debug

name	debug
description	Debug issues with iterative fix loop. Gathers problem description, investigates, then enters fix-verify cycle. Triggers on "debug", "fix this", "troubleshoot". Use when the goal is to fix a specific reported issue. For exploration or new features, use brainstorm or plan-creation.
allowed-tools	["Read","Write","Edit","Grep","Glob","Bash","Skill","AskUserQuestion"]

Debug

Iterative debug loop: gather problem, investigate, fix loop (max 10 iterations) with verification after each fix.

---

Phase 0: Goal Definition

Parse $ARGUMENTS for a problem description.

If $ARGUMENTS is empty:

• Use AskUserQuestion: "Describe the problem you're seeing. Include error messages, unexpected behavior, or what's broken."

Check for active work session:

• Read .flywheel/session.md — if it exists, warn the user:
  • "A work session is currently active. Debugging may conflict with in-progress work."
  • Use AskUserQuestion: "Continue debugging anyway? (yes/no)"
  • If no, stop.

Get verification command:

• Use AskUserQuestion: "What command reproduces or shows the problem? (e.g., pytest tests/test_foo.py, npm test, curl ...). Say 'none' for manual verification."

If command provided:

• Run the command to capture baseline output
• Truncate output to last 2000 characters
• Store as BASELINE_OUTPUT

If "none":

• Set MANUAL_MODE = true
• Skip baseline capture

---

Phase 1: Investigation

Investigate inline (no subagent dispatch in V1).

Gather Context

1. Read error output / BASELINE_OUTPUT carefully — identify file names, line numbers, error types
2. Search codebase for relevant files:

   # Use Grep to find error strings, function names, class names from the output
   # Use Glob to locate test files, config files, related modules
   

3. Check recent git changes:

   git log --oneline -10
   git diff
   git diff --cached
   

Form Hypotheses

Produce 2-3 ranked hypotheses based on the evidence. Format each as:

Hypothesis N: <one-line summary>
Evidence: <what points to this>
Likelihood: High / Medium / Low

Confirm Direction

Present hypotheses to user using AskUserQuestion:

• "Here are my hypotheses. Which should I pursue first? (number, or describe a different direction)"

---

Phase 2: Fix Loop

ITERATION = 0
STRIKES = {}  # track failures per hypothesis
CURRENT_HYPOTHESIS = <user-selected hypothesis>

For each iteration (1 to 10):

  1. Implement ONE targeted fix
     - Minimum change needed
     - If fix requires >5 lines, explain why before implementing

  2. Verify:
     - Automated mode: run verification command, truncate to last 2000 chars
     - Manual mode: AskUserQuestion "Did this fix the problem? (describe what you see)"

  3. Evaluate:
     - If FIXED → go to Phase 3
     - If NOT FIXED → analyze new output, adjust approach

  4. Track strikes:
     - STRIKES[CURRENT_HYPOTHESIS] += 1
     - If STRIKES[CURRENT_HYPOTHESIS] >= 3 → move to next hypothesis

  5. If all hypotheses exhausted:
     - AskUserQuestion "All hypotheses exhausted. Describe what you're seeing or suggest a new direction."
     - Form new hypotheses from user input

Fix Loop Rules

• Minimum change: Make the smallest fix needed. If a fix requires >5 lines, explain why before implementing.
• No shotgun debugging: Fix root causes. Do NOT make random changes hoping something works.
• Changes accumulate: Do NOT stash or revert changes between iterations. Changes build toward the solution.
• 3-Strike Protocol: 3 failures on the same hypothesis means move to the next. See flywheel-conventions/SKILL.md for the full 3-Strike Error Protocol.
• Escalation: After 10 iterations or all hypotheses exhausted, escalate to user with a summary of everything tried.

Escalation Summary Format

## Debug Escalation
- Problem: <original description>
- Iterations completed: N
- Hypotheses tested: <list>
- Changes made so far: <list of files modified>
- Current state: <what the verification command shows now>
- Recommendation: <next steps if any>

---

Phase 3: Summary & Next Steps

Summarize the Fix

Provide a clear summary:

• Root cause: What was wrong
• Fix applied: What changed and why
• Verification: Confirmation that the verification command passes

Show Changes

git diff

Offer Next Steps

Use AskUserQuestion with exactly 2 options:

1. "Commit and compound (Recommended)" — Commit changes via /ship, then offer /compound to document the debugging solution for future reference.
2. "Done for now" — Exit without committing. Changes remain in the working tree.

If user picks option 1:

• Invoke /ship to commit and create PR
• Then offer: "Want to run /compound to document this fix for future reference?"

If user picks option 2:

• Inform user that changes are uncommitted in the working tree
• Exit

---

Key Principles

• Verification command is your feedback loop — trust it over assumptions
• One fix per iteration — small, targeted changes that isolate variables
• Escalate, don't spin — after 3 strikes on a hypothesis, move on
• All user interaction happens here — never dispatch AskUserQuestion to subagents
• Read before editing — always Read a file before modifying it
• Preserve context — keep BASELINE_OUTPUT for comparison throughout the session

---

Anti-Patterns

• Shotgun debugging — random changes hoping something works
• Skipping verification — never claim "fixed" without running the verification command
• Stashing between iterations — changes accumulate, do not revert
• AskUserQuestion in subagents — only the orchestrator interacts with users
• Fixing symptoms — address root causes, not surface-level manifestations
• Multi-fix iterations — one change per iteration keeps the feedback loop tight