# grounding-before-coding

The grounding-before-coding skill makes the agent inspect code and data before changing a project or explaining a bug. It fits unfamiliar repositories and non-trivial work.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 25600 installs · ★ 6 repo stars
- Author: riekelt
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/grounding-before-coding/SKILL.md
- Updated: 2026-09-11
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/grounding-before-coding

## What it does

grounding-before-coding sets a research step before implementation. The agent traces actual entry points, reads the code behind names, checks the relevant data, and supports important claims with `file:line`, query results, or command output. For a bug, it must observe the failure before changing the code and inspect every route into a shared area.

The skill also records invariants, existing guards, and repository conventions that a change must preserve. It covers investigations where no edit is planned yet. The required background is the `principal-engineering` skill, so that dependency belongs in the setup plan.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill grounding-before-coding -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/grounding-before-coding/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/grounding-before-coding/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill grounding-before-coding -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/grounding-before-coding/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill grounding-before-coding -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/grounding-before-coding/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install riekelt/principal-engineer plugins/principal-engineer/skills/grounding-before-coding
```

2. **Manually: put the files in place**
- File: `.github/skills/grounding-before-coding/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill grounding-before-coding -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/riekelt/principal-engineer --path plugins/principal-engineer/skills/grounding-before-coding
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/grounding-before-coding/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill grounding-before-coding -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/grounding-before-coding/SKILL.md

## When to use it
- understand an unfamiliar repository
- reproduce a bug before editing code
- trace every caller of shared logic
- support conclusions with code evidence
- record invariants before a change

## Example prompts
- Before changing anything, inspect the project tree and support each key finding with a `file:line` reference.
- Investigate why an export is sometimes empty: reproduce the failure first, then trace the code and data.
- Find every route into this shared code and list the invariants the fix must preserve.

## Similar
- [verification-before-completion](https://affpapa.org/en/nevibecode/skills/ganyuanran-verification-before-completion.md) — skill · ★ 1450 repo stars
- [branch-review-before-pr](https://affpapa.org/en/nevibecode/skills/branch-review-before-pr.md) — skill · 167 installs
- [coding-agent](https://affpapa.org/en/nevibecode/skills/coding-agent.md) — skill · 6500 installs
- [isolate-the-specific-failure-mode-before-proposing-a-fix](https://affpapa.org/en/nevibecode/skills/isolate-the-specific-failure-mode-before-proposing-a-fix.md) — skill · ★ 539 repo stars
- [coding](https://affpapa.org/en/nevibecode/skills/vicotrbb-coding.md) — skill · ★ 121 repo stars
- [confirm-failures-are-causally-linked-to-the-task-before-reportin](https://affpapa.org/en/nevibecode/skills/confirm-failures-are-causally-linked-to-the-task-before-reportin.md) — skill · ★ 539 repo stars

From the same set: [riekelt/principal-engineer](https://affpapa.org/en/nevibecode/by/riekelt/principal-engineer.md) — 11 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
