get-shit-done/workflows/audit-milestone.md
<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>
<available_agent_types> Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
INIT=$(gsd-sdk query init.milestone-op)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS_CHECKER=$(gsd-sdk query agent-skills gsd-integration-checker)
Extract from init JSON: milestone_version, milestone_name, phase_count, completed_phases, commit_docs.
Resolve integration checker model:
integration_checker_model=$(gsd-sdk query resolve-model gsd-integration-checker --raw)
# Get phases in milestone (sorted numerically, handles decimals)
gsd-sdk query phases.list
For each phase directory, read the VERIFICATION.md:
# For each phase, use find-phase to resolve the directory (handles archived phases)
PHASE_INFO=$(gsd-sdk query find-phase 01 --raw)
# Extract directory from JSON, then read VERIFICATION.md from that directory
# Repeat for each phase number from ROADMAP.md
From each VERIFICATION.md, extract:
If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.
With phase context collected:
Extract MILESTONE_REQ_IDS from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.
Agent(
prompt="Check cross-phase integration and E2E flows.
Phases: {phase_dirs}
Phase exports: {from SUMMARYs}
API routes: {routes created}
Milestone Requirements:
{MILESTONE_REQ_IDS — list each REQ-ID with description and assigned phase}
MUST map each integration finding to affected requirement IDs where applicable.
Verify cross-phase wiring and E2E user flows.
${AGENT_SKILLS_CHECKER}",
subagent_type="gsd-integration-checker",
model="{integration_checker_model}"
)
ORCHESTRATOR RULE — CODEX RUNTIME: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
Combine:
MUST cross-reference three independent sources for each requirement:
Extract all REQ-IDs mapped to milestone phases from the traceability table:
[x] vs [ ])For each phase's VERIFICATION.md, extract the expanded requirements table:
For each phase's SUMMARY.md, extract requirements-completed from YAML frontmatter:
for summary in .planning/phases/*-*/*-SUMMARY.md; do
[ -e "$summary" ] || continue
gsd-sdk query summary-extract "$summary" --fields requirements_completed --pick requirements_completed
done
For each REQ-ID, determine status using all three sources:
| VERIFICATION.md Status | SUMMARY Frontmatter | REQUIREMENTS.md | → Final Status |
|---|---|---|---|
| passed | listed | [x] | satisfied |
| passed | listed | [ ] | satisfied (update checkbox) |
| passed | missing | any | partial (verify manually) |
| gaps_found | any | any | unsatisfied |
| missing | listed | any | partial (verification gap) |
| missing | missing | any | unsatisfied |
REQUIRED: Any unsatisfied requirement MUST force gaps_found status on the milestone audit.
Orphan detection: Requirements present in REQUIREMENTS.md traceability table but absent from ALL phase VERIFICATION.md files MUST be flagged as orphaned. Orphaned requirements are treated as unsatisfied — they were assigned but never verified by any phase.
Skip if workflow.nyquist_validation is explicitly false (absent = enabled).
NYQUIST_CONFIG=$(gsd-sdk query config-get workflow.nyquist_validation --raw 2>/dev/null)
If false: skip entirely.
For each phase directory, check *-VALIDATION.md. If exists, parse frontmatter (nyquist_compliant, wave_0_complete).
Classify per phase:
| Status | Condition |
|---|---|
| COMPLIANT | nyquist_compliant: true and all tasks green |
| PARTIAL | VALIDATION.md exists, nyquist_compliant: false or red/pending |
| MISSING | No VALIDATION.md |
Add to audit YAML: nyquist: { compliant_phases, partial_phases, missing_phases, overall }
Discovery only — never auto-calls /gsd-validate-phase.
Create .planning/v{version}-v{version}-MILESTONE-AUDIT.md with:
---
milestone: {version}
audited: {timestamp}
status: passed | gaps_found | tech_debt
scores:
requirements: N/M
phases: N/M
integration: N/M
flows: N/M
gaps: # Critical blockers
requirements:
- id: "{REQ-ID}"
status: "unsatisfied | partial | orphaned"
phase: "{assigned phase}"
claimed_by_plans: ["{plan files that reference this requirement}"]
completed_by_plans: ["{plan files whose SUMMARY marks it complete}"]
verification_status: "passed | gaps_found | missing | orphaned"
evidence: "{specific evidence or lack thereof}"
integration: [...]
flows: [...]
tech_debt: # Non-critical, deferred
- phase: 01-auth
items:
- "TODO: add rate limiting"
- "Warning: no password strength validation"
- phase: 03-dashboard
items:
- "Deferred: mobile responsive layout"
---
Plus full markdown report with tables for requirements, phases, integration, tech debt.
Status values:
passed — all requirements met, no critical gaps, minimal tech debtgaps_found — critical blockers existtech_debt — no blockers but accumulated deferred items need reviewRoute by status (see <offer_next>).
<offer_next> Output this markdown directly (not as a code block). Route based on status:
If passed:
Score: {N}/{M} requirements satisfied Report: .planning/v{version}-MILESTONE-AUDIT.md
All requirements covered. Cross-phase integration verified. E2E flows complete.
───────────────────────────────────────────────────────────────
Complete milestone — archive and tag
/clear then:
/gsd-complete-milestone {version}
───────────────────────────────────────────────────────────────
If gaps_found:
Score: {N}/{M} requirements satisfied Report: .planning/v{version}-MILESTONE-AUDIT.md
{For each unsatisfied requirement:}
{For each integration gap:}
{For each flow gap:}
| Phase | VALIDATION.md | Compliant | Action |
|---|---|---|---|
| {phase} | exists/missing | true/false/partial | /gsd-validate-phase {N} |
Phases needing validation: run /gsd-validate-phase {N} for each flagged phase.
───────────────────────────────────────────────────────────────
Close the gaps inline — gap planning happens as part of this audit's output (see the Unsatisfied Requirements, Cross-Phase Issues, Broken Flows, and Nyquist Coverage sections above). Insert one closure phase per gap (or per group of related gaps) using the standard phase chain:
/clear then:
/gsd-phase --insert <N> "Close gap: <REQ-ID> — <description>" /gsd-discuss-phase <N> /gsd-plan-phase <N> /gsd-execute-phase <N>
For Nyquist-coverage gaps flagged in the table above, prefer running
/gsd-validate-phase <N> for each flagged phase (and /gsd-secure-phase <N> if SECURITY.md was flagged) before inserting a new closure phase —
they may close the gap retroactively without a new phase.
───────────────────────────────────────────────────────────────
Also available:
───────────────────────────────────────────────────────────────
If tech_debt (no blockers but accumulated debt):
Score: {N}/{M} requirements satisfied Report: .planning/v{version}-MILESTONE-AUDIT.md
All requirements met. No critical blockers. Accumulated tech debt needs review.
{For each phase with debt:} Phase {X}: {name}
───────────────────────────────────────────────────────────────
A. Complete milestone — accept debt, track in backlog
/gsd-complete-milestone {version}
B. Plan a cleanup phase — address the debt above before completing. Insert a closure phase using the standard chain:
/clear then:
/gsd-phase --insert <N> "Address tech debt: <area>" /gsd-discuss-phase <N> /gsd-plan-phase <N> /gsd-execute-phase <N>
─────────────────────────────────────────────────────────────── </offer_next>
<success_criteria>
requirements-completed frontmatter extracted for each phase