Reconcile PRD requirements with a story-audit drift report. Use when marking PRD entries implemented/partial/missing, or promoting code-only stories into the PRD.
Reconcile PRD requirements with a story-audit drift report. Use when marking PRD entries implemented/partial/missing, or promoting code-only stories into the PRD.
Apply the drift findings from /blueprint:story-audit back to the PRDs. Adds status markers, a Known Drift section, and (with consent) promotes candidate stories. Does not delete unimplemented requirements — they remain the roadmap.
When EFFECTIVE_INTERACTION_MODE=quietand this invocation was
automation-initiated (autopilot, session bookend, drift-nudge follow-up — not
a slash command the user typed), skip closing navigation menus ("what next?" /
"create another?" style): apply the safe default and end with a one-line
receipt instead. Quiet mode never skips confirmation gates that guard writes —
only navigation menus. A direct user invocation always behaves fully
interactively (explicit intent overrides quiet; see ADR-0020).
Execution
Execute this PRD-reconciliation workflow.
Step 1: Locate the audit artifact
If --audit <path> provided, read that file.
Otherwise, list docs/blueprint/audits/*-story-audit.md, pick the lexicographically last one (date-stamped names sort correctly).
If none found → abort with: "No audit artifact found. Run /blueprint:story-audit first."
Step 2: Parse the drift report
Read the audit's Drift Report section (Section 4 in the canonical template). Extract every row into a structured list:
Skip ✅ implemented rows — they're informational; reconcile only adds value for ⚠️, ❌, and 🆕.
If the audit also has a Story Inventory → Candidate section, merge those rows into the 🆕 group with their entry-point evidence.
Step 3: Group edits by PRD
For each non-✅ drift entry, determine the target PRD:
Status
Target PRD
⚠️ partial / ❌ missing
The PRD whose prd_ref matches the entry (e.g. FR-2.3 → docs/prds/PRD-002.md)
🆕 candidate
Ask the user which PRD to promote into; if no PRD covers the area, suggest creating a stub via /blueprint:derive-plans
If --prd <path> is set, drop entries whose target PRD doesn't match.
Step 4: Plan edits per PRD
For each target PRD, plan two kinds of edit:
A. Inline status markers for ⚠️ and ❌ entries — locate the line containing the requirement (search by prd_ref or substring of capability) and prepend the marker to the requirement line:
- FR-2.3 OCR support → server runs tesseract over uploads
becomes
- ❌ FR-2.3 OCR support → server runs tesseract over uploads (drift: dep declared but never imported)
B. A "Known Drift" appendix at the bottom of the PRD, in this exact format (idempotent — replace the section if it already exists):
## Known Drift> Tracked by audit: `docs/blueprint/audits/<YYYY-MM-DD>-story-audit.md`
| Status | Requirement | Evidence | Action |
|--------|-------------|----------|--------|
| ❌ | FR-2.3 OCR support | dep `tesseract` declared but never imported | <work-orderidor "open"> |
| ⚠️ | FR-1.4 deskew on import | implemented but only for landscape orientation | open |
For 🆕 candidate entries (Step 3 mapped them to a PRD): append a new requirement row at the end of the relevant FR section, with explicit text:
For each PRD, show the planned edits as a unified diff and ask via AskUserQuestion:
Apply all edits to this PRD — proceed
Apply some edits — show each row individually for accept/skip
Skip this PRD — no edits land
Cancel reconcile entirely — exit with no changes
If --dry-run is set, print the diffs and exit without prompting.
Step 6: Apply edits
For each accepted edit, use the Edit tool to modify the PRD. Keep edits idempotent: re-running this skill against the same audit + same PRD must produce no further changes (the inline marker is already there; the Known Drift table already reflects the same rows).
After all PRD edits land:
git status --porcelain=v2 docs/prds/
If any non-PRD file shows up as modified → abort and report. This skill must only touch PRDs.
Choose <scope> as the PRD prefix shared by edits (e.g. prd-001) or omit if multiple PRDs were touched.
Step 9: Hand off the next action
Use AskUserQuestion to surface the obvious follow-on:
Open work-orders for ❌ entries → recommend the user run /blueprint:work-order per Tier-3 row (a user-invocable command — surface it for the user to run, don't invoke it via the Skill tool)
Re-run the audit to confirm green → invoke /blueprint:story-audit
I'm done → exit
What this skill deliberately does NOT do
Off-limits
Why
Edit source code
Code changes go through /blueprint:work-order so the change has a TDD packet behind it
Delete unimplemented requirements
They are the roadmap. ❌ is a tracked status, not a delete signal.
Auto-create GitHub issues for drift
Audit + reconcile are local artifacts; issue filing is an explicit user action
Renumber FRs to "tidy up"
FR numbers are referenced from tests, commits, and other PRDs — renumbering is an unsafe, non-idempotent edit
Commit changes
Commit boundaries are the user's decision; this skill prints the suggested message and stops
Idempotency
Re-running this skill against the same audit + same PRDs must be a no-op. The two mechanisms:
Inline status markers (⚠️ , ❌ , 🆕 ) are detected before insertion. If the requirement line already starts with the right marker, skip.
The ## Known Drift section is replaced wholesale by the new content, never appended.
If a re-run produces changes, that is a bug — file it.
