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..57726d2 100644 --- a/bugfix/skills/assess.md +++ b/bugfix/skills/assess.md @@ -94,6 +94,33 @@ 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: + +- **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 + +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..7a6da97 100644 --- a/bugfix/skills/diagnose.md +++ b/bugfix/skills/diagnose.md @@ -48,6 +48,30 @@ 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, 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. + +**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..b838d47 100644 --- a/bugfix/skills/fix.md +++ b/bugfix/skills/fix.md @@ -26,6 +26,36 @@ 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.) +- **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. + +**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