Fix Issue

Fix Issue: $ARGUMENTS

Step 0: Load Configuration

Read .claude/project.config.json to get project configuration.

Variables to use:

• {testCmd} = config.commands.test (default: npm test)
• {mainBranch} = config.git.mainBranch (default: main)
• {fixPrefix} = config.git.branchPrefixes.fix (default: fix/)
• {coAuthoredBy} = config.git.coAuthoredBy (default: false)

Read context/FIXES.md for existing bug reports and fix history.

Step 1: Issue Context

Determine the issue source based on $ARGUMENTS:

If numeric (e.g., 42):

gh issue view $ARGUMENTS --json title,body,labels,comments

• Extract: title, description, reproduction steps, labels
• Note issue number for commit reference

If text description (e.g., login-timeout):

• Treat as a description of the problem
• Ask user for reproduction steps if not clear

Step 2: Consult FIXES Registry

Read context/FIXES.md and search for existing reports matching the issue:

• Check Pending section for matching entries
• Check In Progress section for related work
• Check Resolved (Recent) for similar past fixes

If match found in Pending:

• Pre-load context (reproduction steps, severity, related files)
• Move item from Pending → In Progress in FIXES.md

If match found in Resolved:

• Report: "A similar fix was applied before: {details}. This may be a regression."

If no match found:

• Ask user: "This issue is not in FIXES.md. Should I register it? (recommended)"
• If yes: add to In Progress with standard format

Step 3: Locate Affected Code

Search for code related to the issue:

1. Keyword search: Grep for terms from the issue description in src/
2. File search: Glob for files matching module/component names
3. Trace the flow: Read identified entry points and follow the execution path
4. Related tests: Find existing tests for the affected code

Report findings:

### Affected Code
| File | Line | Relevance |
|------|------|-----------|
| `{file}` | {line} | {why this file is relevant} |

Step 4: 3-Hypothesis Debugging Protocol (R12)

MANDATORY: Before writing any fix, formulate and validate hypotheses.

4.1 Formulate Hypotheses

Based on the issue context and code analysis, formulate at least 3 hypotheses about the root cause:

### Hypotheses
| # | Hypothesis | Confidence | Validation Method |
|---|-----------|------------|-------------------|
| 1 | {description} | HIGH/MED/LOW | {how to verify} |
| 2 | {description} | HIGH/MED/LOW | {how to verify} |
| 3 | {description} | HIGH/MED/LOW | {how to verify} |

4.2 Validate Each Hypothesis

For each hypothesis, gather evidence:

• Read relevant code sections
• Check logs if available
• Run targeted tests
• Trace data flow

### Validation Results
| # | Hypothesis | Evidence | Verdict |
|---|-----------|----------|---------|
| 1 | {description} | {what was found} | CONFIRMED / REJECTED / INCONCLUSIVE |
| 2 | {description} | {what was found} | CONFIRMED / REJECTED / INCONCLUSIVE |
| 3 | {description} | {what was found} | CONFIRMED / REJECTED / INCONCLUSIVE |

4.3 Confirm Root Cause

• If one hypothesis is CONFIRMED: proceed with fix targeting that cause
• If multiple CONFIRMED: determine the primary cause and address all
• If all INCONCLUSIVE: gather more evidence or formulate new hypotheses
• Never proceed without a confirmed root cause

Step 5: Implement Fix

Fix the confirmed root cause:

• Minimal change: only modify what's necessary to fix the issue
• Follow conventions: use project naming and patterns
• No refactoring: don't clean up unrelated code
• Add guards: prevent the same issue from recurring if appropriate

Step 6: Test

Run tests to verify the fix:

{testCmd}

• If tests fail: investigate whether the failure is related to the fix
• If tests pass: verify the fix actually addresses the issue
• Add new tests if the bug wasn't covered by existing tests

Step 7: Update FIXES Registry

Read and update context/FIXES.md:

If item was in Pending/In Progress:

• Move to Resolved (Recent) with:

  ### FIX-{NNN}: {title}
  - **Severity**: {severity}
  - **Root cause**: {confirmed hypothesis}
  - **Fix**: {what was changed}
  - **Files**: {list of modified files}
  - **Date resolved**: {date}
  - **Session**: {session-ID if applicable}
  

If item was not registered:

• Add directly to Resolved (Recent) with the same format

Step 8: Commit

Create commit with fix prefix:

If from GitHub issue (numeric $ARGUMENTS):

git add {modified files}
git commit -m "fix(scope): description (closes #$ARGUMENTS)

- Root cause: {confirmed hypothesis}
- Fix: {what was changed}
"

If from description:

git add {modified files}
git commit -m "fix(scope): description

- Root cause: {confirmed hypothesis}
- Fix: {what was changed}
"

Co-Authored-By: Check config.git.coAuthoredBy:

• If true: add Co-Authored-By: Claude <noreply@anthropic.com>
• If false (default): do NOT include AI attribution

Error Recovery

Workflow Decision

Converted and distributed by TomeVault — claim your Tome and manage your conversions.