debug-mode

name	debug-mode
description	Hypothesis-driven debugging with hybrid dual-track parallel execution (Opus 4.5 + GPT 5.2). Spawns two independent chains of subagents where each reviews and improves upon its own previous work, then synthesizes findings from both tracks. Use when debugging hard-to-reproduce bugs, CI/E2E test failures, flaky tests, or when standard fixes have failed.

<debug_mode_skill> Deep Debugger / Senior Engineer <primary_goal>Fix bugs through runtime evidence using parallel AI perspectives</primary_goal>

Debug Mode uses hybrid dual-track parallel debugging with Opus 4.5 and GPT 5.2:

```
Main Agent (minimal - coordinates orchestrators)
    |
    ├── Task() -> Track 0 Orchestrator (Opus, synchronous)
    │       ├── debug-mode context run (GPT 5.2 medium)
    │       └── Task(model="opus") -> Repro Assessment
    |
    ├── [After Track 0 completes]
    |   |
    |   ├── Task(background) -> Track A Orchestrator (Opus)
    |   │   └── A1 (Opus) -> A2 (Opus/resume) -> A3 (Opus/resume) -> A4 (GPT/verify)
    |   │
    |   └── Task(background) -> Track B Orchestrator (Opus)
    |       └── B1 (GPT) -> B2 (Opus) -> B3 (GPT) -> B4 (Opus/verify)
    |
    ├── [After Track A/B complete]
    |   |
    |   └── Task() -> Judge Subagent (Opus, synchronous)
    |           └── Compares tracks, picks winner, outputs verdict
    |
    └── Apply winner fix, cleanup
```

- Track 0: Orchestrator runs Context Builder (GPT) then Repro Assessment (Opus)
- Track A: Opus chain with resume (Opus -> Opus -> Opus -> GPT), saves tokens
- Track B: True alternation (GPT -> Opus -> GPT -> Opus)
- Judge: Opus compares both tracks, picks winner (or COMPLEMENTARY if both needed)
- All Claude models = Opus 4.5, all OpenAI models = GPT 5.2
- Each iteration: Hypothesize -> Instrument -> Reproduce -> Analyze
- Early exit: A2/A3 or B2/B3 can verify and signal READY_FOR_FIX to skip remaining iterations
- Each track works in its own git worktree (no conflicts)

First time setup: cd ~/.claude/skills/debug-mode && bun install Add to PATH: ln -s ~/.claude/skills/debug-mode/bin/debug-mode ~/agent-tools/bin/ Requires: bun, tmux, codex CLI (for Track B)

<cli_commands> The debug-mode CLI provides utilities for managing debug sessions:

debug-mode init <project>                       Initialize worktrees and progress docs
debug-mode cleanup <project>                    Complete cleanup of all artifacts
debug-mode context run <prompt> <project>       Launch context builder (GPT 5.2 medium)
debug-mode context poll                         Check context builder status
debug-mode context read                         Output context.md contents
debug-mode codex run <track> <n> <file>         Run Codex iteration N for a track
debug-mode codex poll <track>                   Check Codex session status for a track
debug-mode status <track>                       Check progress doc for signals
debug-mode diff <track>                         Show changes in a track's worktree
debug-mode apply <track> <project>              Apply a track's fix to the project

Tracks: track-a, track-b

</cli_commands>

<critical_rule> NEVER attempt to fix the bug immediately. You MUST follow the dual-track debugging workflow. Speculative fixes without runtime evidence are prohibited. Wait for both tracks to complete before synthesizing findings. </critical_rule>

Use the CLI to create worktrees and progress docs:

  ```bash
  debug-mode init /path/to/project
  ```

  This creates:
  - Worktrees: /tmp/debug-track-a, /tmp/debug-track-b
  - Progress docs: /tmp/debug-track-a-progress.md, /tmp/debug-track-b-progress.md

  Update the progress docs with the actual bug description.
  Each track works in its own worktree - no conflicts possible.
</phase>

<phase name="2. TRACK 0 (Context + Repro)" agent="main">
  Spawn Track 0 Orchestrator to gather context and establish reproduction.
  This runs synchronously - main agent waits for completion.

  ```
  Task(
    subagent_type="general-purpose",
    model="opus",
    prompt="{track_0_orchestrator_prompt}",
    run_in_background=false  # Wait for completion
  )
  ```

  Track 0 Orchestrator performs:
  1. Context Builder (GPT 5.2 medium via Codex) - gathers relevant files
  2. Repro Assessment (Opus sub-subagent) - establishes reproduction strategy

  Outputs:
  - /tmp/debug-context.md with relevant code and analysis
  - REPRO_MODE in both progress docs (AUTO/SEMI_AUTO/MANUAL)
  - debug-repro.{js|py|sh} in both worktrees (if AUTO mode)

  See <track_0_orchestrator_prompt> for the prompt this orchestrator receives.
</phase>

<phase name="3. SPAWN PARALLEL DEBUG TRACKS" agent="main">
  Launch BOTH debug tracks as background subagents. Each subagent manages
  its own iteration loop independently. Main agent waits for both to complete.

  Track A Orchestrator (Opus, manages Opus/GPT iterations):
  ```
  Task(
    subagent_type="general-purpose",
    model="opus",
    prompt="{track_a_orchestrator_prompt}",
    run_in_background=true
  )
  ```

  Track B Orchestrator (Opus, manages GPT/Opus iterations):
  ```
  Task(
    subagent_type="general-purpose",
    model="opus",
    prompt="{track_b_orchestrator_prompt}",
    run_in_background=true
  )
  ```

  Both tracks start with context and repro strategy from Track 0.
  They focus purely on debugging: hypothesize, instrument, reproduce, analyze.

  See <track_orchestrator_prompts> for the prompts each orchestrator receives.
</phase>

<phase name="4. WAIT FOR COMPLETION" agent="main">
  Main agent waits for both background subagents to complete.
  Each subagent handles its own iteration loop internally.

  ```
  # Wait for both tracks (can check periodically or block)
  track_a_result = TaskOutput(task_id=track_a_id, block=true)
  track_b_result = TaskOutput(task_id=track_b_id, block=true)
  ```

  The subagents will:
  - Run up to 4 debug iterations each (repro already done by Track 0)
  - Spawn fresh sub-subagents for "fresh eyes" review (Track A)
  - Spawn fresh codex exec calls (Track B)
  - Update their progress docs after each iteration
  - Terminate when "READY FOR FIX" or "EARLY EXIT" is reached, or max iterations

  Main agent can optionally poll with block=false to show progress to user.
</phase>

<phase name="5. JUDGE" agent="main">
  Spawn Judge subagent to compare tracks and pick winner.

  ```
  Task(
    subagent_type="general-purpose",
    model="opus",
    prompt="{judge_subagent_prompt}",
    run_in_background=false  # Wait for verdict
  )
  ```

  The Judge will:
  1. Read context file: /tmp/debug-context.md
  2. Read both progress docs
  3. Compare fixes: `debug-mode diff track-a` and `debug-mode diff track-b`
  4. Evaluate: evidence quality, fix simplicity, verification confidence
  5. Output verdict: WINNER: track-a | WINNER: track-b | COMPLEMENTARY

  See <judge_subagent_prompt> for the prompt this subagent receives.
</phase>

<phase name="6. APPLY" agent="main">
  Apply the winning fix based on Judge verdict:

  ```bash
  debug-mode apply <winning-track> /path/to/project
  ```

  If COMPLEMENTARY, apply both fixes in sequence (track-a first, then track-b).
  Ask user to verify fix works in their environment.
</phase>

<phase name="7. CLEANUP" agent="main">
  After user confirms fix works:

  1. Apply the fix to main worktree (if developed in a track worktree):
     ```bash
     git diff /tmp/debug-track-{a|b}/path/to/file path/to/file
     ```

  2. Run the cleanup command:
     ```bash
     debug-mode cleanup /path/to/project
     ```

     This will:
     - Kill tmux session
     - Remove worktrees and branches
     - Delete all temp files
     - List remaining [DEBUG_AGENT] lines for manual removal

  3. Manually remove any [DEBUG_AGENT] lines listed in the output.

  This phase is MANDATORY. Never leave debug artifacts behind.
</phase>

<meta_prompt_template> Use this template for subagents 1-3 in either track (NOT for subagent 4 - see verification_subagent_prompt). These subagents iterate toward a fix: hypothesize, instrument, reproduce, analyze.

```
## Debug Track {A|B} - Subagent {N}

### Bug Description
{original_bug_description}

### Context
Read the context file for relevant files and code snippets:
Path: /tmp/debug-context.md

### Your Worktree (IMPORTANT)
Path: {/tmp/debug-track-a or /tmp/debug-track-b}

You are working in an ISOLATED git worktree. All file edits and commands
should be executed in YOUR worktree. The other track has its own worktree.
This prevents conflicts between tracks.

### Progress Document
Path: {/tmp/debug-track-a-progress.md or /tmp/debug-track-b-progress.md}

FIRST: Read the progress document to understand:
- REPRO_MODE and REPRO_COMMAND from Track 0
- Previous fix attempts and their results
LAST: Update the progress document with your findings before completing.

### Your Task
You are Subagent {N}. You are a DIFFERENT MODEL than the previous subagent.
Your job is to review their work with "fresh eyes" and iterate toward a fix.

### Behavior Constraints (GPT 5.2)
- Implement EXACTLY what is needed to fix the bug - nothing more
- Do NOT refactor unrelated code or add "improvements"
- Do NOT add extra error handling, logging, or features beyond the fix
- Keep fixes minimal: prefer 2-3 line changes over large refactors
- Use PARALLEL tool calls when reading multiple files
- Progress updates: 1-2 sentences at major steps only

Follow this flow: HYPOTHESIZE -> INSTRUMENT -> REPRODUCE -> ANALYZE

1. READ CONTEXT AND PROGRESS DOC
   - Read /tmp/debug-context.md for relevant files
   - Track 0's REPRO_MODE and REPRO_COMMAND
   - Previous fix attempts and their results
   - What's been confirmed/disproved

2. HYPOTHESIZE
   Based on the bug description and context, generate 2-3 hypotheses about the root cause.
   If this is not the first iteration, review previous hypotheses and their status.

3. FRESH EYES REVIEW (Critical Step)
   Read the previous subagent's code changes and analysis with fresh eyes.
   Look carefully for:
   - Obvious bugs or errors in their fix
   - Flawed assumptions or reasoning
   - Edge cases they missed
   - Off-by-one errors, null checks, race conditions
   - Whether their fix actually addresses the root cause
   - Anything that looks wrong, confusing, or suspicious

   You are a different model - use that to your advantage. Question everything.
   Don't assume the previous fix is correct just because it was attempted.

4. ANALYZE current state
   - If previous fix works AND passes your review -> consider SKIP_TO_VERIFY
   - If previous fix has issues -> understand why, plan correction
   - If no fix yet -> identify root cause from logs/code

5. INSTRUMENT (if needed)
   - Add [DEBUG_AGENT] logging to understand failures
   - JavaScript/TypeScript: console.log('[DEBUG_AGENT] ...')
   - Python: print('[DEBUG_AGENT] ...')
   - Skip if you have enough information to attempt fix

6. PROPOSE FIX
   - State which hypothesis you're testing
   - Describe the fix you will make
   - Explain why this should work

7. ATTEMPT FIX
   - Make the code change in your worktree
   - Keep fixes minimal and targeted (prefer 2-3 line fixes)
   - Do NOT remove [DEBUG_AGENT] logging

8. REPRODUCE AND VERIFY
   - Run REPRO_COMMAND - does the bug still occur?
   - Run tests if available - do they pass?
   - Document the results

9. UPDATE PROGRESS DOC
   ```markdown
   ## Iteration {N}

   ### Fresh Eyes Findings
   {issues found in previous work, or "N/A - first iteration"}
   - Bugs/errors spotted: {list or "None"}
   - Flawed assumptions: {list or "None"}
   - Edge cases missed: {list or "None"}

   ### Root Cause Analysis
   {current understanding of the bug}

   ### Fix Attempted
   File: {path}
   Change: {description of code change}
   Rationale: {why this fixes the root cause}

   ### Verification Results
   REPRO_RESULT: PASS | FAIL
   TESTS_RESULT: PASS | FAIL | N/A

   ### Signal
   One of:
   - SKIP_TO_VERIFY: Fix works, passed fresh eyes review, ready for verification
   - CONTINUE: Fix failed, has issues, or incomplete
   - NEEDS_MORE_INFO: Need more instrumentation before fixing

   ### Notes for Next Subagent
   {what to focus on if CONTINUE}
   ```

## SKIP_TO_VERIFY Criteria
Signal SKIP_TO_VERIFY if ALL of the following are true:
1. Fresh eyes review found no issues with the fix
2. REPRO_RESULT is PASS (bug no longer reproduces)
3. TESTS_RESULT is PASS or N/A (no regressions)
4. The fix is minimal and clearly addresses root cause
5. You questioned the fix critically and it holds up

DO NOT remove [DEBUG_AGENT] logging - main agent handles cleanup.
```

</meta_prompt_template>

<context_builder_prompt> Use this prompt for the Context Builder (GPT 5.2 medium) - the first step in Track 0. It searches the codebase to identify relevant files, then bundles them with repomix.

```
## Track 0 Step 1: Context Builder

Your task is to identify all relevant files for debugging this bug, then bundle
them into a context file using repomix.

You are running with GPT 5.2 medium reasoning.

### Behavior Constraints
- Use PARALLEL tool calls when searching (grep multiple patterns simultaneously)
- Be CONCISE - no narration of routine operations
- Output only what's needed: file list, repomix command, brief analysis
- Do NOT expand scope beyond finding relevant files

### QUICK REFERENCE: repomix Usage

Bundle files into /tmp/debug-context.md using these patterns:

```bash
# Single files (comma-separated)
npx repomix --include "src/auth.ts,src/utils/token.ts" --output /tmp/debug-context.md

# Glob patterns
npx repomix --include "src/auth/**/*.ts" --output /tmp/debug-context.md

# Multiple globs
npx repomix --include "src/auth/**/*.ts,tests/auth*.ts" --output /tmp/debug-context.md

# With exclusions
npx repomix --include "src/**/*.ts" --exclude "**/*.test.ts,**/node_modules/**" --output /tmp/debug-context.md
```

Output MUST go to: /tmp/debug-context.md

### Bug Description
{bug_description}

### Project Root
{project_root}

### Phase 1: SEARCH - Identify Relevant Files

Use search tools to find files relevant to this bug:

1. Grep for error messages, function names, keywords from bug description
2. Glob to find related files by pattern (e.g., `**/*auth*.ts`)
3. Read files briefly to confirm relevance

Target files:
- Files likely to contain the bug
- Files that interact with the buggy code
- Test files related to the affected functionality
- Config files that might influence behavior
- Entry points and call chains

Build a list of relevant file paths as you search.

### Phase 2: BUNDLE - Package with repomix

Once you have identified the relevant files, bundle them:

```bash
npx repomix \
  --include "src/auth.ts,src/utils/token.ts,tests/auth.test.ts" \
  --output /tmp/debug-context.md
```

Tips:
- Use comma-separated paths in --include
- Can use globs: --include "src/auth/**/*.ts,tests/auth*.ts"
- repomix will include full file contents with line numbers

### Phase 3: APPEND - Add Analysis Summary

After repomix generates the bundle, append your analysis:

```bash
cat >> /tmp/debug-context.md << 'EOF'

---

## Debug Analysis Summary

### Bug Description
{bug_description}

### Reproduction Hints
- Entry point: {how the bug is triggered}
- Dependencies: {external services, databases, etc.}
- Test commands: {existing test commands that might help}

### Investigation Areas
1. {file:lines - what to look for and why}
2. {file:lines - what to look for and why}
3. {file:lines - what to look for and why}

EOF
```

IMPORTANT: The subsequent subagents will rely on this context file.
Be thorough in Phase 1 - missing a relevant file means the debug
iterations won't have visibility into that code.
```

</context_builder_prompt>

<repro_subagent_prompt> Use this prompt for Track 0 Step 2 - the repro assessment subagent that establishes reproduction strategy for BOTH Track A and Track B.

```
## Track 0 Step 2: Repro Assessment Subagent

Your SOLE task is to establish a reproduction strategy for this bug.
Do NOT add instrumentation. Do NOT attempt to fix. Just establish repro.

This repro strategy will be used by BOTH Track A (Claude) and Track B (GPT 5.2).

### Context
FIRST: Read the context file generated by the Context Builder:
Path: /tmp/debug-context.md

This contains relevant files, code snippets, and observations about the bug.

### Worktrees