Skill: /fix-bug

Trigger

/fix-bug "description of unexpected behavior"

The description is critical for investigation quality. Without it, ask before continuing.

Response guidelines

Be comprehensive but concise. Omit obvious explanations, avoid repetition, get straight to the point. Save tokens without losing technical precision.

Reading project context

Read if they exist:

.claude/project.md — stack, environments, modules
.claude/known-issues.md — priority read
.claude/architecture.md — flows and dependencies
.claude/conventions.md — team standards

Stage 0: Clarification

Before investigating, check if the description is actionable.

Ask up to 3 targeted questions if any of the following are true:

No description was provided
Expected vs. current behavior cannot be distinguished from the description
The environment (local / staging / prod) is not determinable and matters for the hypotheses
An error message or stack trace exists but was not shared

Only ask for facts that directly narrow the hypothesis space. No style or preference questions.

After asking, wait for the user's reply before proceeding to Stage 1. If the user says "skip questions" or "just investigate", proceed with available context.

Stage execution

By default, all stages run sequentially in one response.

The user can say "do only Stage 1 and 2", "stop after Stage 3", "skip to Stage 5". Respect this literally.

If a mid-stage ambiguity requires input, emit the completed portion of the current stage, then write:

Paused at Stage N. [Question]. Reply to continue.

Stage 1: Known issues check

Check .claude/known-issues.md first.

If it matches something recorded: show the solution and ask if context changed
If not: proceed to Stage 2

Output: "Checking known-issues..." followed by result.

Stage 2: Bug understanding

Expected: what should happen Current: what is happening Environment: infer from context (local / staging / prod) Frequency: always / sometimes / specific condition

If after rephrasing the bug you identify a fundamental ambiguity that makes Stages 3–5 unreliable, pause here and ask the user to confirm before continuing.

Stage 3: Root cause hypotheses

List ordered from most to least likely:

### Hypothesis N — [title]
Probability: High / Medium / Low
Cause: why this would explain the behavior
Verify: command or code snippet to confirm

If two hypotheses have equal probability and the distinction requires information only the user has (e.g., recent deploys, infra changes), pause after listing them and ask one targeted question before Stage 4.

Stage 4: Diagnostic plan

Concrete steps in order of increasing cost:

Logs, database, queue (no code)
Code and flow
Reproduction in controlled environment

Prefer commands executable in pod terminal for K8s environments.

Stage 5: Fix plan

Only produce Stage 5 if either:

At least one hypothesis from Stage 3 has High probability, OR
The user has explicitly confirmed which hypothesis is correct.

If neither is true, output: "Stage 5 on hold — complete Stage 4 steps and share results to proceed."

Where: file(s) and function(s)
What: necessary change
Side effects: what else might be affected
Test: how to confirm the fix

Stage 6: Register in known-issues

If new bug with recurring potential, add to .claude/known-issues.md:

## [Category — title]

Description: behavior and root cause.
Context: where it tends to appear.
Solution: how to fix.
Detected in: [fix-bug]

Inform: "⚠️ Recorded in known-issues: [title]"

Output format

## Stage 1 — Known Issues
[Found with solution / Not found]

## Stage 2 — Bug Understanding
Expected: ...
Current: ...
Environment: ...
Frequency: ...

## Stage 3 — Hypotheses
[ordered list]

## Stage 4 — Diagnostic Plan
[numbered steps]

## Stage 5 — Fix Plan
[after diagnosis or high-confidence hypothesis / "On hold — see Stage 4"]

## Stage 6 — Known Issues Registration
[new record / "No registration needed"]

fix-bug