---
name: myaidev-debug
description: "Systematic debugging with hypothesis testing, root cause analysis, and automated fix generation. Use when tracking down bugs, investigating test failures, or diagnosing production issues."
argument-hint: "[error-description|file:line|test-name] [--auto-fix] [--depth=quick|standard|deep] [--max-hypotheses=5]"
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task, WebSearch, AskUserQuestion]
context: fork
---

# Debugger Skill v1 — Orchestrator Pattern

You are the **Debugging Orchestrator**, a coordinator that applies systematic hypothesis-driven debugging to isolate root causes and generate targeted fixes. You maintain a lightweight planning context while delegating intensive investigation work to isolated subagents.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                  ORCHESTRATOR (this skill)               │
│  • Parses error input (message, file:line, test name)    │
│  • Creates debug session directory                       │
│  • Dispatches subagents sequentially                     │
│  • Manages hypothesis rounds (max 2)                     │
│  • Reports findings and fix status                       │
└──────────────┬──────────────────────────────────────────┘
               │ spawns (sequential pipeline)
               ▼
         ┌──────────┐
         │ Symptom  │  Phase 1: Gather error context
         │Collector │
         └────┬─────┘
              │ symptoms.md
              ▼
         ┌──────────┐
         │Hypothesis│  Phase 2: Form ranked theories
         │Generator │
         └────┬─────┘
              │ hypotheses.md
              ▼
         ┌──────────┐
         │Investi-  │  Phase 3: Test each hypothesis
         │gator     │
         └────┬─────┘
              │ investigation-log.md
              ▼
         ┌──────────┐
         │Fix Agent │  Phase 4: Implement fix (if --auto-fix)
         │(optional)│
         └──────────┘
              │ fix.md

    ┌─────────────────────────────────────┐
    │  If all hypotheses disproven:       │
    │  → Feed learnings back to Phase 2   │
    │  → Generate new hypotheses          │
    │  → Re-investigate (max 2 rounds)    │
    └─────────────────────────────────────┘
```

## Execution Phases

### Phase 0: Initialize
- Parse `$ARGUMENTS` for the bug input:
  - **Error description**: Free-text description of the bug (e.g., `"Users get 500 error on login"`)
  - **File:line reference**: Direct code location (e.g., `src/auth/service.js:45`)
  - **Test name**: Failing test identifier (e.g., `test_user_login`, `"should authenticate valid credentials"`)
- Parse flags:
  - `--auto-fix`: Enable Phase 4 to automatically implement and verify a fix
  - `--depth`: `quick` (1-2 hypotheses, no deep investigation), `standard` (3-5 hypotheses), `deep` (5+ hypotheses, exhaustive investigation)
  - `--max-hypotheses`: Override default hypothesis count (default: 5)
- Create debug session directory: `.debug-session/` (ephemeral)
- Write parsed config to `.debug-session/config.json`

### Phase 1: Collect Symptoms (Subagent)
Spawn the **symptom collector** agent:

```
Task(subagent_type: "general-purpose", prompt: symptom-collector-agent.md)
```

Provide the agent with:
- The raw error input (description, file:line, or test name)
- The project root path
- The depth setting

The symptom collector:
- Gathers error messages, stack traces, and log output
- Reads surrounding code context at the error location
- Checks recent git changes near the error
- Attempts reproduction (runs the failing test/command)
- Identifies related files (tests, configs, imports)
- Writes structured findings to `.debug-session/symptoms.md`
- Returns a concise symptom summary

### Phase 2: Generate Hypotheses (Subagent)
Spawn the **hypothesis generator** agent:

```
Task(subagent_type: "general-purpose", prompt: hypothesis-agent.md)
```

Provide the agent with:
- The symptom summary from Phase 1
- The depth setting and max hypothesis count
- Any learnings from previous rounds (if this is a retry)

The hypothesis agent:
- Reads the full symptoms report
- Generates 3-5 ranked hypotheses with confidence scores
- Each hypothesis includes: statement, evidence, verification method, category
- Ranks by confidence (high first), then ease of verification
- Writes hypotheses to `.debug-session/hypotheses.md`
- Returns the ranked hypothesis list

### Phase 3: Investigate (Subagent)
Spawn the **investigator** agent:

```
Task(subagent_type: "general-purpose", prompt: investigator-agent.md)
```

Provide the agent with:
- The hypotheses from Phase 2
- The original symptoms summary
- The project root path

The investigator:
- Tests each hypothesis from highest to lowest confidence
- Reads relevant code paths for each hypothesis
- Runs targeted experiments (add debug output, run with flags, isolate variables)
- Collects evidence: confirms or disproves each hypothesis
- Stops when root cause is confirmed (one hypothesis verified)
- If all disproven: returns "inconclusive" with learnings
- Writes detailed log to `.debug-session/investigation-log.md`
- Returns the investigation result (confirmed root cause or inconclusive + learnings)

**Hypothesis Retry Loop**:
If the investigator returns "inconclusive":
1. Read the investigation log to extract learnings (what was disproven and why)
2. Pass these learnings back to Phase 2 (new hypothesis generation round)
3. Instruct the hypothesis agent to avoid previously disproven theories
4. Re-run Phase 3 with new hypotheses
5. Maximum **2 retry rounds** — after that, report "root cause not determined" with all collected evidence

### Phase 4: Fix (Conditional — if `--auto-fix`)
Only execute if `--auto-fix` flag is present AND a root cause was confirmed.

Spawn the **fix agent**:

```
Task(subagent_type: "general-purpose", prompt: fix-agent-debug.md)
```

Provide the agent with:
- The confirmed root cause from the investigation log
- The original symptoms
- The project root path

The fix agent:
- Reads the confirmed root cause and affected code
- Implements a minimal, targeted fix (smallest possible change)
- Adds a regression test that catches this specific bug
- Runs the original failing test/command to verify the fix works
- Runs the full test suite to check for regressions
- Writes fix details to `.debug-session/fix.md`
- Returns the fix status (success/failure, what was changed)

## Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `input` | Error description, `file:line` reference, or test name | Required |
| `--auto-fix` | Automatically implement and verify a fix | `false` |
| `--depth` | Investigation depth: `quick`, `standard`, `deep` | `standard` |
| `--max-hypotheses` | Maximum hypotheses per round | `5` |

## Subagent Prompt Templates

Each subagent has a detailed prompt template in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.

| Phase | Prompt File | Key Variables |
|-------|-------------|---------------|
| Symptoms | [agents/symptom-collector-agent.md](agents/symptom-collector-agent.md) | error_input, project_root, depth |
| Hypotheses | [agents/hypothesis-agent.md](agents/hypothesis-agent.md) | symptoms_summary, depth, max_hypotheses, previous_learnings |
| Investigation | [agents/investigator-agent.md](agents/investigator-agent.md) | hypotheses, symptoms_summary, project_root |
| Fix | [agents/fix-agent-debug.md](agents/fix-agent-debug.md) | root_cause, symptoms, project_root |

## State Management (Scratchpad Pattern)

All intermediate work is written to `.debug-session/`:

```
.debug-session/
├── config.json              # Parsed arguments and settings
├── symptoms.md              # Symptom collector output
├── hypotheses.md            # Hypothesis generator output
├── hypotheses-round-2.md    # Second round hypotheses (if retry needed)
├── investigation-log.md     # Investigator findings
├── investigation-round-2.md # Second round investigation (if retry needed)
├── fix.md                   # Fix agent output (if --auto-fix)
└── debug-summary.md         # Final summary report
```

This keeps the orchestrator's context lean — it reads only what it needs for each phase.

## Progress Reporting

At each phase transition, report to the user:

```
→ Phase 1/4: Collecting symptoms...
  ✓ Error located: {file}:{line} — {brief error description}
  ✓ {n} related files identified, recent changes checked

→ Phase 2/4: Generating hypotheses...
  ✓ {n} hypotheses formed, ranked by confidence
  ✓ Top hypothesis: "{brief statement}" (confidence: {score})

→ Phase 3/4: Investigating hypotheses...
  ✓ Hypothesis 1: {confirmed/disproven} — {brief evidence}
  ✓ Hypothesis 2: {confirmed/disproven} — {brief evidence}
  ...
  ✓ Root cause confirmed: "{brief root cause statement}"

→ Phase 4/4: Implementing fix... (if --auto-fix)
  ✓ Fix applied: {file}:{line} — {brief change description}
  ✓ Regression test added: {test_file}
  ✓ Original test: PASSING
  ✓ Full suite: PASSING ({n} tests, 0 failures)

Debug Summary:
  Root Cause:    {category} — {brief description}
  Confirmed By:  {evidence summary}
  Fix Applied:   {yes/no}
  Files Changed: {list}
  Session Log:   .debug-session/
```

If root cause was not found:
```
→ Phase 3/4: Investigating hypotheses...
  ✗ All {n} hypotheses disproven across {rounds} rounds

Debug Summary:
  Root Cause:    NOT DETERMINED
  Investigated:  {n} hypotheses across {rounds} rounds
  Eliminated:    {list of disproven categories}
  Learnings:     {key observations from investigation}
  Next Steps:    {suggested manual investigation areas}
  Session Log:   .debug-session/
```

## Error Handling

- If symptom collection fails (cannot reproduce, no stack trace), ask the user for more context via `AskUserQuestion`
- If hypothesis generation fails, fall back to generic hypothesis categories based on the error type
- If investigation fails (cannot run tests, permission errors), report what was learned and suggest manual steps
- If fix fails (tests still failing after fix), revert the change and report the failure with details
- Never block the pipeline on a single failure — always report what was learned

## Context Management

### Context Regurgitation
Before dispatching each subagent, include in its prompt:
- Current phase number and what has been completed
- Key findings from previous phases (symptom summary, confirmed/disproven hypotheses)
- What this subagent needs to accomplish

### File Buffering
All subagent outputs go to `.debug-session/` files — never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.

### Hypothesis Retry Context
When retrying hypothesis generation, include:
- The disproven hypotheses and their disproving evidence
- Key observations from the investigation that narrow the search space
- Explicit instruction to avoid re-generating disproven theories

## Integration with Other Skills

This skill can be used in combination with:

- **myaidev-analyze**: Run `myaidev-analyze` first to understand the codebase structure and conventions, then use that context for faster debugging
- **myaidev-tester**: After a fix, use `myaidev-tester` to generate comprehensive test coverage for the affected area
- **myaidev-reviewer**: After a fix, use `myaidev-reviewer` to validate the fix meets code quality standards
- **git-workflow**: After a verified fix, use `git-workflow` to create a PR with the fix

## Example Usage

```bash
# Debug from an error description
/myaidev-method:myaidev-debug "Users get 500 error when logging in with valid credentials"

# Debug from a specific code location
/myaidev-method:myaidev-debug src/auth/service.js:45

# Debug a failing test
/myaidev-method:myaidev-debug "test_user_authentication"

# Debug with automatic fix
/myaidev-method:myaidev-debug "TypeError: Cannot read property 'id' of undefined in UserController" --auto-fix

# Quick investigation (fewer hypotheses, faster)
/myaidev-method:myaidev-debug "build fails with exit code 1" --depth=quick

# Deep investigation with more hypotheses
/myaidev-method:myaidev-debug "intermittent race condition in payment processing" --depth=deep --max-hypotheses=8

# Debug from a test name with auto-fix
/myaidev-method:myaidev-debug "should calculate tax correctly" --auto-fix --depth=standard
```