amirfish1 / bug-race

Bug-race is the pattern for hunting a stubborn root cause in parallel: you spawn
one autonomous CCC session ("racer") per distinct hypothesis, each diagnosing
ONLY its assigned line, and you act as referee — the first racer to CONFIRM a
root cause with reproducible evidence wins, and you stand the rest down
mid-flight. It builds on the spawn/report_to mechanics in the
ccc-orchestration skill — read that first for the full Spawn/Inject/Ask API.

Cost

2-3 spawned sessions — one per hypothesis, capped at 3. Each spawn is a real
billed session on the user's kanban — tell the user the count before spawning.

Do NOT use this for first-pass debugging. The race is for bugs that already beat
you once; a fresh bug gets normal systematic debugging first (see
superpowers:systematic-debugging). If you have only one hypothesis, don't race
— just debug it. Racing near-identical hypotheses burns sessions for nothing.

Setup

CCC_URL="$(cat ~/.claude/command-center/port.txt 2>/dev/null || echo "${CCC_URL:-http://127.0.0.1:8090}")"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_URL="http://127.0.0.1:8090"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_DOWN=1

Notes: (a) run every CCC curl with the network sandbox disabled — the Bash
sandbox blocks loopback and fails spuriously even when CCC is up. (b) URL-encode
repo_path in query strings (+ → %2B, space → %20). (c) Resolve your own
session id from $CLAUDE_SESSION_ID, else the newest *.jsonl under
~/.claude/projects/<slugified-cwd>/ (see ccc-orchestration).

Step 1 (you): enumerate the hypotheses

DISTINCT means a different subsystem or mechanism, not variations of one idea
(e.g. "race in the writer" vs "stale cache" vs "wrong env var" — not "off-by-one
here" vs "off-by-one there"). Cap at 3. Write each as one falsifiable sentence.
If you can't name two genuinely distinct hypotheses, stop — this isn't a race.

Step 2: spawn one racer per hypothesis

All with report_to set to your own session id. Omit "model" and
"reasoning_effort": the server spawn defaults (Settings → Spawn defaults)
apply. Pass either explicitly to keep cost down, with "engine" alongside it,
since both are validated per engine (see ccc-orchestration § 2 for the
per-engine effort ladders).

curl -s -X POST "$CCC_URL/api/sessions/spawn" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "prompt": "Bug: <symptom + exact repro steps>. Your assigned hypothesis: <H>. Work ONLY this hypothesis. Try to CONFIRM it with reproducible evidence (instrument, add logging, bisect, trace — evidence a peer could re-run), or ELIMINATE it (state exactly what rules it out). Do NOT fix anything; diagnose only. Report: VERDICT: CONFIRMED (evidence + the exact failure mechanism) / ELIMINATED (the disproof) / INCONCLUSIVE (what would be needed to decide).",
  "repo_path": "/abs/path/to/repo",
  "report_to": "<your-session-id>"
}
JSON

Repeat once per hypothesis, changing only the assigned <H>.

Waiting for the report(s)

After spawning, end your turn and tell the user which hypotheses are racing
and in which sessions. Verdicts arrive by injection (the report_to footer CCC
appends). Never poll or sleep-loop (see the no-tight-polling rule in
ccc-orchestration). If a report never arrives, check `GET
/api/sessions/spawned` for whether that racer's session is still alive before
assuming it finished silently.

Step 3 (referee = you): pick the winner

The first CONFIRMED verdict whose evidence you can re-run yourself wins.
Immediately stand the other racers down via POST /api/inject-input:

curl -s -X POST "$CCC_URL/api/inject-input" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "session_id": "<other-racer-session-id>",
  "text": "Root cause confirmed elsewhere: <mechanism>. Stop your line of investigation. If you saw evidence that CONTRADICTS this mechanism, report it now; otherwise report ELIMINATED and stand down."
}
JSON

If two racers both report CONFIRMED, do not pick a favorite — either the bug
is two bugs, or one evidence chain is weak. Reconcile the two mechanisms before
you fix anything.

Record the eliminations (an issue comment or the fix commit message). Dead
ends are the expensive half of debugging, and the race just bought them cheaply
— throwing that away means the next person re-runs the same dead ends.

Dry run

If the arguments contain dry-run, print the session count, each hypothesis
sentence, the exact spawn payload per racer, and the target repo — then POST
nothing.

When CCC is down

If CCC_DOWN=1 or a curl returns connection refused (exit 7): do not pretend the
race ran. Fall back to testing the hypotheses yourself sequentially,
cheapest-to-test first, and tell the user CCC was unreachable.

What this is not

Parallel one-shot Task subagents could explore hypotheses too, but racers are
visible, long-running sessions you can stand down mid-flight via inject — the
referee move is the whole point. This is not wt critique (that reviews a thing
you already made; this hunts a root cause).