From 4597fdbc4e829b694195c37234610f75c922d24a Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Wed, 18 Mar 2026 11:34:01 -0600 Subject: [PATCH 1/4] fix(code-review): restore actionable review output with interactive choices The March 15 rewrite (PR #2007) removed the ability to auto-fix patches, create action items in story files, and handle deferred/spec findings. This restores interactive post-review actions: - Deferred findings: auto-written to deferred-work.md and checked off in story - Intent gap/bad spec: conversation with downgrade-to-patch, patch-spec, reset-to-ready-for-dev, or dismiss options - Patch findings: fix automatically, create action items, or show details Co-Authored-By: Claude Opus 4.6 (1M context) --- .../bmad-code-review/steps/step-04-present.md | 68 ++++++++++++++----- 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md index 73a6919e2..bcfee3b9c 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md @@ -1,38 +1,70 @@ --- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' --- -# Step 4: Present +# Step 4: Present and Act ## RULES - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` -- Do NOT auto-fix anything. Present findings and let the user decide next steps. +- Deferred findings are handled automatically — no user input needed. +- Patch findings require user choice before acting. +- Intent gap and bad spec findings require a conversation — suggest options but let the user decide. ## INSTRUCTIONS -1. Group remaining findings by category. +### 1. Clean review shortcut -2. Present to the user in this order (include a section only if findings exist in that category): +If zero findings remain after triage (all rejected or none raised): state that and end the workflow. - - **Intent Gaps**: "These findings suggest the captured intent is incomplete. Consider clarifying intent before proceeding." - - List each with title + detail. +### 2. Handle deferred findings automatically - - **Bad Spec**: "These findings suggest the spec should be amended. Consider regenerating or amending the spec with this context:" - - List each with title + detail + suggested spec amendment. +If `defer` findings exist: - - **Patch**: "These are fixable code issues:" - - List each with title + detail + location (if available). +1. Append each to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with severity and description. +2. If `{spec_file}` exists and contains a Tasks/Subtasks section, append each as a checked-off item: + `- [x] [AI-Review][Defer] Description [file:line]` +3. Announce: "**{N} deferred findings** written to deferred-work.md and marked complete in the story file." - - **Defer**: "Pre-existing issues surfaced by this review (not caused by current changes):" - - List each with title + detail. +### 3. Present remaining findings -3. Summary line: **X** intent_gap, **Y** bad_spec, **Z** patch, **W** defer findings. **R** findings rejected as noise. +Group and present in this order (include a section only if findings exist): -4. If clean review (zero findings across all layers after triage): state that N findings were raised but all were classified as noise, or that no findings were raised at all (as applicable). +- **Intent Gaps**: "These findings suggest the captured intent is incomplete." + - List each with title + detail. -5. Offer the user next steps (recommendations, not automated actions): - - If `patch` findings exist: "These can be addressed in a follow-up implementation pass or manually." - - If `intent_gap` or `bad_spec` findings exist: "Consider running the planning workflow to clarify intent or amend the spec before continuing." - - If only `defer` findings remain: "No action needed for this change. Deferred items are noted for future attention." +- **Bad Spec**: "These findings suggest the spec should be amended." + - List each with title + detail + suggested spec amendment. + +- **Patch**: "These are fixable code issues:" + - List each with title + detail + location (if available). + +Summary line: **X** intent_gap, **Y** bad_spec, **Z** patch, **W** defer (auto-handled), **R** rejected as noise. + +### 4. Handle intent gap and bad spec findings + +If `intent_gap` or `bad_spec` findings exist, initiate a conversation: + +1. Present each finding with its detail and the specific spec section it relates to. +2. For each finding (or as a batch if they relate to the same spec section), suggest resolution options: + - **Downgrade to patch** — reclassify as a `patch` finding and handle it with the other patches in step 5. Cheapest option — avoids re-running dev story or create story. + - **Patch the spec** — amend the specific section in `{spec_file}` to address the gap or fix the bad spec language, then continue with implementation. + - **Reset to ready-for-dev** — update the story status back to ready-for-dev so the spec can be reworked and code regenerated from the corrected spec. Most expensive — triggers another full dev cycle. + - **Dismiss** — the finding is not actionable or the spec is correct as-is. +3. For findings that trace upstream of the story file (e.g., a PRD or architecture gap), note this explicitly: "This may originate upstream of the story — consider whether the PRD or architecture docs need a course correction." +4. Let the user decide. Do not auto-apply any spec changes. + +### 5. Handle patch findings + +If `patch` findings exist (including any downgraded from step 4), ask the user: + +> **How would you like to handle the {Z} patch findings?** +> 1. **Fix them automatically** — I will apply fixes now +> 2. **Create action items** — I will add them to the story file for later +> 3. **Show me details** — Let me walk through each one before deciding + +- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made. +- **Option 2**: Add a "Review Follow-ups (AI)" subsection to the Tasks/Subtasks section of `{spec_file}`. For each finding: `- [ ] [AI-Review][{Severity}] {Description} [{file}:{line}]` +- **Option 3**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer options 1 and 2. Workflow complete. From adafd1187bcb63c30f74530b3ccbe6b68cc84802 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Thu, 19 Mar 2026 00:39:45 -0600 Subject: [PATCH 2/4] refactor(code-review): simplify triage to decision-needed/patch/defer/dismiss MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace 5-bucket classification (intent_gap, bad_spec, patch, defer, reject) with 4 pragmatic buckets. Findings always written to story file first. Decision-needed findings gate patch handling — resolve ambiguity before fixing. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../bmad-code-review/steps/step-03-triage.md | 15 +++-- .../bmad-code-review/steps/step-04-present.md | 58 ++++++++----------- 2 files changed, 30 insertions(+), 43 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md index 3e1d21665..0b4dc04f5 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md @@ -30,19 +30,18 @@ - Set `source` to the merged sources (e.g., `blind+edge`). 3. **Classify** each finding into exactly one bucket: - - **intent_gap** -- The spec/intent is incomplete; cannot resolve from existing information. Only possible if `{review_mode}` = `"full"`. - - **bad_spec** -- The spec should have prevented this; spec is wrong or ambiguous. Only possible if `{review_mode}` = `"full"`. - - **patch** -- Code issue that is trivially fixable without human input. Just needs a code change. + - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`. + - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous. - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now. - - **reject** -- Noise, false positive, or handled elsewhere. + - **dismiss** -- Noise, false positive, or handled elsewhere. - If `{review_mode}` = `"no-spec"` and a finding would otherwise be `intent_gap` or `bad_spec`, reclassify it as `patch` (if code-fixable) or `defer` (if not). + If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not). -4. **Drop** all `reject` findings. Record the reject count for the summary. +4. **Drop** all `dismiss` findings. Record the dismiss count for the summary. -5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping rejects AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review. +5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review. -6. If zero findings remain after dropping rejects and no layers failed, note clean review. +6. If zero findings remain after dropping dismissed and no layers failed, note clean review. ## NEXT diff --git a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md index bcfee3b9c..2610207cc 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md @@ -7,64 +7,52 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md' ## RULES - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` -- Deferred findings are handled automatically — no user input needed. -- Patch findings require user choice before acting. -- Intent gap and bad spec findings require a conversation — suggest options but let the user decide. +- Always write findings to the story file before offering action choices. +- Decision-needed findings must be resolved before handling patches. ## INSTRUCTIONS ### 1. Clean review shortcut -If zero findings remain after triage (all rejected or none raised): state that and end the workflow. +If zero findings remain after triage (all dismissed or none raised): state that and end the workflow. -### 2. Handle deferred findings automatically +### 2. Write findings to the story file -If `defer` findings exist: +If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order: -1. Append each to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with severity and description. -2. If `{spec_file}` exists and contains a Tasks/Subtasks section, append each as a checked-off item: - `- [x] [AI-Review][Defer] Description [file:line]` -3. Announce: "**{N} deferred findings** written to deferred-work.md and marked complete in the story file." +1. **Decision needed** findings (unchecked): + `- [ ] [Review][Decision] {Title} — {Detail}` -### 3. Present remaining findings +2. **Patch** findings (unchecked): + `- [ ] [Review][Patch] {Title} [{file}:{line}]` -Group and present in this order (include a section only if findings exist): +3. **Defer** findings (checked off, marked deferred): + `- [x] [Review][Defer] {Title} [{file}:{line}] — deferred, pre-existing` -- **Intent Gaps**: "These findings suggest the captured intent is incomplete." - - List each with title + detail. +Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description. -- **Bad Spec**: "These findings suggest the spec should be amended." - - List each with title + detail + suggested spec amendment. +### 3. Present summary -- **Patch**: "These are fixable code issues:" - - List each with title + detail + location (if available). +Announce what was written: -Summary line: **X** intent_gap, **Y** bad_spec, **Z** patch, **W** defer (auto-handled), **R** rejected as noise. +> **Code review complete.** {D} decision-needed, {P} patch, {W} deferred, {R} dismissed as noise. +> Findings written to the review findings section in `{spec_file}`. -### 4. Handle intent gap and bad spec findings +### 4. Resolve decision-needed findings -If `intent_gap` or `bad_spec` findings exist, initiate a conversation: - -1. Present each finding with its detail and the specific spec section it relates to. -2. For each finding (or as a batch if they relate to the same spec section), suggest resolution options: - - **Downgrade to patch** — reclassify as a `patch` finding and handle it with the other patches in step 5. Cheapest option — avoids re-running dev story or create story. - - **Patch the spec** — amend the specific section in `{spec_file}` to address the gap or fix the bad spec language, then continue with implementation. - - **Reset to ready-for-dev** — update the story status back to ready-for-dev so the spec can be reworked and code regenerated from the corrected spec. Most expensive — triggers another full dev cycle. - - **Dismiss** — the finding is not actionable or the spec is correct as-is. -3. For findings that trace upstream of the story file (e.g., a PRD or architecture gap), note this explicitly: "This may originate upstream of the story — consider whether the PRD or architecture docs need a course correction." -4. Let the user decide. Do not auto-apply any spec changes. +If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed. ### 5. Handle patch findings -If `patch` findings exist (including any downgraded from step 4), ask the user: +If `patch` findings exist (including any resolved from step 4), ask the user: > **How would you like to handle the {Z} patch findings?** > 1. **Fix them automatically** — I will apply fixes now -> 2. **Create action items** — I will add them to the story file for later -> 3. **Show me details** — Let me walk through each one before deciding +> 2. **Leave as action items** — they are already in the story file +> 3. **Walk through each** — let me show details before deciding -- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made. -- **Option 2**: Add a "Review Follow-ups (AI)" subsection to the Tasks/Subtasks section of `{spec_file}`. For each finding: `- [ ] [AI-Review][{Severity}] {Description} [{file}:{line}]` +- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made and check off the items in the story file. +- **Option 2**: Done — findings are already written to the story. - **Option 3**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer options 1 and 2. Workflow complete. From 097c4ec5c1b1ce40a4516b390449f0d7ff4a2c01 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Thu, 19 Mar 2026 15:49:44 -0600 Subject: [PATCH 3/4] fix(code-review): address PR review findings in step-04-present Replace undefined curly-brace placeholders with angle-bracket syntax, add HALT guard before patch menu, guard spec_file references for no-spec mode, and backtick category names for consistency. --- .../bmad-code-review/steps/step-04-present.md | 42 ++++++++++++------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md index 2610207cc..168f316bb 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md @@ -7,8 +7,8 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md' ## RULES - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` -- Always write findings to the story file before offering action choices. -- Decision-needed findings must be resolved before handling patches. +- When `{spec_file}` is set, always write findings to the story file before offering action choices. +- `decision-needed` findings must be resolved before handling `patch` findings. ## INSTRUCTIONS @@ -20,14 +20,14 @@ If zero findings remain after triage (all dismissed or none raised): state that If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order: -1. **Decision needed** findings (unchecked): - `- [ ] [Review][Decision] {Title} — {Detail}` +1. **`decision-needed`** findings (unchecked): + `- [ ] [Review][Decision] — <Detail>` -2. **Patch** findings (unchecked): - `- [ ] [Review][Patch] {Title} [{file}:{line}]` +2. **`patch`** findings (unchecked): + `- [ ] [Review][Patch] <Title> [<file>:<line>]` -3. **Defer** findings (checked off, marked deferred): - `- [x] [Review][Defer] {Title} [{file}:{line}] — deferred, pre-existing` +3. **`defer`** findings (checked off, marked deferred): + `- [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing` Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description. @@ -35,24 +35,34 @@ Also append each `defer` finding to `{deferred_work_file}` under a heading `## D Announce what was written: -> **Code review complete.** {D} decision-needed, {P} patch, {W} deferred, {R} dismissed as noise. -> Findings written to the review findings section in `{spec_file}`. +> **Code review complete.** <D> `decision-needed`, <P> `patch`, <W> `defer`, <R> dismissed as noise. + +If `{spec_file}` is set, add: `Findings written to the review findings section in {spec_file}.` +Otherwise add: `Findings are listed above. No story file was provided, so nothing was persisted.` ### 4. Resolve decision-needed findings If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed. -### 5. Handle patch findings +### 5. Handle `patch` findings -If `patch` findings exist (including any resolved from step 4), ask the user: +If `patch` findings exist (including any resolved from step 4), HALT. Ask the user: -> **How would you like to handle the {Z} patch findings?** +If `{spec_file}` is set, present all three options: + +> **How would you like to handle the <Z> `patch` findings?** > 1. **Fix them automatically** — I will apply fixes now > 2. **Leave as action items** — they are already in the story file > 3. **Walk through each** — let me show details before deciding -- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made and check off the items in the story file. -- **Option 2**: Done — findings are already written to the story. -- **Option 3**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer options 1 and 2. +If `{spec_file}` is **not** set, present only options 1 and 3 (omit option 2 — findings were not written to a file): + +> **How would you like to handle the <Z> `patch` findings?** +> 1. **Fix them automatically** — I will apply fixes now +> 2. **Walk through each** — let me show details before deciding + +- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the items in the story file. +- **Option 2** (only when `{spec_file}` is set): Done — findings are already written to the story. +- **Walk through each**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above. Workflow complete. From 9c3e2804ab63e2eedd1043e1ab644f708e911955 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky <alexey.verkhovsky@gmail.com> Date: Thu, 19 Mar 2026 16:57:49 -0600 Subject: [PATCH 4/4] feat(code-review): add HALT guards, batch option, defer reason, final summary Add strong HALT guards after decision-needed and patch menus to prevent auto-progression. Add batch-apply option 0 for >3 patch findings. Prompt for defer reason and append to story file and deferred-work.md. Show boxed final summary with counts. Polish clean-review shortcut in triage. --- .../bmad-code-review/steps/step-03-triage.md | 2 +- .../bmad-code-review/steps/step-04-present.md | 22 ++++++++++++++++--- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md index 0b4dc04f5..6bb2635db 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md @@ -41,7 +41,7 @@ 5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review. -6. If zero findings remain after dropping dismissed and no layers failed, note clean review. +6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.) ## NEXT diff --git a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md index 168f316bb..799f05fe9 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md @@ -44,25 +44,41 @@ Otherwise add: `Findings are listed above. No story file was provided, so nothin If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed. +If the user chooses to defer, ask: Quick one-line reason for deferring this item? (helps future reviews): — then append that reason to both the story file bullet and the `{deferred_work_file}` entry. + +**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option. + ### 5. Handle `patch` findings If `patch` findings exist (including any resolved from step 4), HALT. Ask the user: -If `{spec_file}` is set, present all three options: +If `{spec_file}` is set, present all three options (if >3 `patch` findings exist, also show option 0): > **How would you like to handle the <Z> `patch` findings?** +> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many) > 1. **Fix them automatically** — I will apply fixes now > 2. **Leave as action items** — they are already in the story file > 3. **Walk through each** — let me show details before deciding -If `{spec_file}` is **not** set, present only options 1 and 3 (omit option 2 — findings were not written to a file): +If `{spec_file}` is **not** set, present only options 1 and 3 (omit option 2 — findings were not written to a file). If >3 `patch` findings exist, also show option 0: > **How would you like to handle the <Z> `patch` findings?** +> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many) > 1. **Fix them automatically** — I will apply fixes now > 2. **Walk through each** — let me show details before deciding +**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option. + +- **Option 0** (only when >3 findings): Apply all non-controversial patches without per-finding confirmation. Skip any finding that requires judgment. Present a summary of changes made and any skipped findings. - **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the items in the story file. - **Option 2** (only when `{spec_file}` is set): Done — findings are already written to the story. - **Walk through each**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above. -Workflow complete. + **HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option. + +**✅ Code review actions complete** + +- Decision-needed resolved: <D> +- Patches handled: <P> +- Deferred: <W> +- Dismissed: <R>