dev-debug

What this skill does

**Announce:** "I'm using dev-debug for systematic debugging."

**Iteration topology:** serial fresh-subagent hypothesis loop (one investigator per cycle)

**Load shared enforcement:**

Auto-load all constraints matching `applies-to: dev-debug`:

!`uv run python3 ${CLAUDE_SKILL_DIR}/../../scripts/load-constraints.py dev-debug`

**You MUST have these constraints loaded before proceeding. No claiming you "remember" them.**

<EXTREMELY-IMPORTANT>
## STEP ZERO — INITIALIZE THE DEBUG LOOP

Your first actions are, in order:
1. Create/update .planning/HYPOTHESES.md (the durable memory across iterations)
2. Spawn the first investigation subagent

**Do NOT read project code. Do NOT form hypotheses. Do NOT "gather context." All investigation happens inside subagents with fresh context.**

### The Cognitive Lock

Until you spawn the first subagent, you cannot: Read files, Edit code, Run commands, Grep for patterns, "Just quickly check" anything, Form hypotheses, or Analyze prior context. **All tools LOCKED until first subagent is spawned.**

### Why This Exists

On March 6-7, 2026, an agent loaded dev-debug TWICE and both times rationalized skipping the loop. Result: 19MB transcript, 15K lines, 30 "root cause found" claims, 6+ theories, zero resolution. The session was killed.
</EXTREMELY-IMPORTANT>

## Architecture: Fresh Subagent Loop With Progress Gating

**No `/goal`. No promises. No honor system.** The main chat runs its own progress-gated loop directly. Each iteration is a fresh subagent. The loop runs autonomously as long as subagents make meaningful progress. The user is only pulled in when the loop stalls. (Debugging doesn't fit `/goal`'s evaluator model because the completion condition is "test passes," which is what the subagent itself is trying to make true — the main chat needs to run the test, not a separate evaluator reading the transcript.)

```
Main chat (thin orchestrator)
  │
  ├─ Initialize .planning/HYPOTHESES.md
  │
  ├─ LOOP:
  │   ├─ Spawn fresh subagent → investigate/fix
  │   ├─ Subagent returns structured report
  │   ├─ Evaluate progress (see stall detection below)
  │   │
  │   ├─ MEANINGFUL PROGRESS?
  │   │   YES → iterate automatically (spawn next subagent)
  │   │   NO  → escalate to user
  │   │
  │   └─ SUBAGENT CLAIMS FIXED?
  │       → Run the test command yourself
  │       → Pass? → DONE
  │       → Fail? → log false positive, iterate
  │
  └─ Max 10 iterations without resolution → escalate to user
```

### Why This Design

- **Fresh subagent per iteration**: No context pollution. Each subagent reads state from .planning/HYPOTHESES.md, not from 15K lines of prior conversation.
- **No `/goal` dependency**: The exit condition is progress, gated by main chat running the test command itself — not a separate evaluator reading the transcript.
- **User only involved when needed**: Autonomous when making progress, escalates when stuck.
- **Test as structural gate**: When the subagent claims FIXED, main chat runs the test. The agent can't lie about test output.

**Progress lives in files, not in conversation.**

<EXTREMELY-IMPORTANT>
## The Iron Law of Delegation

**MAIN CHAT MUST NOT TOUCH THE CODEBASE. EVER.**

Main chat does exactly four things:
1. Initialize .planning/HYPOTHESES.md
2. Spawn fresh subagents
3. Evaluate progress between iterations
4. Run the regression test when a subagent claims FIXED

| Tool | Main Chat? | Subagent? |
|------|-----------|-----------|
| `Read` (project files) | **NO** | YES |
| `Read` (.planning/HYPOTHESES.md) | **YES** — for progress evaluation | YES |
| `Edit` / `Write` | **NO** | YES |
| `Grep` / `Glob` | **NO** | YES |
| `Bash` (project commands) | **ONLY** to run regression test | YES |
| `Agent` (spawn subagent) | **YES** — this is your job | — |

**Why?** The moment you read code, you form opinions. Opinions bias hypotheses. You end up editing directly. This is how the 19MB transcript happened.
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
## The Iron Law of Verification vs Investigation

**Running the test suite IS verification. Reading source code IS investigation. If you need to READ CODE to "verify," you need a SUBAGENT, not verification.**

This distinction exists because on March 16, 2026, an agent rationalized reading source code, grepping project files, and running docker exec commands as "verification" after a subagent returned. It was investigation disguised as verification. 71 protocol violations followed.

| Verification (main chat CAN do) | Investigation (main chat CANNOT do) |
|----------------------------------|--------------------------------------|
| `vitest run` / `npm test` | `grep` / `rg` in source code |
| `git diff HEAD -- '*.test.*'` | `Read()` any project source file |
| Read .planning/HYPOTHESES.md / .planning/LEARNINGS.md | `docker exec` into containers |
| Check test exit code | Read application logs |
| `git status` / `git log` | Query databases (`sqlite3`, etc.) |
| | `curl` / `wget` to test endpoints |
| | Inspect process state / env vars |

**The test command is the ONLY Bash command main chat runs on the project.** Everything else — log reading, container inspection, database queries, curl testing, env var checking — is investigation. Delegate it.
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
## The Iron Law of Topic Changes

**If the user sends a message that is NOT about the current debug bug, you MUST announce the loop pause before responding.**

On March 16, 2026, the user asked "What's in spotless db" mid-debug-loop. The assistant silently abandoned the protocol, ran 15+ direct database queries, and never resumed the debug loop. The user had to re-invoke dev-debug.

**Protocol:**
1. Announce: "Pausing dev-debug loop to address your request."
2. Handle the off-topic request (normal tools allowed — you're outside the loop)
3. Announce: "Resuming dev-debug loop. Reading .planning/HYPOTHESES.md for current state."
4. Read .planning/HYPOTHESES.md and spawn the next subagent

**If the user's message could be interpreted as EITHER a new topic OR part of the debug:**
- Ask: "Is this related to the current debug, or a separate request?"
- Do NOT assume it's separate and abandon the loop silently

**Silent loop abandonment is NOT HELPFUL — the user invoked dev-debug because they want structured debugging. Silently dropping the structure wastes their explicit request.**
</EXTREMELY-IMPORTANT>

## The Process

### Step 1: Initialize State

Create .planning/HYPOTHESES.md if it doesn't exist (ensure .planning/ directory exists first):

```markdown
# Debug Hypotheses

## Bug: [SYMPTOM]
Started: [timestamp]

## Iteration Log
(subagents will append here)
```

**Cross-session re-entry check (FIRST).** Before initializing, check for a prior handoff:

```bash
test -f .planning/HANDOFF.md && echo "HANDOFF_EXISTS" || echo "NO_HANDOFF"
```

If `HANDOFF_EXISTS`: read `.planning/HANDOFF.md`, summarize the recorded debug state to the user, and resume from it (then delete the consumed HANDOFF.md). This mirrors the entry-skill resume detection (dev/SKILL.md:17-67) so a `/dev-debug` re-entry after a handoff does not silently start a fresh loop.

If .planning/HYPOTHESES.md already exists (resumed session), read it to understand current state.

### Context Monitoring

Before spawning each subagent iteration, check context availability:

| Level | Remaining Context | Action |
|-------|------------------|--------|
| Normal | >35% | Spawn next subagent |
| Warning | 25-35% | Complete current iteration evaluation, then write .planning/HYPOTHESES.md and invoke dev-handoff |
| Critical | ≤25% | Write .planning/HYPOTHESES.md immediately, invoke dev-handoff |

**Why:** Debug loops can run 10+ iterations. Without monitoring, the orchestrator degrades and loses track of hypotheses tested vs. remaining.

### Step 2: Spawn Investigation Subagent

Each iteration spawns exactly ONE fresh subagent with this prompt (fill in brackets):

```
Agent(subagent_type="workflows:dev-debugger", prompt="""