First-Principles Investigation
Paths below are relative to this skill's directory; resolve them to absolute
paths before running anything.
Most "debugging" is reasoning by analogy: this looks like that bug last week, so
it's probably the same cause. That's fast and often right - until it's wrong,
and then it sends you fixing a symptom while the real defect sits untouched. This
skill is the discipline for the times that matters: you trust only what you
have observed in this system, you rebuild your understanding from the ground
up, and you refuse to act on a cause until the evidence forces it.
The whole method rests on one idea from Feynman: the first principle is that you
must not fool yourself - and you are the easiest person to fool. Everything below
is machinery for not fooling yourself.
The stance
These four commitments are what separate a real investigation from "debug
carefully." Hold them the whole way through.
- Ground truth is the running system and its source - not docs, not memory,
not analogy, not what anyone asserted (including the user). Docs drift; the
code and the logs don't. The function you're sure you understand is the one
that bites you. When a claim matters, go read the actual source or reproduce
the behavior yourself.
- Separate evidence from inference, always. "The request returned 401" is
evidence. "Auth is broken" is an inference drawn from it. Confusing the two is
how a plausible story hardens into false certainty. Label them differently in
your own notes and in your report.
- Every hypothesis carries the observation that would kill it. A cause you
can't imagine disproving is worthless - every test will seem to "confirm" it
and you'll learn nothing. Before you go looking, state: what would I have to
see for this to be false? Then go try to see that.
- Don't stop at the first plausible cause. Trace to the true root, and prove
the fix. The first wrong value you find is usually an infection partway
down the chain, not the defect that started it. And a fix you can't toggle
on and off to make the failure appear and disappear is not a proven fix - it's
a hope. If you didn't verify it, it isn't fixed.
Two modes, one method
The same discipline serves two kinds of investigation, and the vocabulary below
leans toward the first - but they're the same method:
- Diagnose a failure - "why is this 500ing", "why did the deploy desync". The
goal is a defect, proven by making the failure appear and disappear.
- Understand a mechanism - "how does
dotenv actually pick a value",
"how does the auth hook resolve claims". There's no bug; the goal is the true
model of how something works, proven by tracing the real code and confirming
each claim.
When you're in mechanism mode, read the failure-oriented words as their
mechanism-mode twins: reproduce → trace and confirm the behavior, root
cause → the mechanism / model, fix & proof → how each claim in the model
is proven. Everything else - the ledger, hypotheses-with-falsifiers, evidence vs.
inference, breadth-before-depth, reading the source over the docs - applies
unchanged, and matters just as much: a "how does it work" answer paraphrased from
the docs is exactly the failure this method exists to prevent.
The core loop
Read references/the-loop.md before the first hypothesis, not after. It holds
the nine phases (frame, ledger, reproduce, read the source, enumerate, test,
converge, trace to root, self-audit) and the rules for when to fan out to
subagents.
Output format
Read references/output-format.md before writing the conclusion, not before
starting the investigation.
Before you conclude - self-audit
Fast pass against the ways a first-principles investigation still fails. Any "yes"
sends you back into the loop. Full catalog with guards in
references/anti-patterns.md.
- Analogy - am I acting on "it's like that other bug" rather than evidence
from this system?
- Confirmation bias - did I only run tests that would confirm my favored
cause, and skip the one that could falsify it?
- Anchoring - am I under-weighting evidence that contradicts my first guess?
- Symptom, not root - is my "cause" actually an infected value partway down
the chain, with an earlier defect still upstream?
- ASSUME as fact - is any step resting on an unverified item I never promoted
to KNOW?
- Authority over evidence - am I trusting an assertion (the user's, a
senior's, the docs') that I could have checked but didn't?
- Unproven fix - can I actually toggle the failure on and off with my change,
or am I hoping?
Going deeper
references/method.md - the canonical grounding: Zeller's scientific-
debugging loop and TRAFFIC workflow, Agans' 9 indispensable debugging rules, and
the full technique toolbox (the cause-category checklist, falsifiability and
cheapest-discriminating-observation, Fermi/constraint checks, correlation vs.
causation, Socratic questioning). Read when you want the depth behind a phase.
references/anti-patterns.md - the failure-mode catalog with concrete
guards. Read at phase 8, or any time the investigation feels stuck or too easy.
references/hypothesis-tester.md - the subagent prompt for swarm mode.
1---2name: first-principles-investigation3description: >-4 Evidence-first root-cause investigation: competing hypotheses, each tested against the5 actual system, until exactly one survives and the fix is proven. Use whenever something6 behaves in a way nobody can explain, a fix did not hold, the obvious cause is already7 ruled out, or the question is how a system really works: "why is CI flaky", "get to the8 bottom of this 500", "why does the deploy drift from main", "root-cause this failure",9 "debug this properly", "this makes no sense, figure out what's going on", "trace where10 this value comes from", even when the user only describes a confusing behavior. Prefer11 it over a domain skill while the cause is still unknown. Do NOT use when the cause is12 known and only the fix is in question, to stress-test a plan (use `grill-me`), to review13 a diff, or for a one-line lookup you can answer directly.14license: MIT15argument-hint: '[optional: the symptom, failing target, error text, or question to investigate]'16metadata:17 source: https://skillmd.com/skills/spencermarx/first-principles-investigation18 ideas: "The open-source First Principles Thinking skill (https://github.com/awesome-skills/first-principles-skill), its framing re-scoped from design evaluation to empirical investigation and not vendored. Method grounded in Andreas Zeller's Why Programs Fail (scientific debugging, TRAFFIC) and David J. Agans' Debugging: The 9 Indispensable Rules; full sourcing in references/method.md."19---2021# First-Principles Investigation2223Paths below are relative to this skill's directory; resolve them to absolute24paths before running anything.2526Most "debugging" is reasoning by analogy: _this looks like that bug last week, so27it's probably the same cause._ That's fast and often right - until it's wrong,28and then it sends you fixing a symptom while the real defect sits untouched. This29skill is the discipline for the times that matters: you trust **only what you30have observed in _this_ system**, you rebuild your understanding from the ground31up, and you refuse to act on a cause until the evidence forces it.3233The whole method rests on one idea from Feynman: _the first principle is that you34must not fool yourself - and you are the easiest person to fool._ Everything below35is machinery for not fooling yourself.3637## The stance3839These four commitments are what separate a real investigation from "debug40carefully." Hold them the whole way through.41421. **Ground truth is the running system and its source - not docs, not memory,43 not analogy, not what anyone asserted (including the user).** Docs drift; the44 code and the logs don't. The function you're _sure_ you understand is the one45 that bites you. When a claim matters, go read the actual source or reproduce46 the behavior yourself.472. **Separate evidence from inference, always.** "The request returned 401" is48 evidence. "Auth is broken" is an inference drawn from it. Confusing the two is49 how a plausible story hardens into false certainty. Label them differently in50 your own notes and in your report.513. **Every hypothesis carries the observation that would kill it.** A cause you52 can't imagine disproving is worthless - every test will seem to "confirm" it53 and you'll learn nothing. Before you go looking, state: _what would I have to54 see for this to be false?_ Then go try to see that.554. **Don't stop at the first plausible cause. Trace to the true root, and prove56 the fix.** The first wrong value you find is usually an _infection_ partway57 down the chain, not the _defect_ that started it. And a fix you can't toggle58 on and off to make the failure appear and disappear is not a proven fix - it's59 a hope. If you didn't verify it, it isn't fixed.6061## Two modes, one method6263The same discipline serves two kinds of investigation, and the vocabulary below64leans toward the first - but they're the same method:6566- **Diagnose a failure** - "why is this 500ing", "why did the deploy desync". The67 goal is a _defect_, proven by making the failure appear and disappear.68- **Understand a mechanism** - "how does `dotenv` actually pick a value",69 "how does the auth hook resolve claims". There's no bug; the goal is the _true70 model_ of how something works, proven by tracing the real code and confirming71 each claim.7273When you're in mechanism mode, read the failure-oriented words as their74mechanism-mode twins: _reproduce_ → **trace and confirm the behavior**, _root75cause_ → **the mechanism / model**, _fix & proof_ → **how each claim in the model76is proven**. Everything else - the ledger, hypotheses-with-falsifiers, evidence vs.77inference, breadth-before-depth, reading the source over the docs - applies78unchanged, and matters just as much: a "how does it work" answer paraphrased from79the docs is exactly the failure this method exists to prevent.8081## The core loop8283Read `references/the-loop.md` before the first hypothesis, not after. It holds84the nine phases (frame, ledger, reproduce, read the source, enumerate, test,85converge, trace to root, self-audit) and the rules for when to fan out to86subagents.8788## Output format8990Read `references/output-format.md` before writing the conclusion, not before91starting the investigation.9293## Before you conclude - self-audit9495Fast pass against the ways a first-principles investigation still fails. Any "yes"96sends you back into the loop. Full catalog with guards in97`references/anti-patterns.md`.9899- **Analogy** - am I acting on "it's like that other bug" rather than evidence100 from _this_ system?101- **Confirmation bias** - did I only run tests that would confirm my favored102 cause, and skip the one that could falsify it?103- **Anchoring** - am I under-weighting evidence that contradicts my first guess?104- **Symptom, not root** - is my "cause" actually an infected value partway down105 the chain, with an earlier defect still upstream?106- **ASSUME as fact** - is any step resting on an unverified item I never promoted107 to KNOW?108- **Authority over evidence** - am I trusting an assertion (the user's, a109 senior's, the docs') that I could have checked but didn't?110- **Unproven fix** - can I actually toggle the failure on and off with my change,111 or am I hoping?112113## Going deeper114115- **`references/method.md`** - the canonical grounding: Zeller's scientific-116 debugging loop and TRAFFIC workflow, Agans' 9 indispensable debugging rules, and117 the full technique toolbox (the cause-category checklist, falsifiability and118 cheapest-discriminating-observation, Fermi/constraint checks, correlation vs.119 causation, Socratic questioning). Read when you want the depth behind a phase.120- **`references/anti-patterns.md`** - the failure-mode catalog with concrete121 guards. Read at phase 8, or any time the investigation feels stuck or too easy.122- **`references/hypothesis-tester.md`** - the subagent prompt for swarm mode.