Menu

Individual skill

code-theory

Builds a Naur-style theory of a codebase — the understanding needed to change it without damaging its conceptual integrity. Use when inheriting an unfamiliar system, capturing design rationale, or recovering lost design intent. Writes `THEORY.md` plus any drift and contradictions it finds to `.issues/`.

skills/code-theory/SKILL.md

Read pinned source

Source commit 83315e4f8206fad56f9791a8f7884eec5609296a

What was checked

Matches the observed repository HEAD
Yes
Scanner rules are current
Yes
Repository scan complete
No
Skill scan complete
Yes
Observed behavior
Network or broad shell
Last checked
Nov 5, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

Standard SKILL.md format has not been attested at this commit. No installation command is available; inspect the source.

Repository context

Repository stars (not skill ratings)
14
Repository last updated
Nov 6, 2026
License
MIT

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files
Read excerpt

Build and express a theory of this codebase in the sense Peter Naur meant in "Programming as Theory Building": not a summary of what files exist, but an account of the understanding a competent maintainer would need to hold in mind to modify this system without damaging its conceptual integrity.

Scope the investigation to `$ARGUMENTS` if provided, otherwise treat the whole repository as in scope. Examples: `the scheduler`, `src/billing/`, `the plugin system`.

Skip vendored dependencies, build output, generated code, and lockfiles (`node_modules/`, `dist/`, `vendor/`, `*.min.js`, `go.sum`).

## Phase one — investigation

Read widely before you read deeply.

1. **Orient.** Entry points, build configuration, top-level module structure. Enough to know what runs and in what order.
2. **Follow the grain.** Trace a few representative flows end-to-end. A flow you can follow from input to durable effect teaches more than ten files skimmed.
3. **Read the tests.** They record which behaviors the authors considered load-bearing. A behavior with an exhaustive test suite and a behavior with none are telling you different things.
4. **Read the history.** Recent commits, design notes, ADRs, long comments. These are the decisions the authors thought worth recording — and the ones they kept revisiting.