tp-docs-update

Docs Update

Propose targeted updates to one or more of the four project docs based on recent work.

Argument: [vision|architecture|roadmap|known-issues] (optional) — update a specific doc. If omitted, reviews all four.

Prerequisites

• At least one of the four docs must exist in three-pillars-docs/. If none exist, suggest running /tp-setup (for vision) or /tp-docs-init (for the other three) first and stop.

Steps

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

2. Validate argument if provided — must be one of vision, architecture, roadmap, known-issues. Reject unknown values.

3. Determine which docs to update: use the argument, or default to all four that exist.

4. For each doc, read the current content and gather recent context:

   • Completed designs in three-pillars-docs/completed-tp-designs/ (read design.md for scope)
   • Active spike results in three-pillars-docs/tp-designs/*/spike-results.md
   • Recent git log (last 20 commits) for changes since doc was last updated
   • Any implementation-audit.md or review.md files with findings

5. Vision update protocol (vision only): Updating three-pillars-docs/vision.md is a higher-stakes edit than the other docs because every downstream TDD skill reads it. Do not propose vision edits automatically from git log or completed designs — a stream of shipped features is not a signal that the why changed. Only propose vision edits when:

   • Recent spike results explicitly concluded the vision needs updating (check spike-results.md for vision callouts)
   • An audit surfaced a MISALIGNMENT finding that the user resolved by deciding the vision was wrong rather than the design
   • The user explicitly invokes /tp-docs-update vision to reconsider the why When proposing vision edits, reopen the Part A conversation from /tp-setup for the affected sections rather than silently rewriting — the user should answer the questions again, not rubber-stamp a diff. Flag downstream impact: list designs whose Vision alignment section would need to be re-checked against the new vision.

6. Review Current Focus (roadmap only): If updating the roadmap and it has a ## Current Focus table, check for staleness — items marked done in Design Inventory but still in Current Focus, blockers that have been resolved, next actions that are outdated. Propose corrections as part of the roadmap edits.

7. Propose specific edits as diff-style before/after blocks:

   • Show the current text that would change
   • Show the proposed replacement
   • Explain why this update is needed Process one doc at a time so the user can approve/reject granularly.

8. On user confirmation, write the changes and follow skills/_shared/living-doc-format.md:

   • Update the *Last updated: YYYY-MM-DD* marker on line 2–3 of the doc to today's date.
   • 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. Do not expand the *Last updated:* line with a prose summary — the summary goes in ## History.

9. Commit the doc updates per skills/_shared/commit-after-work.md. Artifact paths to stage: only the doc files actually modified in step 7 — any of three-pillars-docs/vision.md, three-pillars-docs/architecture.md, three-pillars-docs/product_roadmap.md, three-pillars-docs/known_issues.md, three-pillars-docs/known_issues_resolved.md (when an update resolves an issue, move its entry verbatim to the resolved archive — never mark it resolved in place).