Iron rule:Do not fix before the root cause is found. Making the symptom disappear and solving the problem are two different things. This rule applies to every anomaly: code, data, metrics, processes.
Diagnosis is a thinking activity; each step is driven by a thinking engine — what the engine gives you is not terminology, it isthe question to ask at that step。
Non-trivial diagnostic processes are written to the workspace draft directory .issues/<YYYY-MM-DD-主题>/diagnosis.md: hypothesis list with item-by-item verdicts, probe records, root-cause reconciliation, fix and verification. Before writing, first make sure the draft directory is ignored:git check-ignore .issues When it does not pass, append .issues/ to .git/info/exclude(local ignore, without touching the shared .gitignore) and tell the user in one sentence. In a non-git environment there is no commit risk, so write directly. It is three things at once — the vehicle for the hypothesis list shown to the user, the counter for the three-strikes stop-loss, and the working memory to continue the investigation next time after a session is interrupted. Small problems that can be located at a glance may be exempted.
1. Reproduce and pin down the symptom
Turn the anomaly into something that can be observed deterministically: for code problems, build a minimal reproduction that can be run repeatedly; for data problems, take the raw data and compute it yourself; for metric problems, pin down the statistical definition and time window. If it cannot be reproduced, keep collecting observations; do not start fixing.
Definition of taking action: only a change that alters behavior counts as a fix. Read-only probes, diagnostic scripts, and pure scaffolding for testability (exported functions, wrapping the main guard, must verify zero behavior change) do not count and do not need to pass the hypothesis threshold.
2. Hypothesis generation — first-principles engine
Do not ask "what similar bug have I seen before" (pattern matching is a breeding ground for anchoring); ask:"For this symptom to hold, which facts must be true?" Break the symptom into a chain of necessary conditions; every link in the chain is a suspect point, and every suspect point generates a hypothesis.
- Write each hypothesis in falsifiable form: "If it is this, I will see X. If not, I will see Y." If you cannot write a falsification condition, it is not a hypothesis, it is a feeling.
- Also run "known information" through the three states of facts: what the logs say, what the user relays, what the comments claim — is it a verified fact, or a proposition awaiting verification? Contaminated "knowns" are the deepest pit.
- The complete list must appear in visible output before acting— not merely thought through internally and counted as done. List it item by item and show it to the user so people can challenge your direction (you may continue without waiting for a reply, but the list itself must not be compressed into a single passing mention).
- Proportionality principle: when the answer is nearly visible to the naked eye, the list may be compressed to 2–3 items (target hypothesis + strongest alternative explanation), but the root-cause reconciliation in step 4 and the item-by-item verification in step 5are not exempted by scale。
- For recurring problems, include "how it was fixed last time" among the suspects — the root cause is often a loop: some fix action itself is feeding the problem.
3. Evidence collection — falsification first, single variable, trace upstream along the flow
- Reverse engine: for each hypothesis, first designthe observation that can falsify it fastest, rather than looking for examples that support it. Confirmatory evidence can be collected indefinitely; one counterexample can settle the case.
- Single-variable discipline: A probe changes only one variable at a time. If you change two things at once and the symptom changes, you have learned nothing.
- System engine: An anomalous value is the output of some production pipeline—walk upstream along the data flow (output ← computation ← input ← source), place observation points at each boundary, and find the handoff where "correct" becomes "wrong".
4. Root-cause reconciliation—the bias firewall guards the gate
Confirmation criteria:The evidence must precisely explain the magnitude and shape of the symptom. If it is off by 75, you must find that 30 plus that 45. An explanation that cannot account for all symptoms is half a root cause—go back to step 2 and add hypotheses.
Before declaring a root cause, run the firewall once: Am I verifying the hypothesis, or defending it (confirmation bias)? Did I choose this hypothesis because of the evidence, or because I recently saw something similar (availability)? Have I really looked for counterexamples?
5. Fix and regression defense line
- Fix the source, not the consumption point. When multiple places need the same kind of protection, fix the data contract or unify the boundary.
- Before fixing the code, first write a failing test to pin down the bug (the test-first threshold applies directly), then watch it turn green after the fix.
- Verify with item-by-item reconciliation, not just equal results—both sides can be wrong by half and still match.
- Ask one question about second-order effects: What shared behavior did this fix change? Who depends on the part that was changed? (The blast radius is not exempt just because it is a bug fix.)
6. Three-strike stop-loss and meta root cause
The same symptomfails three landed fixes(probes and rework sent back by single-variable discipline do not count), or every fix introduces a new problem: stop, do not fix a fourth time. What is wrong is most likely not some line, but your understanding of the architecture, data flow, or the problem itself—go back to step 1 and rebuild, or lay the evidence and blockers on the table with the user.
At the end, ask one more layer of meta root cause:Why could this bug happen? Which defense line was missing (types, contracts, tests, review) that let it slip in—adding that defense line is worth more than fixing this bug.
Non-code scenarios
The same loop with different words: reproduce = obtain the raw data or the complete timeline. For the four hypothesis types, first rule out statistical distortion (definition change/channel change/structural change/real change). Probe = an evidence request that can distinguish hypotheses. Reconciliation = the magnitudes match. Fix = act on the cause, not on the metric—a metric improving does not mean the problem is solved; first ask why the metric improved.
Red flags—stop when these thoughts appear
| Thought | Reality |
|---|---|
| "Let's just change something and try" | A change without a hypothesis is a lottery; even if you win, you do not know why |
| "As long as the numbers match, I can hand it in" | You are fixing the report, not the problem. Faking the definition will eventually blow up somewhere else |
| "Add a retry/fallback and it will be stable" | Masking failure upgrades a random failure into a silent failure |
| "I have the checklist in my head, no need to write it out" | Assumptions that are not brought into the open evade all challenges—including your own |
| "Let's try this direction one more time" (the fourth time) | Three strikes. What is wrong is the understanding, not the technique |
| "The error is too weird, let's bypass it first" | The strangest error is closest to the root cause; bypassing it is equivalent to throwing away the best clue. |