Afc:debug

/afc:debug — Bug Diagnosis and Fix

> Analyzes the root cause of a bug and fixes it. > Validates the safety and accuracy of the fix with convergence-based Critic Loop.

Arguments

• $ARGUMENTS — (required) Bug description, error message, or reproduction steps

Project Config (auto-loaded)

!cat .claude/afc.config.md 2>/dev/null || echo "[CONFIG NOT FOUND] .claude/afc.config.md not found. Create it with /afc:init."

Execution Steps

1. Gather Information

1. Extract from $ARGUMENTS:

• Symptom: what is going wrong?
• Reproduction conditions: when does it occur?
• Error message: full text if available
• Expected behavior: what should happen?

1. Ask user for additional information if needed (max 2 questions)

2. Root Cause Analysis (RCA)

Proceed in order, applying adaptive skipping based on symptom type:

1. Error trace: extract file:line from error message/stack trace → read that code
2. Data flow: trace backwards from the problem point (where did the bad data come in?) — skip if error trace already identifies root cause with high confidence
3. State analysis: check relevant state management cache state (from Project Context) — skip if bug is clearly a syntax/type/null-reference error with no state involvement
4. Recent changes: check recent changes with git log --oneline -10 -- {related files} — skip if bug is clearly pre-existing (user reports it "always" fails)
5. Race conditions: check for timing issues between async operations — skip if bug is deterministic (same input always fails, no async/concurrent context)

When skipping a step, note: "Skipped: {reason}". Do not skip steps 1 and 2 unless step 1 alone identifies the root cause.

3. Form Hypotheses

List possible causes as a hypothesis list:

### Hypotheses
0. **[Not a Bug?]** {intended behavior explanation}: {evidence from docs/code/spec}
1. **[High probability]** {cause1}: {evidence}
2. **[Medium probability]** {cause2}: {evidence}
3. **[Low probability]** {cause3}: {evidence}

Always evaluate hypothesis 0 first. Check:

• Is this behavior documented or specified? (README, comments, spec, CLAUDE.md)
• Does the code explicitly handle this case? (intentional logic, not missing logic)
• Is the user's expectation based on a misunderstanding of the design?

If hypothesis 0 is confirmed (not a bug):

• Report: "This appears to be intended behavior: {explanation with evidence}."
• Do not modify code. Suggest documentation improvement if the behavior is non-obvious.
• Skip Steps 4-6. Go directly to Final Output with verdict: "Not a bug — intended behavior."

If hypothesis 0 is rejected: verify remaining hypotheses starting from highest probability.

4. Implement Fix

Precondition: Only proceed if a genuine bug was confirmed in Step 3 (hypothesis 0 rejected).

1. Minimal change principle: change only the minimum code required to fix the bug
2. Impact analysis: verify what effect the fix has on other code
3. Apply fix

5. Critic Loop

> Always read ${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md first and follow it.

Run the critic loop until convergence. Safety cap: 5 passes.

Fast-path: If the fix is a single-line change (null guard, typo, missing import) with no behavioral side effects: run 1 pass with both criteria. If both PASS on the first pass, converge immediately without adversarial challenge.

| Criterion | Validation | |-----------|------------| | SAFETY | Does the fix break any other functionality? Any side effects? | | CORRECTNESS | Does it actually resolve the root cause? Or just mask the symptom? |

Follow verdict handling and output format per docs/critic-loop-rules.md.

6. Verification

{config.gate}

Retry after fixing on failure (max 3 attempts).

7. Retrospective Entry (if new pattern found)

If this debug session reveals a pattern not previously documented in .claude/afc/memory/retrospectives/:

Append to .claude/afc/memory/retrospectives/{YYYY-MM-DD}.md:

## Pattern: {category}
**What happened**: {concrete description}
**Root cause**: {why this bug occurred}
**Prevention rule**: {actionable rule — usable in future plan/implement phases}
**Severity**: Critical | Warning

Only write if the pattern is new and actionable. Generic observations are prohibited.

8. Final Output

If bug confirmed and fixed:

Debug complete
├─ Root cause: {one-line summary}
├─ Fixed files: {file list}
├─ Critic: converged ({N} passes, {M} fixes, {E} escalations)
├─ Verified: typecheck + lint passed
└─ Impact scope: {affected components/features}

If not a bug (intended behavior):

Debug complete
├─ Verdict: Not a bug — intended behavior
├─ Explanation: {why this behavior is correct}
├─ Evidence: {code path, documentation, or spec reference}
├─ Fixed files: none
└─ Suggestion: {documentation improvement if non-obvious, or "none"}

Notes

• Not every report is a bug: Always evaluate "intended behavior" hypothesis first. Do not modify code to match incorrect expectations.
• No excessive changes: change only what is needed to fix the bug. Do not refactor surrounding code.
• Symptom vs cause: find the root cause, not the surface symptom.
• 3-attempt limit: if fix fails after 3 attempts, report the situation to the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jhlee0409
• Source: jhlee0409/all-for-claudecode
• License: MIT
• Homepage: https://www.npmjs.com/package/all-for-claudecode

Install and usage instructions live in the source repository linked above.