debug

Investigate-then-decide root-cause analysis for a defect whose cause is unknown. No code changes — exits to /ca:fix, /ca:adr, or a no-action close.

What it does

This is where an unexplained defect goes before anyone touches code. The investigation is deliberately separated from the fix: describing the symptom, forming multiple candidate causes, and checking each against logs, traces, and recent commits all happen without editing anything. The requirement for at least three distinct hypotheses — with one of them a boring explanation like a stale cache or a config mismatch — exists because locking onto the first plausible story is the most common way a diagnosis goes wrong. Whatever the investigation lands on, it has to close as exactly one outcome: a confirmed bug handed to /ca:fix with a named regression-test obligation, a design ambiguity handed to /ca:adr, or a documented decision that no action is needed.

Usage

/ca:debug <observed symptom>

Describe what happened with enough detail that someone else could reproduce it — a vague description like “it’s flaky” gets a request for more detail before routing begins.

Example

> /ca:debug the nightly export job sometimes finishes with a zero-byte file, maybe once a week

Symptom captured. Repro: intermittent, ~1-in-7 nightly runs, no clear trigger yet identified.
Hypotheses:
  H1 (likely): export writer is not flushed before the process exits
  H2: source query times out silently under load and returns nothing
  H3 (boring): the export volume mount is occasionally unmounted before the job starts
Gathering evidence... H1 CONFIRMED (log shows process exit 0.2s after last write, no flush call in
the writer's shutdown path). H2 and H3 REFUTED (query duration and mount logs are clean on affected runs).

Exit: (a) confirmed bug. Regression test obligation: kill the writer immediately after the last write
call and assert the output file is complete. Routing to /ca:fix.

When to reach for it

Reach for /ca:debug when the cause isn’t known yet. If the cause and a reproduction are already in hand, go straight to /ca:fix.

Gates

Gate	When	Effect
minimal repro	before a hypothesis is formed	a defect with no reliable reproduction (or a documented intermittent-trigger profile) cannot proceed
three hypotheses, one boring	before evidence is gathered	at least three distinct candidate causes are required, including one environmental or configuration explanation, before anything is checked against evidence
no code changes	for the entire investigation	every phase is read-only; a fix is never attempted mid-investigation
single named exit	at the end of the investigation	the session must close as exactly one of a confirmed bug, a design ambiguity, or a no-action close — never left open

Source

Source — plugins/ca/commands/debug.md (v2.9.1)

---
description: Investigate-then-decide root-cause analysis for a defect whose cause is unknown. No code changes — exits to /ca:fix, /ca:adr, or a no-action close.
argument-hint: "<observed symptom>"
---

# /ca:debug — root-cause investigation

Investigates a defect, anomaly, or unexpected behavior whose cause is not yet known. Separates investigation from implementation: no code is modified while debugging. Describe the symptom with enough fidelity that another operator could reproduce it — observed behavior, reproduction steps (or intermittent-trigger profile), and environment. Vague descriptions ("it's flaky") are rejected; the orchestrator asks for clarification before routing.

If the cause is already known and a regression test is already named, invoke `/ca:fix` directly.

## Routes to

The `debug` skill (`${CLAUDE_PLUGIN_ROOT}/skills/debug/SKILL.md`) — five gated phases: symptom
capture, hypothesis generation, evidence gathering, root-cause decision, handoff. Phase 4 forces one
named exit:

- **(a) Confirmed bug → `/ca:fix`**, carrying the confirmed bug statement, cited evidence, and a named
  regression test obligation tied to the minimal repro.
- **(b) Behavior/design ambiguity → `/ca:adr`**, with the ambiguity statement and evidence ledger,
  authored only with explicit user attribution.
- **(c) No-action close** — symptom and rationale appended to
  `${CLAUDE_PROJECT_DIR}/.codearbiter/open-tasks.md`.

A real finding that is out of scope for those exits is marked inline `[NEEDS-TRIAGE]` and the
investigation continues.

## When NOT to use

- Known bug with a named regression test → `/ca:fix` directly.
- Design discussion with no failing behavior → `/ca:adr`.
- New feature → `/ca:feature`.
- A general "why does it behave this way" question with no defect → `/ca:btw`.
- Re-entry from inside `/ca:fix` or `/ca:adr` → exit that command first (routing-cycle prevention).

## Hard gate

MUST NOT modify any code during Phases 1–5 — code changes belong to `/ca:fix`. MUST exit Phase 4 with
exactly one of (a)/(b)/(c). Exit (a) MUST carry a regression test obligation. Exit (b) MUST obtain
user attribution before any `/ca:adr`. MUST NOT promote INCONCLUSIVE evidence to CONFIRMED without a
cited source.

View in repo