From 0104fbbebeb25bfe35e65a7fb96ae724e4382a94 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Wed, 5 Aug 2026 11:35:00 -0400 Subject: [PATCH 1/3] Add within-phase understanding checkpoints to attended bugfix workflow Address user feedback about the bugfix workflow racing forward, making broad assumptions, and suffering from compounding misunderstandings across phases. Adds mid-phase checkpoints in assess (after error signature extraction), diagnose (after hypothesis formation), and fix (after reviewing fix strategy) that pause for user confirmation before proceeding to the expensive/irreversible part of each phase. User redirects are evaluated against evidence rather than taken blindly. Unattended mode explicitly skips these checkpoints. Assisted-by: Claude Opus 4.6 (1M) --- bugfix/SKILL.md | 2 +- bugfix/skills/assess.md | 22 ++++++++++++++++++++++ bugfix/skills/diagnose.md | 21 +++++++++++++++++++++ bugfix/skills/fix.md | 22 ++++++++++++++++++++++ bugfix/skills/unattended.md | 4 ++-- 5 files changed, 68 insertions(+), 3 deletions(-) diff --git a/bugfix/SKILL.md b/bugfix/SKILL.md index 234b767..b8e5d5a 100644 --- a/bugfix/SKILL.md +++ b/bugfix/SKILL.md @@ -1,6 +1,6 @@ --- name: bugfix -version: 0.5.0 +version: 0.6.0 description: >- Diagnostic and repair workflow that analyzes error logs, traces root causes, implements fixes, and verifies with regression tests. diff --git a/bugfix/skills/assess.md b/bugfix/skills/assess.md index fa82b40..ab89953 100644 --- a/bugfix/skills/assess.md +++ b/bugfix/skills/assess.md @@ -94,6 +94,28 @@ be determined. | Symptoms | One-line user-visible symptom (e.g., "Save returns 500") | | Environment | OS, browser, version, cluster — only if stated | +### Checkpoint: Confirm Understanding + +Before investing in source-code exploration, pause and present your +understanding to the user: + +- Your 2–3 sentence interpretation of the bug +- The error signature table from Step 3 +- The area of code you plan to investigate based on the bug report, and why + +Then ask the user to confirm or redirect. + +**Handling the response:** + +- **User confirms** — proceed to Step 4. +- **User redirects** ("no, look at X instead") — evaluate the redirect + against the evidence you have. If it aligns, incorporate it and proceed. + If it contradicts what the bug report shows, say so — explain what you + found and why your original direction may be more accurate. Reach + agreement before proceeding. +- **User rejects without a redirect** — ask what to adjust. Do not + proceed past this checkpoint until the user confirms direction. + ### Step 4: Source-Code Exploration Explore the local repository to build source-level context for the bug. This diff --git a/bugfix/skills/diagnose.md b/bugfix/skills/diagnose.md index b7f110b..72f66c9 100644 --- a/bugfix/skills/diagnose.md +++ b/bugfix/skills/diagnose.md @@ -48,6 +48,27 @@ Perform thorough root cause analysis that provides clear, evidence-based conclus - Consider multiple failure modes: logic errors, race conditions, edge cases, missing validation - Document reasoning for each hypothesis +### Checkpoint: Confirm Direction + +Before testing hypotheses, pause and present the hypotheses from Step 4 +to the user: + +- The ranked hypotheses with brief supporting evidence for each +- Which hypothesis you plan to test first and how + +Then ask the user to confirm or redirect. + +**Handling the response:** + +- **User confirms** — proceed to Step 5. +- **User redirects** ("it's actually X") — evaluate the redirect against + the evidence you've gathered. If it aligns, incorporate it and adjust + your hypothesis ranking. If it contradicts what the code shows, say + so — explain your evidence and why you think your original direction may + be more accurate. Reach agreement before proceeding. +- **User rejects without a redirect** — ask what to adjust. Do not + proceed past this checkpoint until the user confirms direction. + ### Step 5: Hypothesis Testing - Add targeted logging or debugging to test hypotheses diff --git a/bugfix/skills/fix.md b/bugfix/skills/fix.md index 107b4b3..81dd017 100644 --- a/bugfix/skills/fix.md +++ b/bugfix/skills/fix.md @@ -26,6 +26,28 @@ Implement targeted bug fixes that resolve the underlying issue without introduci - Plan for backward compatibility if needed - Identify any configuration or migration requirements +### Checkpoint: Confirm Approach + +Before creating a branch or writing any code, pause and present to the +user: + +- The fix approach you plan to take, based on the root cause analysis +- Which files you expect to modify and why +- The expected scope of changes (single function, multiple files, etc.) + +Then ask the user to confirm or redirect. + +**Handling the response:** + +- **User confirms** — proceed to Step 2. +- **User redirects** ("use a different approach" or "fix it in X + instead") — evaluate the redirect against the root cause analysis and + what you see in the code. If it aligns, incorporate it and proceed. If + it contradicts the diagnosis or introduces risk, say so — explain your + reasoning and reach agreement before proceeding. +- **User rejects without a redirect** — ask what to adjust. Do not + proceed past this checkpoint until the user confirms the approach. + ### Step 2: Create Feature Branch - If a branch was specified (e.g. by the user or via the unattended `branch` setting), use it as-is — do not create a new branch diff --git a/bugfix/skills/unattended.md b/bugfix/skills/unattended.md index 587d848..5d75d05 100644 --- a/bugfix/skills/unattended.md +++ b/bugfix/skills/unattended.md @@ -82,8 +82,8 @@ Run these phases in order. Read each skill from the same `skills/` directory: 1. Announce the phase: *"Starting /fix (unattended mode)."* 2. Read the skill file from the table above. While executing it, apply these overrides: - - "Never auto-advance" / "Stop and wait" / "re-read the controller" — - ignore; proceed to the next phase in this table + - "Never auto-advance" / "Stop and wait" / "re-read the controller" / + "Checkpoint: Confirm" sections — ignore; proceed without pausing - "Stop and request human guidance" (escalation) — write an escalation report (see Escalation below) and terminate - "Create Feature Branch" (fix.md Step 2) — skip if `branch` is set or From 8b349e46dbaa4f691c6de8dad084cd02e12d41ac Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Wed, 5 Aug 2026 11:54:19 -0400 Subject: [PATCH 2/3] Separate evidence, assumptions, and unknowns in checkpoint output Each checkpoint now explicitly labels what is grounded in evidence vs. inferred vs. missing, making it easier for the user to spot incorrect assumptions before the AI proceeds. Addresses CodeRabbit review feedback on PR #98. Assisted-by: Claude Opus 4.6 (1M) --- bugfix/skills/assess.md | 7 ++++++- bugfix/skills/diagnose.md | 5 ++++- bugfix/skills/fix.md | 4 ++++ 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/bugfix/skills/assess.md b/bugfix/skills/assess.md index ab89953..57726d2 100644 --- a/bugfix/skills/assess.md +++ b/bugfix/skills/assess.md @@ -99,7 +99,12 @@ be determined. Before investing in source-code exploration, pause and present your understanding to the user: -- Your 2–3 sentence interpretation of the bug +- **Evidence:** what the bug report explicitly states — error messages, + stack traces, reproduction steps, affected component +- **Assumptions:** what you inferred that isn't directly stated — which + code area is likely involved, what the failure mode probably is +- **Unknowns:** what's missing or ambiguous — unclear repro steps, + unspecified environment, vague symptoms - The error signature table from Step 3 - The area of code you plan to investigate based on the bug report, and why diff --git a/bugfix/skills/diagnose.md b/bugfix/skills/diagnose.md index 72f66c9..7a6da97 100644 --- a/bugfix/skills/diagnose.md +++ b/bugfix/skills/diagnose.md @@ -53,7 +53,10 @@ Perform thorough root cause analysis that provides clear, evidence-based conclus Before testing hypotheses, pause and present the hypotheses from Step 4 to the user: -- The ranked hypotheses with brief supporting evidence for each +- The ranked hypotheses, each labeled with: + - **Evidence:** what code analysis or history directly supports it + - **Assumptions:** what you inferred beyond the evidence + - **Unknowns:** what would need to be confirmed to validate it - Which hypothesis you plan to test first and how Then ask the user to confirm or redirect. diff --git a/bugfix/skills/fix.md b/bugfix/skills/fix.md index 81dd017..d0e2cf5 100644 --- a/bugfix/skills/fix.md +++ b/bugfix/skills/fix.md @@ -34,6 +34,10 @@ user: - The fix approach you plan to take, based on the root cause analysis - Which files you expect to modify and why - The expected scope of changes (single function, multiple files, etc.) +- **Assumptions:** any inferences about the fix that aren't directly + established by the diagnosis (e.g., that no other callers are affected, + that backward compatibility is preserved) +- **Risks:** anything that could go wrong with this approach Then ask the user to confirm or redirect. From a802dccd5a1ea334991b444fb76427c38d3f7c31 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Wed, 5 Aug 2026 11:59:09 -0400 Subject: [PATCH 3/3] Add Evidence and Unknowns to fix checkpoint for consistency The fix checkpoint now uses the same four-part structure (Evidence, Assumptions, Unknowns, Risks) as the assess and diagnose checkpoints, so users see a consistent format across all three pause points. Assisted-by: Claude Opus 4.6 (1M) --- bugfix/skills/fix.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/bugfix/skills/fix.md b/bugfix/skills/fix.md index d0e2cf5..b838d47 100644 --- a/bugfix/skills/fix.md +++ b/bugfix/skills/fix.md @@ -34,9 +34,13 @@ user: - The fix approach you plan to take, based on the root cause analysis - Which files you expect to modify and why - The expected scope of changes (single function, multiple files, etc.) +- **Evidence:** findings from the root cause analysis that support this + approach - **Assumptions:** any inferences about the fix that aren't directly established by the diagnosis (e.g., that no other callers are affected, that backward compatibility is preserved) +- **Unknowns:** facts that still need confirmation before or during + implementation - **Risks:** anything that could go wrong with this approach Then ask the user to confirm or redirect.