Entropyk/.agents/skills/bmad-quick-dev/step-04-review.md

deferred_work_file

deferred_work_file
{implementation_artifacts}/deferred-work.md

Step 4: Review

RULES

• YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}
• All review subagents must run at the same model capability as the current session.

INSTRUCTIONS

Change {spec_file} status to in-review in the frontmatter before continuing.

Construct Diff

Read {baseline_commit} from {spec_file} frontmatter. If {baseline_commit} is missing or NO_VCS, use best effort to determine what changed. Otherwise, construct {diff_output} covering all changes — tracked and untracked — since {baseline_commit}.

Do NOT git add anything — this is read-only inspection.

Review

Launch Blind Hunter and Edge Case Hunter in parallel without prior conversation context. If no subagents are available, generate two review prompt files in {implementation_artifacts} — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.

• Blind Hunter — prompt:

  Invoke the bmad-review-adversarial-general skill on this diff:

  {diff_output}

• Edge Case Hunter — prompt:

  Invoke the bmad-review-edge-case-hunter skill on this diff:

  {diff_output}

Classify

1. Deduplicate all review findings.
2. Assign severity to each finding by consequence for the artifact's main consumer (software user, document reader, etc). Disregard any severity assigned by a reviewing subagent. Review subagents operate under by-design information asymmetry and do not have enough context to set final severity for this workflow.
   • low: none or cosmetic
   • medium: tolerable
   • high: intolerable
3. Route each finding into exactly one triage category. The first three categories are this story's problem — caused or exposed by the current change. The last two are not this story's problem.
   • intent_gap — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
   • bad_spec — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
   • patch — caused by the change; trivially fixable without human input. Just part of the diff.
   • defer — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
   • reject — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
4. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each loopback, read {spec_file} frontmatter review_loop_iteration (missing means 0), increment it by 1, and write it back. If it exceeds 5, HALT and escalate to the human.
   • intent_gap — Root cause is inside <frozen-after-approval>. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow ./step-02-plan.md to re-run steps 2–4.
   • bad_spec — Root cause is outside <frozen-after-approval>. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the ## Spec Change Log in {spec_file} and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow ./step-03-implement.md to re-derive the code, then this step will run again.
   • patch — Auto-fix. These are the only findings that survive loopbacks.
   • defer — Append one new entry to {deferred_work_file} using this format. Do not modify existing entries or look for duplicates.

     - source_spec: `{spec_file}`
       summary: <one sentence>
       evidence: <why this is real>
     

   • reject — Drop silently.

NEXT

Read fully and follow ./step-05-present.md