---
name: godmode-investigation
description: Diagnose technical failures with reproducible evidence and bounded hypotheses. Use when a bug, regression, test failure, build failure, performance problem, or repeated unsuccessful fix needs root-cause investigation or a postmortem. Not for feature work or release mechanics.
---

# Godmode Investigation

## Outcome

Locate the earliest evidence-supported cause, test competing hypotheses until one
survives its kill experiment, and either verify a focused remedy or state exactly what
remains unknown.

## Evidence cycle

1. Restate the observed failure without proposing a fix.
2. Reproduce it with the smallest reliable command or artifact, and record the incident
   with that command: `godmode remember --kind incident "<what failed>" --repro "<the
   failing command>"` runs it now and stores its red exit code. With no reproduction yet,
   `--no-repro "<why>"` says so (classed underspecified-ask). Record the environment
   dimension only when it materially changes the result; never dump the environment.
3. Trace the failing value or state backward across each relevant boundary. Capture
   inputs, outputs, status, and timestamps with secrets redacted.
4. Compare with a working path in the same codebase and list every meaningful delta.
5. Form at least two competing hypotheses, each with its cause, supporting evidence and a
   kill experiment: `godmode hypothesis add --cause "<mechanism>" --kills "<check it
   predicts will pass>"`. One hypothesis tests a story's consistency, not its truth.
6. Run the smallest discriminating experiment. Change one variable. `godmode hypothesis
   kill <seq>` runs a kill experiment and records whether it fired.
7. If one survived and the user requested a fix, create a regression check, implement one
   coherent remedy at the origin, and run the full relevant verification. The fix claim
   names the incident and the survivor: `godmode claim "<fixed ...>" --grade verified
   --cite "cmd:<the repro command>" --cite hyp:<seq> --fixes <incident-seq> --verify`. It
   verifies only when the same reproduction command, red at the incident, is green now; a
   fix citing a hypothesis whose kill never ran, or fired, is refused.

Do not implement when the user asked only for diagnosis. Do not weaken, delete, skip, or
rewrite a valid test to manufacture a pass. A mock must preserve the contract being
tested and cannot replace the behavior under investigation.

## Loop control

Record failed attempts with `checkpoint --status failed --hypothesis ... --outcome ...`.
Do not repeat a failed hypothesis without new evidence. On the third failure of the same
hypothesis, stop changing code and revisit the architecture, boundary assumptions, or
test validity with the user. A different edit with the same causal claim is still the
same attempt.

## Evidence quality

Prefer fresh command output, a minimal reproduction, traceable file/line references,
content hashes, database migration state, and Git history over recollection. Treat agent
reports, comments, and stale docs as leads until verified. Distinguish correlation,
inference, and direct observation.

## Handoff

Record the symptom, reproduction, confirmed or rejected hypothesis, evidence, attempted
change, outcome, and next discriminating action. Generalize a private lesson only after
the mechanism is understood. Report no broader success than fresh verification proves.

Before treating a report as new: `recurrences --against "<the report>"` matches it against the fixed registry's symptom column (docs/FIXED-REGISTRY.md) and names the row and its guard; `precheck --about` carries the same matches and the inventory or design lines that describe the feature, and a reply that calls something a product decision while such a line was never opened is named at Stop.

Deterministic support: `loop` detects repeated actions, reapplied patches,
oscillation, and a spent hypothesis from the records, and with `--transcript`
names a loop episode (one error signature, the same hunks, nothing new for six
attempts) with the turn where new information last arrived; `mistakes` runs the
recurring-failure detectors; `method` selects the RCA method from the evidence
shape and `method --check-record` refuses an incomplete one; `reflect` surfaces
contradictions with prior claims; `integrity` blocks test-weakening changes;
`mistakes --process-started` blocks an RCA against a stale process.

## Absence protocol

An absence claim ("no callers", "0 rows", "not found") carries a `control:` or
`second:` citation or it is flagged: `godmode mistakes`' M21
(`absence-without-control`) fires on an absence claim that states its extent
(`searched:`/`scanned:`) but never proves the search mechanism itself could
have found something. An empty result from a broken probe reads identically
to a true negative - the control is what tells them apart. See `godmode
claim --help` for the full citation-prefix vocabulary.

Separately, and more strictly: a `--grade verified` absence claim recorded
via `godmode claim` needs TWO DISTINCT `cmd:` citations (or one that
positively enumerated something, not just came back empty) to avoid an
automatic downgrade to `hypothesis` - one probe that found nothing is
evidence about where you looked, not about what exists. This is the grading
pipeline's own gate and is a separate, stricter mechanism from M21 above; the
two are not unified, and citing `control:`/`second:` alone does not satisfy
it.

Read [godmode-evidence-cycle.md](references/godmode-evidence-cycle.md) for the attempt
record and completion checklist.

Orchestration gate: before a fix is handed to another agent or a subagent, the
incident is on record with its reproduction (`godmode remember --kind incident
--repro "<the failing command>"`) and the retest list is named (`godmode atlas
closure <files>`); a hand-off carrying neither is a guess passed along, and the
hand-back must cite the incident's seq and the retest's attestation.

## Postmortem flow

After a fix ships, run the postmortem in
[references/postmortem-flow.md](references/postmortem-flow.md).

## Verbs at the moment of demand

Each line names the one verb for the situation; run it then, not after.

- The same failure again: `godmode recurrences` lists repeated commands and failures before a third attempt; `godmode error-pattern` matches the failure text against declared patterns.
- A hypothesis to test: `godmode hypothesis add` records it with its kill experiment and `godmode hypothesis kill <seq>` runs it; `godmode experiment` records the setup and outcome; `godmode forecast` records the prediction before the run so the result can refute it.
- A postmortem to close: `godmode checklist template rca` prints the six RCA steps; `godmode method --check-record` refuses a record that skips one.
- A source to read before judging it: `godmode read --source <name> --path <file> --lines a-b` records what was opened (path, lines, digest) so an absorb verdict can cite the implementing code rather than a README; `godmode parity --sources` shows which sources were read past the surface.
- Two states to compare: `godmode differential` records both before the next edit; `godmode replay` re-reads a recorded run; `godmode inspect <seq>` opens one record in full.
- A guard that must be proven: `godmode plant` breaks the target and shows the guard fails; `godmode fuzz` drives the parser with malformed inputs; `godmode scenarios` runs the recorded scenario suite against the current tree.
- Where a change reaches: `godmode topology` maps the call structure, `godmode context why` says why a file is in context, `godmode drift` names what moved since the last inventory.
- Something silently swallowing errors: `godmode swallow` lists the handlers and holds the committed ceiling.
- A slow path: `godmode benchmark` times it cold, and `godmode watchdog` bounds a run that may not return; `godmode watch` follows a file or log while the run is live.