root-cause — read-only bug analysis

You are performing read-only analysis: no file edits, no branches, no commands that mutate state. Output is a brief that a human or /fix acts on.

The iron rule: no fix without a root cause. A fix proposed before the cause is understood is a guess, and guesses create new bugs. Symptom patches are failure even when they make the error disappear.

Announce at start: "Using the root-cause skill — read-only analysis of this bug."

Step 0: Load context

1. The bug report — full description, repro steps, linked threads/issues.
2. .ai/lessons.md — known pitfalls in the affected area.
3. Root AGENTS.md Task Router → the matching .claude/rules/ guides.
4. The affected module/package AGENTS.md.

Step 1: Establish the facts

1. Read the error completely — full stack trace, message, HTTP status, file and line numbers. The error text often contains the answer.
2. Reproduce or trace. State the exact repro steps. If you cannot reproduce even mentally, gather more data — do not guess.
3. Check recent changes: git log --oneline -20 -- <affected paths> and the branch diff. Most bugs live in what changed last.
4. Trace the data flow from entry point to origin: route → loader/action → service function → query → response. Note every transformation. Follow the bad value backward to where it is first wrong — fix at the source, not where the symptom surfaces (see references/root-cause-tracing.md).
5. Check the schema: read the newest relevant migrations (order by timestamp) and generated types. Column names and constraints must match what the code assumes.

Step 2: Carbon-specific failure modes

Check each of these before inventing exotic theories:

Step 3: One hypothesis at a time

1. Form a single specific hypothesis: "X in file Y causes the bug because Z."
2. Verify it against the code you can read. If the code contradicts it, discard it — don't force-fit.
3. Distinguish cause from symptom: a UI TypeError may originate three layers down. Keep tracing until you reach the origin.
4. Three-strikes rule: if 3 hypotheses have failed, the problem is likely architectural (shared state, coupling, a wrong pattern) — STOP, write up what you ruled out, and surface the architectural question to the human instead of producing hypothesis #4.

Step 4: Confidence

If MEDIUM or LOW and the bug involves runtime state, ordering, caching, concurrency, or manual reproduction → recommend /debugging-difficult-bugs (temporary JSONL instrumentation) as the next step instead of guessing. Never present a guess as a finding.

Step 5: Output the brief

Produce exactly this structure (~400 words max):

## Root-Cause Brief

**Bug:** <one line>
**Summary:** <2–3 sentences: symptom and observable impact>
**Root cause:** <why it happens, citing file:line>
**Confidence:** HIGH | MEDIUM | LOW
<if not HIGH: what is uncertain and what would resolve it — e.g. "instrument via /debugging-difficult-bugs">

**Files to change:**
- `path/to/file.ts` — <what and why>

**Approach:**
1. <step>

**Risks:**
- <e.g. "signature change affects 3 callers">

**BC impact:** <NONE | FROZEN/STABLE surfaces touched, per BACKWARD_COMPATIBILITY.md>

Guardrails

• Read-only. No edits, no git writes, no migrations, no DB commands.
• No speculative fixes. "Try this and see" is not a finding.
• Stay scoped. Analyze the reported bug only; note unrelated discoveries in one line at the end, don't chase them.
• Cite evidence. Every claim references a file, line, migration, or policy.

Red flags — thinking any of these means you're guessing, not analyzing; STOP:

• "it's probably X, let me suggest the fix" (no verified cause → no fix)
• "I'll propose two possible fixes and let them pick" (that's two guesses)
• "one more hypothesis" after three have failed (that's an architecture question now — surface it)
• "the error message is misleading, ignore it" (read it again; it usually isn't)

References (read when the situation matches)

• references/root-cause-tracing.md — tracing a bad value backward through the call stack to its origin
• references/defense-in-depth.md — layering validation after the cause is found
• references/condition-based-waiting.md (+ condition-based-waiting-example.ts) — replacing arbitrary timeouts with condition polling in flaky async tests
• references/find-polluter.sh — bisecting which earlier test pollutes a failing test