grounding-before-coding skill (riekelt): make Claude read the code before it plans

Makes Claude read the real code and run the real queries before it plans a fix, and quote its evidence.

Installs: 20.4K; on skills.sh
Stars: 7; on GitHub
Updated: Sep 2026; last repo commit

grounding-before-coding makes Claude map the real code and data before it writes a spec, a fix or a first line. Its description covers starting a change, investigating a bug and working in unfamiliar code, and also pure investigation with no change planned. Claude is asked to quote a file:line, a query result or a command output for every claim the plan rests on, and to see a bug fail before changing anything. It names principal-engineering as required background.

Good for

Developers debugging in code they do not know
Anyone who asks Claude to "figure out why" before changing anything
Teams whose fixes keep missing the sibling code paths

Install grounding-before-coding

Claude Code

Copy this prompt.

Install the grounding-before-coding skill in Claude Code. Run this command:

/plugin marketplace add riekelt/principal-engineer
/plugin install principal-engineer@principal-engineer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The plugin installs all 11 skills in the repo, plus one agent (change-verifier) and two commands (/verify and /preflight), counted from the git tree. grounding-before-coding names principal-engineering as required background, so the skills CLI and folder routes below install both. There is no Claude app upload route: the README documents only the Claude Code plugin and the other-agents routes.

From the project README. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

Overview
The discipline
Limits of grounding
Common mistakes

Key facts

Author: riekelt (named as author in the plugin manifest)
License: MIT per the README and plugin.json; the repo has no LICENSE file and GitHub shows none
Installs on skills.sh: 20,366 (Nov 2, 2026)
GitHub stars: 7 for the whole riekelt/principal-engineer repo (Nov 2, 2026)
Last repo commit: Sep 11, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes: 1 file: SKILL.md (counted from the git tree)
Part of: The principal-engineer plugin: 11 skills, 1 agent and 2 commands (counted from the git tree)
Needs: The principal-engineering skill, named as required background in SKILL.md
Works in: Claude Code via the plugin; other agents via a plugin loader or symlinked skill folders, as the README describes

What it includes

Checks what a function does before building on what it is called
A method called validate that does not validate is the default assumption.
Read · Read implementations, not names
A file:line, query result or command output behind each load-bearing claim
When a claim cannot be backed, Claude is told to say so instead of assuming.
Runs code · Quote your evidence
Finds how this repo names, wires and tests things instead of assuming
Naming, dependency wiring, error handling and test running are discoverable in minutes.
Read · Never guess conventions
Checks docs and tickets against the code and git history
A document's self-reported state is not evidence. The skill names git log -S <symbol> and grepping the tree.
Runs code · Trust code, not status
Sees the bug fail before changing anything
For bugs Claude is told to watch the failure happen first.
Runs code · Reproduce before fixing
Finds every route into the code and puts the guard in the shared place
A fix on only the reported path repairs the report, not the bug.
Read · Fix where the callers converge
Lists touchpoints, quoted current behavior and what must not break
Tests named after old bugs, guards with comments and hard-won constants mark earlier incidents.
Read · Map the invariants
Maps the change plus one ring around it, not the whole repo
Three limits: do not read everything, ask when the code cannot answer an intent question, and do not re-ground what the session already established.
Read · Limits of grounding

From the official docs

Permissions

Low risk

grounding-before-coding is instructions for Claude and the plugin route adds an agent and two commands. Our advice: review the diff after each session and keep your tool's permission prompts on.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It tells Claude to run queries and commands to check facts
SKILL.md says to run the query behind every number the plan relies on. Our advice: point your session at a development database or read-only credentials. github.com
The plugin route adds an agent that can run shell commands
change-verifier lists the tools Read, Glob, Grep and Bash, and the plugin adds the /verify and /preflight commands. The repo tree has no hooks or MCP config files. Use the skills CLI route to install only this skill. github.com

Technical details

Turning on read-only	SKILL.md describes no read-only mode.
Sign-in and keys	SKILL.md names no account, key or token.
Scopes	Claude reads files and git history in your repository Claude runs commands and queries to reproduce bugs and check numbers The plugin route also installs 10 other skills, one agent and two commands

Questions

What does grounding-before-coding do?

It makes Claude read the implementations, quote evidence, reproduce a bug and map what must not break before it plans a change. It also applies to pure investigation, such as "figure out why the export is sometimes empty".

How do I install it?

Use the install box at the top. The skills CLI and folder routes add principal-engineering too, because this skill names it as required background. The plugin route installs all eleven skills.

How is it different from verifying-before-done?

Grounding comes before the change and maps the code. verifying-before-done comes at the end and covers proof that the change works, by driving it where a user meets it.

Does it make Claude read the whole repository?

No. SKILL.md says to map what the change touches plus one ring around it, at the depth the risk demands, and to ground once per session.

Does it work in the Claude app or Codex?

The README documents the Claude Code plugin and, for other agents, a plugin loader pointed at plugins/principal-engineer/ or symlinked skill folders. It documents no Claude app upload route.

Is it safe to install?

The skill folder bundles no scripts. It tells Claude to run commands and queries to check facts, so it runs in your repository and against whatever data your setup can reach. The plugin route also adds an agent, covered under "Watch out for".

Information

updated Nov 2, 2026

Repository: riekelt/principal-engineer
Folder: plugins/principal-engineer/skills/grounding-before-coding

riekelt/principal-engineer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

grounding-before-coding SKILL.md · github.com
principal-engineering SKILL.md · github.com
README · github.com
plugin.json · github.com
change-verifier agent · github.com