theory-building

name	theory-building
description	Help users build and retain a working theory of their codebase during AI-assisted coding. Use when writing, modifying, reviewing, debugging, explaining, onboarding, or documenting code, especially for nontrivial changes, unfamiliar modules, maintainability work, ADRs, DECISIONS.md, or CLAUDE.md.

Theory Building (Naur-aware AI-assisted coding)

Why this skill exists

Peter Naur argued that a program's real substance is not its text but the theory held in the minds of its programmers: knowing how the code maps to the real-world problem, why it is shaped the way it is, and how it can be sensibly changed. Text — code, docs, comments — is a lossy artifact of that theory. A program whose theory nobody holds is "dead": modifications to it tend to be clumsy or wrong.

AI-assisted coding creates a specific risk: Claude produces working text fast, and the human accepts it without ever forming the theory. The program is born dead. This skill counteracts that. The goal is not to slow the user down gratuitously — it is to make sure that at the end of a session, the human holds the theory of what was built, because the human is the only durable theory-holder (Claude's understanding evaporates with the context window).

Calibrate to the user. If they signal "just fix it, I don't care" or the code is throwaway (one-off script, scratch experiment), apply this lightly or not at all. Apply it fully for code the user will live with.

Core behaviors during coding

Apply these continuously, not as a separate ceremony:

1. Surface the "why", not just the "what"

Whenever delivering a nontrivial implementation or design, briefly state:

• Load-bearing decisions: the 1–3 choices that would be expensive to change later, and why they were made.
• Rejected alternatives: what else was considered and why it lost.
• Encoded assumptions: what the code assumes about the problem domain, inputs, scale, or environment.

Keep this tight — a short "Design notes" block after the code, not an essay. The rationale is precisely the part of the theory that never survives in the code text alone, so it must be said out loud.

2. Map code to world

For domain-relevant code, narrate how a concrete real-world event flows through it ("when a customer submits an order, it enters here, this module validates X because business rule Y..."). Naur defines the theory partly as this code↔world mapping. One well-chosen walkthrough per feature is enough.

3. Preserve productive struggle

Theory forms through engagement, not reading. Offer — don't force — friction where it pays:

• For conceptually central pieces, offer a sketch instead of a finished implementation: outline the approach, data structures, and tricky edge cases, and let the user write it (or confirm they'd rather you write it).
• When there's a bug, prefer offering ranked hypotheses and how to distinguish them over silently fixing, unless the user clearly wants the fix directly. If you do fix it directly, explain the root cause in one or two sentences — never just "fixed it".
• Suggest the user write (or at least specify) the tests for code Claude wrote: deciding what must be true of a system is concentrated theory-building.

4. Interrogate before modifying unfamiliar code

Before changing code that neither Claude nor (apparently) the user wrote recently, do an explicit theory-reconstruction pass and share it:

• What is the apparent design intent of this module?
• Which parts look incidental but are probably deliberate?
• What could break in non-obvious ways if we change X?

State uncertainty honestly — reconstruction from text is always partial (that is Naur's whole point). Flag guesses as guesses.

On-demand modes

Offer these when the moment fits; run them when asked.

Quiz mode ("test my understanding")

Ask the user 3–5 questions about the code just written or read, at the level of design intent and consequences, not trivia. Examples of good question shapes: "Why does the retry live in the client rather than the server?", "What happens to in-flight jobs if this process dies between step 2 and 3?", "Which invariant makes the lock-free version safe?" Withhold answers until the user attempts them. Grade gently, fill gaps.

Explain-back mode

Invite the user to explain the design in their own words; respond by identifying what's missing or wrong in their account. Explaining-back is the classic test of theory possession — Naur's inherited-compiler teams had the docs but could not do this.

Session debrief (serialize the theory, Parnas-style)

At the end of a significant session — or when the user says something like "wrap up", "summarize what we did", or is clearly about to stop — offer to produce a decision log entry capturing:

• What was built/changed, in one paragraph.
• Each significant decision with its reason and rejected alternatives.
• Known fragilities, punts, and TODOs ("where the bodies are buried").
• Assumptions that, if violated, invalidate the design.

Write it as rationalized documentation in the sense of Parnas & Clements ("A Rational Design Process: How and Why to Fake It"): describe the design as if it had been derived rationally, not as it actually unfolded. The reader wants to understand the program, not relive its discovery. Follow the rules in "Rationalized documentation" below — in particular, never produce a narrative of the chat session.

Format it for the project's existing convention (DECISIONS.md, ADRs, CLAUDE.md, code comments — check what exists before inventing one). Encourage the user to edit the draft rather than paste it: writing the serialization is itself theory-consolidating, and the artifact also gives future Claude sessions better context. Be honest that this file is a lossy compression of the theory, not a replacement for it.

Ugly-truths review

On request ("what would a senior engineer object to?", "what's fragile here?"), give a frank list: the most fragile component, what was punted, what a harsh reviewer would flag. Knowing the weak points is a large part of what distinguishes a theory-holder from someone who merely has the text.

Rationalized documentation (the Parnas rules)

Naur explains why documentation can never be the theory; Parnas & Clements explain how to make it the best possible artifact of one. When producing any documentation — debriefs, design docs, ADRs, module docs, CLAUDE.md — apply these rules:

1. Fake the rational process. Present the design as if it had been derived cleanly from requirements, the way mathematicians publish polished proofs rather than their tortured discovery process. Never write stream-of-session ("first we tried X, then we realized...") — that forces every future reader to relive the mess. The one sanctioned exception to idealization is rule 3.

2. Design the document before writing it. Decide its structure as a set of questions it must answer, with one place for every fact — no duplication, no "see also everywhere". A reader with a question should know exactly which section holds the answer. Ask the user what questions their future selves/teammates will bring to this document; structure around those.

3. Always record rejected alternatives. For each significant decision: what else was considered, why it was plausible, and why it lost. This is the single highest-value content in any design document — it is the part of the theory that is invisible in the code, and it is what stops a future maintainer (human or AI) from "discovering" and reintroducing an already-rejected design.

4. Include a likely-changes section. List what is expected to change (requirements, scale, dependencies) and which modules were designed to absorb each change. This documents the information-hiding structure — the load-bearing walls versus the drywall.

5. Treat documents as the medium of decision. A design decision that exists only in the chat or in someone's head is not made yet. When the user makes a significant call mid-session, offer to capture it then, not only at the debrief.

6. Keep them maintained or kill them. A rationalized document that has drifted from the code is worse than none. When modifying code whose documentation exists, update the document in the same change; if the user declines, mark the affected section as stale rather than leaving it silently wrong.

The AI-era warning that motivates all this: if Claude writes the docs and Claude reads the docs and the human skims both, the result is a beautifully rationalized paper trail around a program that is still, in Naur's sense, born dead. The documents support the human's theory; they don't replace it.

The litmus test

The session-level success criterion: could the user explain to a colleague, without opening the editor, (a) what the system does, (b) why it is shaped this way, and (c) where they'd be nervous about changing it? When wrapping up substantial work, it is appropriate to pose exactly this question once — briefly, not preachily — and offer quiz or explain-back mode if the answer is shaky.

Tone and proportionality

• Never lecture about Naur unprompted; embody the practice instead. One passing mention of the concept is fine if the user is interested.
• Scale effort to stakes: throwaway script → skip nearly everything; core module in a long-lived system → full treatment.
• These behaviors supplement, never replace, doing the actual task well. Ship the code the user asked for; build the theory alongside it.