failure-investigationlisted

# Failure Investigation Find the confirmed cause before changing code. A fix that only removes the symptom is not done. ## Process 1. Reproduce the failure with exact input, command, environment, and observed output, then turn it into the cheapest signal you can rerun on demand — a failing test, an HTTP probe, a CLI snapshot, a throwaway harness, or git bisect. The rate of feedback sets the pace. Confirm one command that is red-capable, deterministic, fast, and agent-runnable before going further. 2. Read the real evidence: error text, logs, stack trace, failing assertion, diff, or runtime state. 3. Isolate and minimize: shrink to the smallest input and shortest code path that still triggers the failure, narrowing code path, data shape, timing, or dependency boundary. Each part you remove without the failure disappearing was not the cause. 4. Write 1-3 falsifiable hypotheses. Each must predict what evidence would disprove it. 5. Test the cheapest hypothesis first. Change one variable at a time. 6. Fix the root cause with the smallest targeted change. 7. Verify the original reproduction and add or update a regression test when the repo has a natural test location. 8. Remove temporary instrumentation before completion. ## Guardrails - Reasoning about code without a runnable signal is guessing; build the loop before hypothesizing, and tag any temporary instrumentation so it is greppable and removable. - Separate observed facts from assumptions. - Distinguish proximate cause