investigate

name	investigate
description	Deep bug investigation. Pass a short description of the problem — error message, unexpected behavior, or failing test. Returns structured root cause analysis with evidence and fix recommendation.

dynos-work: investigate

Runs a deterministic-first investigation pipeline: triage first, reasoning second, citation validation third. The LLM never gathers evidence on its own — it reasons over a pre-built dossier, and that guarantee is enforced in code: the investigator role's Read access is restricted to the investigations directory and its Grep/Glob calls are denied by the pre-tool-use hook.

Ruthlessness Standard

• Name the mechanism, not the symptom.
• Every conclusion must cite a pre-minted evidence ID from the dossier.
• If the evidence does not support a claim, say so instead of guessing.

Phase 1 — Deterministic Evidence Gathering

Create an investigation directory inside the project's .dynos/ (never /tmp — the write policy denies it), then run the triage orchestrator before invoking the LLM:

INVESTIGATION_DIR=".dynos/investigations/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$INVESTIGATION_DIR"
python3 "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}/debug-module/triage.py" --bug "<bug text>" --repo . --out "$INVESTIGATION_DIR/dossier.json"

This produces an evidence dossier with pre-minted evidence IDs (F-001 for files, S-001 for symbols, etc.), git blame, linter findings, and Semgrep silent-accomplice findings. The LLM does not gather evidence — it reasons over what triage has already found.

Phase 2 — Causal Reasoning

If a task dir exists, grant the investigator role before the spawn (enforces dossier-only reads in the hook): python3 "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}/hooks/ctl.py" grant-role .dynos/task-{id} --role investigator. Standalone investigations (no task) skip this.

Spawn the @investigator subagent. Pass the contents of $INVESTIGATION_DIR/dossier.json as input and instruct the agent to:

• Trace root cause, immediate cause, and detection failure.
• Cite only evidence IDs that exist in the dossier.
• Return the structured bug-report JSON as its final message — a single JSON object matching debug-module/schemas/bug_report.schema.json, no prose, no markdown fences. The investigator is read-only (tools: [Read, Grep]); it must NOT attempt to write any file.

The agent must not invent file paths, symbols, or findings outside the dossier.

Phase 3 — Validation, Persistence, and Render

Pipe the agent's returned JSON into the deterministic finalize step. It validates the report structure (every claim must carry non-empty evidence_ids), mechanically verifies every cited evidence ID exists in the dossier, renders the Markdown via debug-module/lib/render_report.py (render_report.render), and persists bug_report.json + the rendered report.md — rejection exits non-zero and nothing is persisted:

python3 "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}/debug-module/triage.py" finalize \
  --report - \
  --dossier "$INVESTIGATION_DIR/dossier.json" <<'REPORT_JSON'
{ ...the investigator's returned JSON, verbatim... }
REPORT_JSON

• Exit 0: print the rendered report.md content to the user.
• Exit 1 (rejected — structural violation or unknown citation): the stderr names each violation. Re-spawn the investigator ONCE with the violations appended to its prompt; if the second attempt is also rejected, report the failure honestly. Do NOT edit the report JSON yourself to make validation pass — fabricating or trimming citations defeats the entire evidence chain.

Usage

/dynos-work:investigate <your problem description>

Examples:

/dynos-work:investigate TypeError: Cannot read properties of undefined reading 'id' at UserService.ts:47
/dynos-work:investigate the checkout flow always skips the discount calculation when coupon code is applied
/dynos-work:investigate test suite: AuthController > login > should return 401 on invalid password is failing
/dynos-work:investigate the GitHub Actions workflow fails on main but tests pass locally