diagnose

name	diagnose
type	reference
description	Multi-agent diagnostic pipeline for complex/intermittent bugs. Orchestrates Investigator → Verifier → Solver → Lead Programmer with enforced handoff contracts. Use ONLY for non-obvious failures (root cause unclear, reproduction unstable, fixes reverted). NOT for trivial bugs with known cause — fix them directly.
paths	[]
effort	4
allowed-tools	Read, Glob, Grep, Write, Edit, Bash, Task
user-invocable	true
when_to_use	When a bug is reproducible but cause is unknown, when a 'fix' has been reverted 2+ times, or when a symptom appears in unfamiliar code. Do NOT use for typos, obvious nulls, or one-line logic errors.

Skill: /diagnose — Complex Bug Diagnostic Pipeline

When to invoke (and when NOT to)

✅ Use /diagnose when:

• Bug reproduces but root cause is unclear after one read-pass of the failing code
• Previous fix attempts have been reverted ≥ 2 times (symptoms return)
• Failure is intermittent (flaky test, race condition, timing-dependent)
• Failure occurs in unfamiliar code (agent has no prior context)
• User has explicitly requested /diagnose or "deep investigation"
• Circuit Breaker (Rule 14) tripped on the specialist agent that normally handles this domain

❌ Do NOT use /diagnose when:

• Cause is obvious (null ref, typo, missing import, incorrect import path)
• Fix is < 10 LOC and has a clear success check
• Bug is in code you just wrote this session (read-pass + local reasoning is faster)
• User wants a quick patch and has accepted the tradeoff

Pipeline overview

┌─────────────────┐     ┌─────────────────┐     ┌──────────────┐     ┌──────────────────┐
│  Investigator   │ ──► │    Verifier     │ ──► │    Solver    │ ──► │ Lead Programmer  │
│  (hypothesis)   │     │ (devil's adv.)  │     │  (tradeoffs) │     │  (assign + exec) │
└─────────────────┘     └─────────────────┘     └──────────────┘     └──────────────────┘
       │                       │                       │                       │
       ▼                       ▼                       ▼                       ▼
  investigation.json      verification.json      solution.json          implementation
  (root_cause,           (status: confirmed |    (3 options:           (delegates to
   evidence[],            refuted | inconclusive, Quick/Strategic/     backend-developer,
   confidence)            reproduction_steps)    Future-Proof)         qa-tester, etc.)

Each stage produces a required artifact saved to .investigations/<task_id>/ and a handoff contract (per Rule 16) to the next agent.

Stage 1 — Investigation

Agent: investigator Goal: Produce a falsifiable root-cause hypothesis backed by empirical evidence.

Inputs

• Symptom description (from user or TODO.md bug ID)
• Reproduction steps (or "cannot reproduce" + environment)
• Relevant log lines, stack traces, error IDs

Required output — investigation.json