Keep Vantage docs (PRD, ROADMAP, ARCHITECTURE, UX, specs, DECISIONS, OPEN-QUESTIONS) in sync with a design or code change. Use when changing behaviour, interfaces or decisions, or when editing docs.
Installs into .claude/skills of the current project.
Are you the author of Update Spec?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/ymatrix1-update-spec)
---
name: update-spec
description: Keep Vantage docs (PRD, ROADMAP, ARCHITECTURE, UX, specs, DECISIONS, OPEN-QUESTIONS) in sync with a design or code change. Use when changing behaviour, interfaces or decisions, or when editing docs.
---
# Update a spec
1. **Find the affected docs** using the table in `AGENTS.md` (Sources of truth).
2. **Edit only the sections the change affects.** Keep wording direct and use tables where they help.
3. **Record the decision:**
- Confirmed by the user: add it to `docs/DECISIONS.md` as a section with **Context, Decision, Why, Alternatives, Impact**, `Status: accepted <date>`, `Decided by: user`, and a row in the index.
- Not yet confirmed: same fields with `Status: proposed`, under the "Proposed" section. Never write `accepted` yourself.
- Changing an accepted decision: add a new decision and mark the old one `superseded` with `Superseded by: Dn`. Never edit an accepted decision's text (CI rejects it).
- Number: use the block of decision numbers your brief gave you (see `.agents/rules/docs-and-specs.md`); if you have none, ask the parent.
- Don't record a decision with any field missing; ask for the missing context first.
- If it answers an open question, remove it from `docs/OPEN-QUESTIONS.md`.
4. **Schema changes:** add a numbered file in `packages/daemon/migrations/` (never edit an existing one), a test that upgrades from the previous version, and update `docs/specs/data-schema.md` (see its Migrations section).
5. **Cross-doc consistency:**
- Stage names, flag names and item kinds must match `docs/specs/lifecycle.md` and `docs/specs/work-item-model.md` everywhere.
- If a phase's scope moves or finishes, update `docs/ROADMAP.md` and tick finished checkboxes.
- If goals or scope change, update `docs/PRD.md`, and only with the user's approval.
- New docs are linked from `README.md`.
6. **Checks:**
- Broken relative links: every `](docs/...)` and `](specs/...)` target exists.
- Privacy: no real names, ids, URLs or message content (see `.agents/rules/privacy-boundary.md`).
