/debug

name: debug
description: "Investigate an unexplained defect or unexpected behavior without changing application code. Use for root-cause diagnosis and an evidence-backed handoff, including a bounded unresolved result. Not for implementing a known fix, new features, or explanation-only questions."
argument-hint: "<observed symptom>"

debug

Select this owning procedure for a root-cause investigation, whether requested in plain language or through `/debug`. The command spelling is not a prerequisite. Investigation and implementation remain separate: this procedure never changes code. It closes the reproduce, evidence, and regression-test handoff loop through `/fix`.

Entry boundaries

• A known bug with a named regression test belongs to `/fix` directly.
• A design discussion without failing behavior belongs to `/adr`; attribution is

still required before authoring an ADR. New behavior belongs to `/feature`.

• An explanation-only question stays in the non-mutating question-answer path;

it does not require a debug invocation or a command spelled by the user.

• A cited failure with an unknown trigger can enter scoped investigation. Keep

diagnosis-only requests within diagnosis; a debug finding grants no repair authority. An active `/fix` may use one bounded internal diagnostic prerequisite and return to the same caller; do not recursively route public `/fix` and `/debug` entries. An active `/adr` is not debug authority.

• The phase gates below own symptom precision, evidence, and the one named exit.

A no-action close requires positive evidence and makes no default board or state write.

Pre-flight

Read scoped project instructions and available context before dependent action:

Resolve the selected context format through `{{PLUGIN_ROOT}}/includes/knowledge.md`. The document names below denote Markdown files in Markdown mode and the corresponding exact knowledge records in HTML mode. Use `knowledge.py commands` for declared test commands in HTML mode.

• `{{PROJECT_DIR}}/.codearbiter/tech-stack.md` — log paths, trace tooling, test runner conventions. The evidence sources.
• `{{PROJECT_DIR}}/.codearbiter/CONTEXT.md` — domain vocabulary, system structure, and the `stage:` frontmatter (the maturity value; higher demands more rigorous evidence before exit).
• Complete format-selected `security-controls` policy (see `{{PLUGIN_ROOT}}/includes/knowledge.md`) — only when the symptom touches a security boundary (auth, crypto, secrets). Optional; absent on most defects.
• `{{PROJECT_DIR}}/.codearbiter/code-map.md` — optional coarse map. Use it as a

search pointer when present, then verify current sources. If absent, the map is no prerequisite: inspect relevant source directly. Do not generate it.

If missing resource, context, or capability blocks a dependent action, name its exact path or capability. Continue safe reads and report established facts with their limits. Do not guess a command, log path, or tool. Do not onboard, scaffold, install, or write a marker to make the investigation appear initialized. Do not claim full readiness from partial context. If no identifiable symptom, failed job, trace, or anomaly exists, ask one focused question and return the missing-input result without inventing a case.

Phase 1 — Symptom capture · gate: BLOCK

Record the available symptom and its limits so another operator can continue:

• **Observed** — one sentence: what the system did. Not the suspected cause; causes belong to Phase 2.
• **Expected** — use the current contract, approved spec, test, authoritative

documentation, or stated user intent when available, without re-asking for facts already present. If current sources conflict on the expectation, name the conflicting sources and the specific decision needed; do not reconcile them silently. If no expectation is established, inspect mechanics without asserting a contract violation.

• **Reproduction state** — record `reproduced`, `intermittent`,

`not_yet_reproduced`, `unsafe_to_replay`, or `unavailable`. Capture the exact action, inputs, cwd, preconditions, environment, frequency, and failure signature only where known. An unknown trigger remains unknown; do not invent a reproduction, trigger, or cause to fill this record.

• **Evidence in hand** — cite the source of each failure, trace, log excerpt,

or source observation and its time or revision context. Distinguish a user report from an independently observed failure.

• **Evidence identity** — record source revision or commit identity and the

observed runtime or build identity where available. Keep an unknown identity explicit with its limitation; do not infer one from the local checkout.

• **Request scope** — retain diagnosis-only scope and actual caller authority;

finding a likely repair does not expand either one.

With a cited failure but unknown trigger, begin safe targeted investigation as `not_yet_reproduced`. Seek discriminating evidence or a safe replay when its effects and authority are understood. A failed replay establishes only the tested conditions; it neither disproves the report nor supplies a no-action verdict. Do not force a failure to make the record look reproducible.

Gate: an identifiable symptom or failure, actual request scope, available expectation, reproduction state, and cited evidence or an explicit evidence gap. Missing details remain unknown and may block a later dependent action; they do not bar safe orientation. Every material observation cites its source.

Phase 2 — Hypothesis generation · gate: BLOCK

List candidate mechanisms that could produce the observed symptom and identify a real distinguishing observation for each. Distinct candidates involve different mechanisms, boundaries, or failure modes, not reworded suspicions. In a narrow case, one grounded candidate and a neighboring-boundary discriminator can suffice. Explore more plausible mechanisms when the symptom or evidence warrants them; do not pad