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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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:
Do not renumber existing FRs โ append at the end.
Step 5: Confirm before writing
Skip this step when --apply-all is set.
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.
