grounding-before-coding

Summary

---
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.

Security audits