Glossary
Two vocabularies meet in this guide. Chapman’s names the kinds of trouble; Pocock’s names the artifacts and procedures. The guide’s own structural terms are listed last.
Chapman’s terms
Section titled “Chapman’s terms”Reasonable, rational, meta-rational
Section titled “Reasonable, rational, meta-rational”Three aspects of activity, not three kinds of person. Reasonable activity is improvised and context-bound; rational activity works inside a formal system; meta-rational activity relates the two, choosing, evaluating, and revising formal systems in the light of the situation. The start page has the full table of aspects.
Nebulosity
Section titled “Nebulosity”The property of most real things of having no definite boundaries, no fixed essence, and no single correct description. Purposes, categories, and problems are nebulous. Nebulosity is not the same as vagueness in someone’s head; it is a feature of the situation that a formal model has to cope with.
A situation that is not yet a problem: tangled, purpose-laden, and not formalisable as it stands. Rational work needs a Problem; meta-rational work shapes one out of a mess, and accepts that the shaping is provisional.
Problem, with a capital P
Section titled “Problem, with a capital P”A formally stated task with a definite criterion of success: a specification, a theorem to prove, a ticket with acceptance tests. Rationality solves Problems. Where Problems come from is not a rational question.
Ontology
Section titled “Ontology”The set of kinds of things a formal system recognises: the entities, categories, properties, and relationships a program’s data model commits to. Every program has one, whether or not anyone chose it.
Ontological remodeling
Section titled “Ontological remodeling”Changing the ontology rather than the details: splitting a category, merging two, introducing a kind of thing that was not there before. It cannot be done inside the rational system because the system takes the ontology as given.
Counting-as
Section titled “Counting-as”The everyday act of treating something as a member of a category for present purposes, without a rigorous definition: counting a prospect as a customer because that is what the conversation needs. Data models freeze counting-as into definitions, which is where edge cases come from.
Circumrational
Section titled “Circumrational”The informal, practical work around a formal system that keeps it applicable: cleaning inputs, handling exceptions by hand, knowing which outputs to distrust. Shielding a system from cases it cannot handle is circumrational work; enlarging the system to handle them is a different choice.
Context
Section titled “Context”Everything a formal system leaves out that still matters: who uses the software, what they are trying to do, what else is going on, what will change. Meta-rational work is context-crossing because the relevant context is never entirely inside one person’s view.
Pocock’s terms
Section titled “Pocock’s terms”A written procedure, kept as a SKILL.md file, that an AI coding agent follows when invoked, usually by a slash command. See the skills index.
CONTEXT.md
Section titled “CONTEXT.md”The project glossary: the domain vocabulary the skills read before exploring a codebase and update when terms are settled. In multi-context repositories a CONTEXT-MAP.md points to one per context.
Architecture decision record: a short dated document in docs/adr/ recording a consequential decision and the reasons for it. Skills flag when their output contradicts an existing ADR.
A description of a piece of work synthesised from a conversation and published to the issue tracker. Treated as a snapshot that can go stale, not as the truth about what is needed.
Tracer-bullet ticket
Section titled “Tracer-bullet ticket”A ticket that is a thin vertical slice through every layer, rather than a horizontal task. Tickets declare which other tickets block them.
Wayfinder map
Section titled “Wayfinder map”A single issue holding notes, decisions so far, and fog (open questions), with child tickets for research, prototypes, grillings, and tasks, worked one at a time toward a named destination.
Triage labels
Section titled “Triage labels”Five states an issue moves through: needs triage, needs info, ready for an agent, ready for a human, will not fix. Will not fix is a legitimate outcome, not a failure.
This guide’s terms
Section titled “This guide’s terms”Situation
Section titled “Situation”One recurring software-development predicament that gets a page. Not a topic or a chapter.
One of the five sidebar groups: Purposes, Ontology, Building, Maintaining, Judgment. A reading order, not a process model.
Aspect
Section titled “Aspect”A row of Chapman’s table. Each situation page names the aspects it touches under its title.
Failure path
Section titled “Failure path”The diagram of how a situation goes wrong when handled purely rationally. Red outlines mark break points; dashed cards mark skipped steps.
Corrected path
Section titled “Corrected path”The same diagram with skills inserted at the break points, and the feedback loops the failure path lacked.
Break point
Section titled “Break point”A node on the failure path where the rational process loses contact with the situation. On the corrected path it is where a skill is inserted.
Context-fit check
Section titled “Context-fit check”A third review question, added to Pocock’s two-axis code review on several pages: what did encountering this implementation reveal about the request’s assumptions, categories, purposes, or setting? It is the only review question permitted to conclude that the spec was wrong.
Invocation
Section titled “Invocation”The one-line phrase a developer types to trigger a skill in a given situation. Every invocation in the guide is collected on the cheat sheet.