Start here

This guide is for developers who build software with AI coding agents such as Claude Code or Codex. It takes ten recurring situations in which software projects go wrong, explains why a purely rational process cannot handle them, and shows where Matt Pocock’s engineering skills for AI agents give you a handle on each one.

If you already know David Chapman’s work on meta-rationality, skip to the first situation. If you already use Pocock’s skills, the skills index shows which pages use each one.

Three ways of working

Chapman distinguishes three ways of getting things done. None of them is a type of person; they are aspects of activity, and most real work mixes all three.

• Reasonable activity is the everyday, improvised, context-dependent way people get by: knowing how, not knowing that; counting something as a customer because that is what matters right now.
• Rational activity works inside a formal system: a specification, a type system, a proof, a procedure. It is systematic, general, and detached from context, and that is exactly what makes it powerful and reliable within its boundaries.
• Meta-rational activity is the work of relating the two: choosing which formal system to use, noticing when the system and the situation have drifted apart, deciding what counts as the problem, and revising the categories, procedures, and purposes that the rational work depends on.

Software development is unusually dependent on the third kind. A program is a perfectly formal object built for purposes that are not formal at all, running in a world that keeps changing. Most of the ways projects fail are failures to notice or manage that gap, not failures of logic inside the program.

Chapman’s table

Chapman summarises the three ways of working as a table of aspects. Each situation page in this guide names the rows it touches, so the table is reproduced here once for reference.

Aspect	Reasonable	Rational	Meta-rational
Relationship with reality	Interactive	Detached	Reflectively relating formalism and reality
Breadth of considerations	Context-dependent	Universal	Context-crossing
Effective action	Ad hoc	Systematic	Meta-systematic
…	Improvised	Procedural	Flexible contextual use and revision of procedures
Purposiveness	Purpose-laden	Purpose-independent	Evaluating and coordinating purposes
Contingencies	Routine	Exceptional or problematic	Anomalous, paradoxical
… Problems	Everyday hassles	Solution specifications	Messes to manage
Inference	Accountable, negotiable	Truth-preserving	Meta-epistemic
Epistemology	Informal	Formal	Relating formal and informal
…	Concrete	Abstract	Crossing abstraction levels
…	Specific	General	Relating details with big picture
…	Tacit	Explicit	Relating implicit and explicit
…	Knowing how	Knowing that	Understanding in context
…	Reasonable account	Rigorous theory	Context-crossing understanding
Ontology	Nebulous	Clear-cut	Relates formal patterns and nebulosity
… Categories	Counting-as	Rigorous definition	Reflection on boundaries
… Truth	Purposive, contextual	Absolute	“In what sense?”

The right-hand column is what this guide is about. Read across any row and you have a diagnosis: when a project is stuck, ask which column the team is working in and whether the situation still allows it.

What a skill is

A skill, in Pocock’s toolkit, is a short written procedure that an AI coding agent follows when you invoke it, usually by typing a slash command such as /grill-me or /prototype. Some skills interrogate you until a plan is sharp. Some produce a document: a spec, a questionnaire, a glossary entry, a set of tickets. Some run a discipline over code: test-first implementation, a two-axis review, a diagnosis loop. They are plain text, they live in a repository, and you can read every one of them.

Skills are rational instruments: procedures. What makes them useful for meta-rational work is that several of them exist precisely to reopen questions a rational process would treat as settled. A grilling refuses to accept a request as the problem. A questionnaire admits that the knowledge you need belongs to someone else. A prototype puts an artifact into people’s hands before anything is specified. A domain-modeling session challenges the words everyone has been using without noticing they disagree. Used with that intent, the skills become the places in a workflow where the frame itself can change.

This guide covers Pocock’s engineering and productivity skills. His in-progress and miscellaneous skills change too often to document.

How the guide is organised

The ten situations are grouped into five phases. The phases are a reading order, not a claim that a project passes through them once; most projects cycle through all five repeatedly.

• Purposes: why are we building this, and whose purposes count?
• Ontology: what things are we talking about, and do we agree on the words?
• Building: how do we make progress when we do not yet know enough?
• Maintaining: how do we live with the code that exists?
• Judgment: the developer as the instrument, and how that instrument grows.

Every situation page has the same shape:

1. An example from the readings, then the meta-rational perspective on the situation.
2. The failure path: a diagram of how the situation goes wrong when handled purely rationally. Red outlines mark break points, where the process loses contact with the situation. Dashed boxes mark steps that get skipped.
3. The corrected path: the same diagram with skills inserted at the break points, and the feedback loops that the failure path lacked.
4. A table of the skills involved: when to invoke each one in this situation, what it changes, and an example of what to type.
5. Sources.

Nothing on these pages is quoted. Every idea is paraphrased and traced to its source in the list at the foot of the page; where a source is a paid post, the link is there but the content is not summarised beyond a line.

How to read the diagrams

Every situation page carries two charts of the same shape. The first is the failure path: the steps a purely rational process takes, with the places it loses contact with the situation marked. The second is the corrected path: the same steps with skills inserted where the breaks were, and feedback loops the failure path never had.

LegendExpand

• A red outline is a break point, where the process stops looking at the situation.
• A dashed, faded card is a step the process skips.
• A teal pill names a skill inserted at that step. Hover for its purpose; click to read about it in the skills index.
• A red dashed loop above the cards shows the failure repeating: the same process restarting with the same blind spots.
• A teal dashed loop shows a misfit feeding back early, before it becomes expensive.

Use the Expand control under any chart to see it at full width.

The two sources

David Chapman is the author of Meta-rationality, a book in progress about how to work with formal systems in a world that does not fit them. Its fourth part is largely about software, and a companion reading list collects the blog posts, papers, and books that shaped it. This guide draws on that list.

Matt Pocock is a TypeScript educator who maintains an open repository of skills for AI coding agents, together with the conventions they assume: a CONTEXT.md glossary, architecture decision records, an issue tracker, and a set of triage labels.

Sources

• David Chapman, Meta-rational software development: Readings (part-paid post).
• David Chapman, Meta-rationality: An introduction.
• David Chapman, Part Four: Taking meta-rationality seriously, where the table of aspects appears.
• Matt Pocock, skills repository.