---
name: stdd-investigation
description: Read-only current-state diagnosis — evidence-backed findings, no changes
when: Asked a factual question about current behavior, or to diagnose or triage it, WITHOUT changing anything.
---

# Investigation

The discipline: the deliverable is an evidence-backed diagnosis and an
explicit list of blockers — never an edit. For the fix that may follow,
switch to the debugging playbook; this one deliberately does not restate
it.

## Contract

- No task, ledger event, persisted artifact, file edit, or state-changing side
  effect — reads only.
- Every claim in the report is backed by evidence you actually observed,
  or labeled as unverified with the blocker named.
- Opinions, future behavior, and hypothetical implementation approaches belong
  in Brainstorming, not Investigation.

## Process

1. **Inventory the evidence channels first.** Before forming any theory,
   check what you can actually observe: forge CLI auth, container / DB /
   log access, environment-key **presence** (never values). Report dead
   channels as blockers immediately — do not silently work around a
   channel you could not reach.
2. **A hypothesis is not a diagnosis.** Test it against runtime signals —
   logs, states, reproductions — before reporting it as a finding. What
   you could not test, report as an explicitly unverified hypothesis with
   the blocker that prevented the test.
3. **Deliver the report**: the diagnosis (or ranked hypotheses) with its
   evidence, the blockers, and the narrowest useful next step.
4. **Hand off only when the prompt needs design.** If unknown current facts
   materially affect requested future behavior, finish the factual diagnosis
   and then invoke `stdd-brainstorming`. Merely reading docs or code during
   Brainstorming does not require a separate Investigation.