debug

What this skill does

# Debug Pipeline

Targeted bug repair pipeline for the ant colony. Six phases (D0-D5) dispatch specialized agents to investigate, diagnose, fix, and ship a bug fix. Uses **stateless direct dispatch** -- no state.json, no hooks, no Agent Teams orchestration. The orchestrator (debug command) spawns agents directly via Task tool calls.

## Key Architecture

- **Stateless:** No `.agents/tmp/state.json` is created or read during debug
- **Direct dispatch:** The debug command spawns agents via Task, reads their output files, and proceeds
- **No hooks:** Because no ants state.json exists, `check_ants_workflow()` in every hook returns false (exits 0 immediately), so all hooks pass through without interfering
- **Self-contained:** All output files live under `.agents/tmp/debug/`

## 6-Phase Pipeline

```
Phase D0  | EXPLORE     | Bug Investigation      | 3x parallel bug-scout
Phase D1  | PROPOSE     | Solution Proposals      | 3x parallel solution-proposer
Phase D2  | AGGREGATE   | Solution Ranking         | 1x solution-aggregator + user confirmation
Phase D3  | IMPLEMENT   | Fix Implementation       | 1x fix-worker
Phase D4  | REVIEW      | Adversarial Review       | 6x parallel sentinels + review-arbiter
Phase D5  | SHIP        | Documentation + Commit   | 1x nurse + 1x drone
```

### Pipeline Diagram

```
        D0 Explore (3x parallel bug-scout)
            |
        D1 Propose (3x parallel solution-proposer)
            |
        D2 Aggregate (solution-aggregator ranks proposals)
            |
        [user confirms selected fix]
            |
        D3 Implement (fix-worker applies the fix)
            |
        D4 Review (adversarial)
       / / | \ \ \
  correct. secur. perf style testing docs  (6x parallel sentinels)
       \ \ | / / /
        review-arbiter (consolidate)
            |
        D5 Ship
          /    \
      nurse    drone
   (docs)    (commit)
```

## Phase Details

### Phase D0: Bug Investigation (EXPLORE)

Three `ants:bug-scout` agents (haiku) are dispatched in parallel, each assigned a focused investigation query derived from the bug report. Each scout investigates from three angles: error manifestation, execution path, and test/change context.

After all scouts complete, their temp files are aggregated into a consolidated exploration report.

- **Agents:** 3x `ants:bug-scout` (haiku, parallel)
- **Input:** Bug description from user
- **Temp output:** `.agents/tmp/debug/explore.bug-scout.{N}.tmp` (one per scout)
- **Final output:** `.agents/tmp/debug/D0-explore.md` (aggregated report)

### Phase D1: Solution Proposals (PROPOSE)

Three `ants:solution-proposer` agents (sonnet) are dispatched in parallel. Each reads the D0 exploration report and independently proposes exactly one targeted fix. Proposals include root cause analysis, concrete code changes, trade-offs, confidence assessment, and testing strategy.

- **Agents:** 3x `ants:solution-proposer` (sonnet, parallel)
- **Input:** D0-explore.md
- **Temp output:** `.agents/tmp/debug/propose.solution-proposer.{N}.tmp` (one per proposer)

### Phase D2: Solution Ranking (AGGREGATE)

A single `ants:solution-aggregator` agent (sonnet) reads all proposal temp files, scores each on 5 dimensions (correctness, scope, risk, confidence, testability), ranks them by weighted total, and recommends the best fix.

After the aggregator writes its output, the orchestrator presents the recommendation to the user for confirmation before proceeding to implementation.

- **Agent:** 1x `ants:solution-aggregator` (sonnet)
- **Input:** All `propose.solution-proposer.{N}.tmp` files
- **Output:** `.agents/tmp/debug/D2-solutions.md`
- **Gate:** User confirmation required before advancing to D3

### Phase D3: Fix Implementation (IMPLEMENT)

A single `ants:fix-worker` agent (inherit) reads the selected solution from D2-solutions.md, implements the fix, writes regression tests, and self-verifies (tests, lint, typecheck).

- **Agent:** 1x `ants:fix-worker` (inherit)
- **Input:** D2-solutions.md
- **Output:** `.agents/tmp/debug/D3-implementation.json`

**Edit gate interaction:** The fix-worker can freely edit project files because no ants state.json exists during the debug pipeline. The `on-edit-gate.sh` hook calls `check_ants_workflow()` at the top of every invocation. Since there is no `.agents/tmp/state.json`, this function returns false and the hook exits 0 (allow). This means the edit gate imposes no stage-based restrictions during debug -- the fix-worker operates with full edit access.

### Phase D4: Adversarial Review (REVIEW)

Six specialist sentinel agents run in parallel, each reviewing the fix from a different dimension:

- **`ants:sentinel-correctness`** (sonnet) -- bugs, logic errors, missing error handling, race conditions
- **`ants:sentinel-security`** (sonnet) -- OWASP top 10, injection, authentication, secrets exposure
- **`ants:sentinel-perf`** (sonnet) -- N+1 queries, blocking I/O, unnecessary allocations, algorithmic complexity
- **`ants:sentinel-style`** (sonnet) -- code style, readability, maintainability, dead code
- **`ants:sentinel-testing`** (sonnet) -- test quality, coverage gaps, missing edge cases, flaky tests
- **`ants:sentinel-docs`** (sonnet) -- documentation accuracy, stale comments, missing docstrings

After all six sentinels complete, the `ants:review-arbiter` (sonnet) cross-references findings, deduplicates overlapping issues, resolves conflicts, and produces a consolidated quality verdict.

- **Agents:** 6x parallel sentinels + 1x `ants:review-arbiter` (sequential after sentinels)
- **Input:** D3-implementation.json + modified source files
- **Sentinel output:** `.agents/tmp/debug/D4-review.sentinel-correctness.json`, `.agents/tmp/debug/D4-review.sentinel-security.json`, `.agents/tmp/debug/D4-review.sentinel-perf.json`, `.agents/tmp/debug/D4-review.sentinel-style.json`, `.agents/tmp/debug/D4-review.sentinel-testing.json`, `.agents/tmp/debug/D4-review.sentinel-docs.json`
- **Arbiter output:** `.agents/tmp/debug/D4-quality.json`

### Phase D5: Documentation + Ship (SHIP)

Two agents run sequentially:

1. **`ants:nurse`** (sonnet) -- updates project documentation (README, CLAUDE.md, etc.) to reflect the bug fix
2. **`ants:drone`** (inherit) -- commits changes and optionally opens a PR

- **Agents:** 1x `ants:nurse` (sonnet), then 1x `ants:drone` (inherit)
- **Nurse output:** `.agents/tmp/debug/D5-docs.json`
- **Drone output:** `.agents/tmp/debug/D5-ship.json`

## Phase-Agent Mapping

| Phase | Agent | Model | New/Reused | Count | Execution |
|-------|-------|-------|------------|-------|-----------|
| D0 | `ants:bug-scout` | haiku | New | 3 | Parallel |
| D1 | `ants:solution-proposer` | sonnet | New | 3 | Parallel |
| D2 | `ants:solution-aggregator` | sonnet | New | 1 | Single |
| D3 | `ants:fix-worker` | inherit | New | 1 | Single |
| D4 | `ants:sentinel-correctness` | sonnet | Reused | 1 | Parallel |
| D4 | `ants:sentinel-security` | sonnet | Reused | 1 | Parallel |
| D4 | `ants:sentinel-perf` | sonnet | Reused | 1 | Parallel |
| D4 | `ants:sentinel-style` | sonnet | Reused | 1 | Parallel |
| D4 | `ants:sentinel-testing` | sonnet | Reused | 1 | Parallel |
| D4 | `ants:sentinel-docs` | sonnet | Reused | 1 | Parallel |
| D4 | `ants:review-arbiter` | sonnet | Reused | 1 | Sequential (after sentinels) |
| D5 | `ants:nurse` | sonnet | Reused | 1 | Sequential |
| D5 | `ants:drone` | inherit | Reused | 1 | Sequential (after nurse) |

**Total:** 13 agents (4 new debug-specific + 9 reused from swarm pipeline)

## Output File Layout

All output files live under `.agents/tmp/debug/`:

| Phase | File | Format | Description |
|-------|------|--------|-------------|
| D0 temp | `.agents/tmp/debug/explore.bug-scout.{N}.tmp` | Markdown | Individual bug scout investigation results (N = 1, 2, 3) |
| D0 final | `.agents/tmp/debug/D0-explore.md` | Markdown | Aggregated exploration report from all scouts |
| D1 temp | `.agents/tmp/debug/propose.solution-proposer.{N}.tmp` | Markdown | Individual