SKILL.md
Grounding before coding
REQUIRED BACKGROUND: the principal-engineering skill.
Overview
Before writing a spec, a fix, or a first line: map the real code and data. Quote file:line and run the query behind every number you rely on.
The discipline
- Read the implementations, not the names. A method called
validatethat does not validate is the default assumption. Verify what a thing does before building on what it is called. - Quote your evidence. Every load-bearing claim in your plan gets a
file:line, an exact query result, or a command output. When you cannot back a claim, say so out loud instead of assuming it. - Never guess conventions. How this repo names things, wires dependencies, handles errors, or runs tests is discoverable in minutes.
- Trust code, not status. A document's or ticket's self-reported state is not evidence of execution state; adjudicate with the code and the history (
git log -S <symbol>, grep the tree) before building on it. - Reproduce before fixing. For bugs: see the failure happen before changing anything.
- Fix where the callers converge. A bug report names one symptom on one path; before editing, find every route into the code you are about to touch. When the defect lives in something shared, the guard belongs in the shared place: it is the smaller diff AND the fix that covers the sibling paths the ticket never mentioned. Patching only the reported path repairs the report, not the bug.
- Map the invariants a change must not break. The output of grounding is a map: the touchpoints, the current behavior (quoted), and those invariants. Tests named after old bugs, guards with explanatory comments, and constants encoding hard-won thresholds mark earlier incidents.