debug

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