Skip to content
Meta-Rational Software Development with Engineering Skills for AI

Nobody knows what the problem is: requirements arrive as solutions

Aspects: relationship with reality · purposiveness · problems (messes to manage)

Signals you are in this situation

Section titled “Signals you are in this situation”
  • The ticket describes a feature, not the trouble it is meant to remove.
  • Nobody can say who will use the result or what they will do next with it.
  • Words like complete, done, valid, or approved appear without a definition.
  • The first time anyone outside the requesting team will see the work is after it ships.
  • Objections are already being filed as change requests before anything is built.

The situation

Section titled “The situation”

An analyst asks for a dashboard that marks a reconciliation as complete when two imported totals agree. The team builds exactly that. It works, the tests pass, and it ships. The first time operations opens it, they refuse to hand the batch over: nobody has looked at the exceptions, so nothing is complete in any sense they care about. No line of code was wrong. The word “complete” had been carrying three different meanings, and the request, taken at face value, chose one of them without anyone noticing.

Michael Jackson observed thirty years ago that software education trains people to hurry through the tedious business of finding out what the problem is, so that the real work of design and programming can begin. The problem gets stated in a few words and the difficulty is assumed to lie entirely in the solution. Einar Høst’s list of questions shows why that assumption fails: who defined this problem, who agrees it is one, whose interests it serves, how long it has existed, what happens if it is only partly solved, how often it changes. A team cannot answer all of those, and yet the enterprise depends on them. A long Hacker News thread on the subject reaches the same conclusion from the trenches: the people who pay for software usually have only a vague idea of what they want, and when they are specific and forceful they are usually specific about a solution, not a problem.

The meta-rational perspective

Section titled “The meta-rational perspective”

A rational process needs a Problem in a formal sense: a specification against which a solution can be checked. Requirements analysis exists to manufacture that object. The trouble is that the object does not exist in advance. What exists is a nebulous situation, a mess in Chapman’s sense, out of which a problem has to be shaped, and the shaping is meta-rational work. Where the problem came from is not a rational question, because rationality starts once the problem is given.

Three things follow. First, a request is evidence about the situation, not a description of it. The analyst’s request tells you that matching totals matter to the analyst; it tells you nothing about what operations needs to know before a handoff. Second, the relevant knowledge is distributed. Understanding of a company’s work is spread through the workforce and never fully centralised, so the people whose context is missing cannot be replaced by asking the requester harder questions. Third, understanding emerges from contact. Høst describes the relationship between a fundamentally unstable problem and a machine that longs for stability as a dance that has to be kept going without toppling over. You learn what the problem is partly by building candidate solutions and watching them meet reality. A process that defers that contact until after sign-off has arranged to learn the most important thing last.

The failure is not that the requirements were wrong. It is that the process treated requirements as an input rather than as something the project produces.

Failure path

Section titled “Failure path”
1 Request arrives “Mark reconciliation complete when the totals match” 2 Copy the request into requirements 3 Name the things skipped: “complete” left undefined 4 Try it early skipped 5 Sign-off freezes the spec 6 Build to spec tests pass 7 Encounter in use “We can't hand this over” “requirements were wrong”: change request
How the situation goes wrong when handled purely rationallyHow to read

The request is copied into a requirements document, which is then signed off, which freezes it. Nobody asks what “complete” means, because the request did not seem ambiguous. Nothing is put in front of operations until the finished product is. When the misfit surfaces, it is filed as a change request and the same process starts again with the same blind spots.

Corrected path

Section titled “Corrected path”
1 Request arrives “Mark reconciliation complete when the totals match” 2 Find the problem grilling: Interviews you round by round until nothing about a plan is left silently assumed.grilling to-questionnaire: Turns a question you cannot answer into a questionnaire for the person who can.to-questionnaire 3 Name the things domain-modeling: Challenges overloaded terms and writes the glossary and decision records.domain-modeling → CONTEXT.md: The project glossary: the domain vocabulary every skill reads and writes.→ CONTEXT.md 4 Try it early operations performs a handoff prototype: Builds throwaway code that answers one design question.prototype 5 Specify to-spec: Synthesises the conversation into a spec and publishes it to the tracker.to-spec 6 Build tdd · implement: The red-green-refactor loop with rules for tests worth keeping.tdd · implement 7 Encounter in use code-review: Reviews a diff for standards and spec conformance in parallel sub-agents.code-review context-fit check: A third review question: what did building this reveal about the request itself?context-fit check misfit: revise the frame, not just add a feature misfit, before any spec
The same path with skills inserted at the break pointsHow to read

The shape is the same: a request still arrives and code still gets built. What changes is that the problem is treated as unknown until it has been interrogated, the words in it are pinned down before they are built on, and something runnable reaches the people whose context was missing before any spec is written. The two feedback loops are the point. Misfit discovered at step 4 goes back to step 3 cheaply. Misfit discovered in use goes back to the frame, not straight into a new feature request.

Skills for this situation

Section titled “Skills for this situation”
Skill When to invoke it here What it changes Example
grilling (via /grill-me) As soon as the request arrives and before anything is written down as a requirement. Refuses to accept the request as the problem. The interview keeps asking what would have to be true for “complete” to be right, until the decision tree behind the request is visible. /grill-me the request for a reconciliation-complete dashboard
to-questionnaire When grilling reaches a question the requester cannot answer, because the knowledge belongs to another role. Turns the gap into a document for one named person to fill in, so the missing context is fetched from where it lives rather than guessed. /to-questionnaire for the operations lead: what has to be true before a batch can be handed over?
domain-modeling (or /grill-with-docs to combine it with grilling) The moment a word turns out to carry more than one meaning. Splits “complete” into matched, reviewed, and handed off, records the terms in CONTEXT.md, and captures the decision as an ADR so the distinction survives the project. /grill-with-docs the reconciliation dashboard
prototype Before writing a spec, once the candidate model exists. Produces throwaway code that answers the design question. Ask an operations person to perform an actual handoff with it, not to approve its appearance. /prototype a state model for a batch moving from matched to reviewed to handed off
to-spec Only after the prototype has met the people it affects. Synthesises the clarified problem into a spec and publishes it to the tracker. Writing it earlier would freeze the request instead of the problem. /to-spec
tdd and implement For the build itself. Unchanged from a rational process, which is the point: the meta-rational work happened before it. /implement issue #14
code-review At the end, with one added question. The skill checks standards and spec conformance. Add a third question the skill does not ask: what did encountering this implementation reveal about the request’s assumptions? Treat an answer as a reason to revisit step 3, not as a bug. /code-review against main, then: what did this reveal about the original request?

Sources

Section titled “Sources”