Debugging by constraints

Code is an unreliable narrator: it says what can happen, not what did happen. Start from what did happen.

The work sits on two tiers:

• Facts are data a tool or a person gathered: the bug report, logs, metrics, traces, config, flag values, versions, deploy history, git history, profiles, packet and DNS data. Docs, help text, specs and existing tests are facts about intended behaviour. You read facts. You never edit or argue them away. A fact that looks wrong gets gathered again, or goes back to whoever produced it.
• Code facts record what the code says, with its location (C3: incidents.ts:480 groups rows with groupByIdKeepAll). Code says only what can happen, so a code fact can explain a mechanism but never serves as the strongest signal.
• Hypotheses are everything you infer: causes, theories, narratives, and every repro you build. A repro becomes a source of facts once it shows the reported symptom. A hypothesis lives only while it fits every fact.

Each fact is a constraint. The job is to find the one hypothesis (a single cause, or a combination where every cause is needed) that fits every fact. Keep the facts fat and the hypotheses thin.

Guardrails

• Production is read-only for you. Ask the user before any command that restarts, scales, writes, deletes, or flips a flag. Before a restart you get approval for, capture what it destroys: thread stacks, open connections, IPC state, a memory profile.
• Before you start an app locally, find what it calls out to on start (seed data, schedulers, health checks, webhooks) and turn those off first. A local stack is a repro, which Step 3 treats as a hypothesis. It is never a source of facts for the matrix; gather facts from where the bug happened.
• Keep the numbered fact list and the matrix in one working file and update it in place. A new fact takes the next number. Nothing is renumbered or dropped. Re-read the file before you add a hypothesis or change the winning row, so no earlier finding is walked past. A finding that is not in the file does not exist.
• Write <REDACTED> in place of every secret in commands, outputs and artifacts you show. Quote only the lines that carry the signal.