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 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.

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.