Read a completed design's artifacts and synthesize what was built into proposed updates for project docs and downstream designs.
-
Run first-run preflight per skills/_shared/first-run.md.
-
Validate {design-name} per skills/_shared/validate-name.md.
-
Locate the design directory: check three-pillars-docs/tp-designs/{design-name}/ first, then three-pillars-docs/completed-tp-designs/{design-name}/.
-
Read the full design directory: design.md, detailed-design.md, plan.md, implementation-audit.md, and any review.md files.
-
Read project docs per skills/_shared/read-project-docs.md.
-
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.
-
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.
-
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.
-
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.
The same verify_learn.py run also surfaces stale invariant-number citations in the design's touched prose files (any file changed within the diff range that cites an invariant #N where N is not a live invariant number in framework-check.sh). These appear alongside the retired-symbol refs in the JSON output. Treat any stale-cite hit as an advisory repair prompt — update the prose to reference a live invariant or remove the stale number — but never block on it (the helper always exits 0, fail-open).
Also run python3 "$TP_ROOT"/skills/_shared/citation_liveness.py --repo . --remote --json and fold any DeadCite or StaleRow hits into the step-7 doc updates. Advisory only — exits 0, fail-open offline; never block on it.
-
Scan for affected sibling designs: Read all design.md files under three-pillars-docs/tp-designs/ (excluding the current design). Match key concepts — new modules, changed interfaces, architecture decisions from implementation-audit.md or detailed-design.md — against each design's Scope and Entities sections. For each affected design, also check whether its declared dependencies include the current design — if so, note whether those dependency requirements are now satisfied. List affected designs with an explanation of what needs updating.
When an affected sibling is an archived design whose documented behavior this design changed, propose the dated amendment per skills/_shared/reconcile-protocol.md. In --auto: apply the amendment and log to decisions.md with Confidence per auto-mode.md rules.
-
Vision drift check (do not auto-propose vision edits): Compare what was actually built against three-pillars-docs/vision.md. Does the implementation contradict a stated principle or non-goal? Does it serve the stated problem in a way the vision didn't anticipate? If you find a genuine tension — not a stylistic mismatch — flag it to the user with a specific citation (which implementation detail, which vision bullet) and recommend /tp-docs-update vision as an explicit follow-up. Do not propose vision edits directly from this skill. The sticky-vision principle exists to prevent post-hoc rationalization: shipped features are not evidence the vision changed.
-
Commit the doc updates per skills/_shared/commit-after-work.md. Artifact paths to stage (include only those actually modified in steps 5–9):
three-pillars-docs/product_roadmap.mdthree-pillars-docs/architecture.mdthree-pillars-docs/known_issues.mdthree-pillars-docs/known_issues_resolved.md (when this learn resolves an issue, move its entry verbatim from known_issues.md to this archive — never mark it resolved in place)
Do NOT stage three-pillars-docs/vision.md — this skill never auto-edits vision. Commit message: Learn: {design-name} design.
-
Report: Summarize what was updated, what designs are affected, any vision tensions flagged, and suggest /tp-design-complete {design-name} as the next step.
