---
id: gh-grounding-before-coding
name: "grounding-before-coding"
url: https://skills.yangsir.net/skill/gh-grounding-before-coding
author: riekelt
domain: ai-software-architecture-engineering
tags: ["grounding", "code-reading", "debugging", "engineering-practices"]
install_count: 17200
rating: 4.60 (120 reviews)
github: https://github.com/riekelt/principal-engineer/tree/main/plugins/principal-engineer/skills/grounding-before-coding
---

# grounding-before-coding

> 此技能在编码前先系统性地映射真实代码库与数据，引用 file:line 和运行结果作为证据，从源头上杜绝基于猜测的开发。它帮助开发者快速定位问题根源、识别共享缺陷、把握不可破坏的约束，适用于非平凡修改、Bug 调查和陌生代码探索，显著降低返工与线上事故风险。

**Stats**: 17,200 installs · 4.6/5 (120 reviews)

## Before / After 对比

### Bug 定位与修复时间

**Before**:

开发者拿到一个线上 bug 后，常常根据函数名和以往经验直接猜测原因并开始修改，结果改错位置，反复验证和调试，有时还引入新问题，一个原本简单的 bug 可能要耗费半天时间。

**After**:

此技能要求先复现 bug、读取真实代码路径并引用证据，通常几分钟内就能定位到共享根因。修改直接命中所有调用路径，一次性解决，无需返工。

| Metric | Before | After | Change |
|---|---|---|---|
| 定位修复时长 | 180分钟 | 15分钟 | -92% |

### 变更返工率

**Before**:

在没有此技能时，团队改动一个共享模块时常只修了报告的那条路径，忽略其他调用方，导致测试通过后上线仍出问题，平均每三个变更就有一个需要返工或紧急修复。

**After**:

此技能在编码前梳理所有调用路径和不变量，一次改动覆盖所有相关路径，返工率大幅下降。

| Metric | Before | After | Change |
|---|---|---|---|
| 变更返工率 | 30% | 5% | -83% |

## Readme

# 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 cost of grounding is minutes; the cost of building on a wrong belief is the whole change plus the incident it causes.

## The discipline

1. **Read the implementations, not the names.** A method called `validate` that does not validate is common enough to be 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. Guessing conventions is how changes arrive that are correct in isolation and wrong in the codebase.
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. A fix for an unreproduced bug is a guess wearing a diff.
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 are the scars that 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.


---
*Source: https://skills.yangsir.net/skill/gh-grounding-before-coding*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-grounding-before-coding/markdown*