A Claude Code skill that makes the agent scope a software problem before it designs or writes anything — by recovering the theory of the domain first.
It's one markdown file. The value is the stance, not the code.
In 1985 Peter Naur argued, in Programming as Theory Building, that the real product of programming is not the source text but a theory held in the programmer's mind: a working understanding of how the program corresponds to the world it acts in, and why it is shaped the way it is. The code is a secondary, lossy projection of that theory. When the people who hold the theory leave, the program effectively dies — no one can any longer say why it is the way it is, or how a change in the world should be reflected in it.
Most agent interactions skip straight to solution-theory: turn the request into code. Cartographer makes the agent build problem-theory first — state what the world is, who holds its current understanding, and how it maps onto the program — and check that with you before committing to structure. The deliverable of scoping becomes a small, checkable map, not a spec or a ticket list.
It's deliberately calibrated to be rigorous without being obstructive: it keeps momentum when the theory is obvious, and only pauses to confirm when confidence is low or the cost of being wrong is high.
Skills live in a skills/<name>/ directory that Claude Code reads at startup.
Personal (available everywhere):
git clone https://github.com/spinchange/cartographer-skill
cp -r cartographer-skill/skills/cartographer ~/.claude/skills/On Windows (PowerShell):
git clone https://github.com/spinchange/cartographer-skill
Copy-Item -Recurse cartographer-skill\skills\cartographer $HOME\.claude\skills\Per-project (checked into a repo): copy skills/cartographer into that
project's .claude/skills/ instead.
Start a new session so the skill registers, then either invoke it explicitly
with /cartographer, or let it auto-trigger when a request is fuzzy or
domain-heavy.
At rest the skill is invisible to the model except for its one-line
description (progressive disclosure) — roughly 70 tokens. The full body loads
only when the skill is actually invoked.
The idea is entirely Peter Naur's. This skill is just an attempt to operate it.
- Peter Naur, Programming as Theory Building, 1985.
CC BY 4.0 — share and adapt with attribution.