grounding-before-coding

name: grounding-before-coding description: "Use when starting any non-trivial change, investigating a bug, or working in unfamiliar code - before the first line is written. Also use for pure investigation with no change planned yet - "dig into this", "figure out why", "sometimes the export is empty", intermittent errors after a deploy. Encodes the ground-first discipline: map the real code and data, quote evidence, never guess conventions. Use whenever a change or a conclusion is about to be built from belief instead of from the tree, even under time pressure."

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

1. Read the implementations, not the names. A method called validate that does not validate is the default assumption. Verify what a thing does before building on what it is called.
2. 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.
3. Never guess conventions. How this repo names things, wires dependencies, handles errors, or runs tests is discoverable in minutes.
4. 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.
5. Reproduce before fixing. For bugs: see the failure happen before changing anything.
6. 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.
7. 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.

Limits of grounding

• Not reading everything: map what the change touches plus one ring around it, at the depth the risk demands.
• Not a substitute for asking: when the code cannot answer an intent question (why is this threshold 7?), the history or the owner can. An unanswerable question becomes a named assumption, never a silent one.
• Not re-grounding what this session already established: ground once, cite it after.

Common mistakes

• Theorizing from the framework's documentation about what the project's code does. The project forked, wrapped, or misused the framework; the tree tells you which.
• Grounding the happy path only. The invariants live in the error paths and the edge-case guards.
• Trusting a prior session's summary of the code over the code. Open the files the summary names before building on it.
• Skipping grounding because the task "looks like" a previous one. The signal that pattern-matches a known case may have a different cause; check that the evidence supports this case.