Draft Assist Review: Human-in-the-Loop Gateway

Help human reviewers effectively review an executed track without shifting the entire cognitive burden onto them.

Red Flags - STOP if you're

• Conducting standard unit tests; use /draft:review for that.
• Fixing code rather than explaining logic and risk profiles to the human.
• Reviewing output without first summarizing the source spec.md intent.

Workflow Constraints

1. Context Extraction:
   • Load the track's spec.md and plan.md.
   • Load the track's hld.md and lld.md if present — extract Key Design Decisions, Alternatives Considered, and (LLD) class invariants and error policies.
   • Re-summarize the Intent of what this track was supposed to achieve in exactly two sentences.
2. Blast Radius Isolation:
   • Scan the git diff generated by the target track.
   • Separate trivial edits (naming, routing adjustments, formatting) from Structural Edits (schema updates, concurrency alterations, middleware auth changes, API surface changes).
   • Present structural edits first — these are where review time should be spent.
3. Generate the Human Helper Guide:
   • Instead of a traditional bug hunt, generate an executive summary containing a Risk Assessment.
   • For each structural edit, cite the originating decision: "I chose [Pattern] for [File/Function] because hld.md §Key Design Decisions / Alternatives Considered selected it over [rejected alternative]. You should specifically scrutinize lines X–Y because they touch [global state / auth boundary / shared schema]." Fall back to architecture.md only when no HLD exists.
   • Highlight any code that violates an LLD §Classes and Interfaces invariant (thread safety, idempotency, ordering) or contradicts an HLD §Checklist claim (e.g., "code introduces a new shared mutex but HLD declared single-writer").
   • Highlight any code that touches shared state, auth boundaries, data persistence, or concurrency.
4. Knowledge Base Verification:
   • Verify if any pattern implemented violates the draft/guardrails.md learned anti-patterns.
   • Verify the diff is consistent with hld.md/lld.md commitments. If the diff makes structural changes not reflected in HLD §Detailed Design or LLD §Classes/Interfaces: flag for the reviewer that HLD/LLD must be amended (/draft:change) before merge.
   • If so, specifically direct the human reviewer to veto the change unless an ADR is created via /draft:adr.
5. Output Format:
   • Track Intent (2 sentences)
   • HLD/LLD Decision Trace (per structural edit: which §Key Design Decision or §Alternatives Considered row drove this code; or "no HLD justification — reviewer must request one")
   • Structural Edits (table: file, change type, risk level, review guidance)
   • Trivial Edits (collapsed list — skim only)
   • HLD/LLD Drift (diff makes claims that HLD/LLD does not document — recommend /draft:change)
   • Guardrail Violations (if any — with ADR recommendation)
   • Suggested Review Order (which files to review first, based on blast radius)