tp-design-learn

Design Learn

Read a completed design's artifacts and synthesize what was built into proposed updates for project docs and downstream designs.

Argument: {design-name} (required) — must match an existing directory under three-pillars-docs/tp-designs/ or three-pillars-docs/completed-tp-designs/.

Prerequisites

• design.md and implementation-audit.md (or at minimum plan.md with all tasks Done) must exist. If not, tell the user what's missing and stop.

Steps

1. Run first-run preflight per skills/_shared/first-run.md.

2. Validate {design-name} per skills/_shared/validate-name.md.

3. Locate the design directory: check three-pillars-docs/tp-designs/{design-name}/ first, then three-pillars-docs/completed-tp-designs/{design-name}/.

4. Read the full design directory: design.md, detailed-design.md, plan.md, implementation-audit.md, and any review.md files.

5. Read project docs per skills/_shared/read-project-docs.md.

6. Update Design Inventory in product_roadmap.md: If the roadmap has a Design Inventory table, find the row for {design-name} and propose updating its status to a short label + link per skills/_shared/living-doc-format.md (e.g., Done — PR #NN — [design](completed-tp-designs/…/design.md)). If the design is NOT in the table (was created before roadmap registration existed), propose adding a row. Keep the What and Status cells short — narrative belongs in the linked design or seed. Show the proposed change and get user confirmation.

7. Update Current Focus in product_roadmap.md: If the roadmap has a ## Current Focus table, propose changes:

   • Remove the completed design's row from Current Focus (it's done).
   • Update "Blocked By" on any row that listed this design as a blocker — clear the blocker if this was the only one.
   • Promote the next logical item if removing this row leaves a priority gap. Look at the Design Inventory for designs whose dependencies are now satisfied.
   • Update "Next Action" on any row whose next step changed because this design completed (e.g., a dependent design can now proceed to /tp-design-detail). Show the proposed Current Focus table and get user confirmation.

8. Propose updates for each doc that needs changes, following the pattern in skills/_shared/propose-doc-edits.md. Explain why the completed design motivates each change. For each living doc edited, follow skills/_shared/living-doc-format.md:

   • Update the *Last updated: YYYY-MM-DD* date on line 2–3.
   • Append one dated line at the top of the ## History section (newest-first): - YYYY-MM-DD — one-sentence summary. Keep it under 800 non-ws chars.

9. Learn-verification (advisory): run python3 "$TP_ROOT"/skills/_shared/verify_learn.py --range {default}...tp/{design-name} --json (where {default} is the base branch — usually master). It reports three-pillars-docs/** lines (living and completed-tp-designs/) that still name a symbol or file this design retired (deleted/renamed in the diff) — the "learn ran ≠ docs match as-built" gap. Treat any hit as a propagation miss: fold the scrub into the step-7 doc updates. Advisory only — the helper always exits 0 and fails open; never block on it. Surface any remaining hits in the step-12 report (and, in --auto, append them to decisions.md). Range note: {default}...tp/{design-name} (three-dot) diffs merge-base→tp/{design-name}, surfacing this design's deletions — not tp/{design-name}...{default}, which would surface the wrong (base) side.