It does exactly what was asked and it is still wrong

Aspects: relationship with reality · inference (meta-epistemic) · epistemology (relating implicit and explicit, understanding in context) · contingencies (anomalous)

Signals you are in this situation

• Acceptance tests pass and users route around the feature.
• Objections begin with it works, but.
• Every objection becomes another feature ticket.
• The spec has not changed since approval despite what shipping taught.
• Reviews check code and spec but never whether the spec fits the situation.

The situation

Chris Krycho describes a set of memory leaks in Node servers at LinkedIn that eventually took the site down every long weekend between deploys. Nothing in the servers was wrong by its own lights. The cause turned out to be a mix of old technical debt, gaps in observability, growing load, configuration mistakes that review had not caught, an organisation-wide memory reduction made for efficiency, and a single point anywhere in the system that could respond to an unhealthy node. Other teams had made perfectly reasonable design decisions that conflicted with this system, because to them it was a tiny fraction of the whole. Every part had passed its checks. Nobody had a view of the system as a whole, and until someone built one, and added enough tracing to see it, progress was impossible.

Justin Etheredge puts the general form in one line: the hardest part of software is building the right thing. You can design the most technically impressive system in the world and have nobody want it, and that happens all the time. The reason engineers resist the point, he suggests, is that it seems to devalue their work. It does the opposite: it locates the difficulty in the irrationality of the environment the work has to fit.

The meta-rational perspective

Rational verification answers a rational question: does the artifact satisfy its specification? Tests, types, and review are excellent at that, and this guide does not ask you to trust them less. The trouble is that satisfying the specification and serving the situated purpose are different properties, and a process that only checks the first will pass software that fails the second. Krycho’s phrase for why is that programming is lossy compression. The model in your head of what the software is for is fuzzy and mostly implicit; writing it down loses detail; and once the software leaves the world you control and enters the world where the choices are not yours, the compression gets far lossier than you notice. The edge cases can be infinite because the world is. A green test suite derived from an incomplete framing is not ten independent confirmations of that framing. It is one framing, checked ten times.

So the encounter with use has to be treated as an instrument, not an afterthought. Chapman’s discussion of instructed activity makes the same observation from the other direction: instructions become usable only through contextual interpretation, and the difficulties met in acting on them are how you find out what needed clarifying. Better instruction-following does not remove that work. Neither does better instruction-writing.

The meta-rational discipline has three parts. First, when someone says the software works but they cannot use it, do not classify the remark. It is not yet a bug and not yet a feature request; it is evidence that something in the frame does not fit, and the first job is to find out what kind of thing: a plain defect, a category that conflates two meanings, a purpose that was never the real one, or a method of investigation that keeps producing the wrong kind of answer. Second, revise at the level the evidence points to. A revised purpose can justify less automation rather than more; a revised category changes the glossary and perhaps the schema, not the feature list. Translating every objection into another feature keeps the frame intact and lets the misfit accumulate. Third, keep completion provisional. There is no point at which future use can be certified to reveal nothing new, so the aim is to have resolved enough to take the next bounded step and to know how to reopen the frame when the result warrants it.

Krycho draws the temptation clearly. Faced with a fuzzy world, it is always easier to force the world to fit the program than to make the program adaptable to the real ways people work. That is the high-modernist move, and software has the power to make it without consulting anyone. The alternative he offers is humility about what has been compressed away, and a preference for tools that leave room for uses their makers did not think of, in the way a spreadsheet does.

Failure path

How the situation goes wrong when handled purely rationallyHow to readExpand

The spec is agreed and from then on treated as the truth about what is needed. The build satisfies it and the review confirms two things, that the code meets the standards and that it matches the spec, which is all the review was asked. The software ships. When the people who use it say it works but they cannot use it, the remark is filed as a bug or a feature request, because those are the only categories the process has. A feature is added. The frame is unchanged, so the next encounter produces the next objection, and the product grows features without ever fitting.

Corrected path

The same path with skills inserted at the break pointsHow to readExpand

The build and the two-axis review stay exactly as they were. What is added is a third review question and a rehearsal: a practitioner performs a representative episode of the real task with the artifact, rather than approving its appearance. What they say and do is then sorted before it is acted on. A plain defect goes straight back to the build. Anything else is a reason to revise the frame at the right level, which may be a term, a recorded decision, or the destination itself, and the revision is carried forward into the glossary, the decision record, and the spec, so that the next slice starts from the corrected frame rather than from the original request plus a patch.

Skills for this situation

Skill	When to invoke it here	What it changes	Example
code-review	After every meaningful increment, with one question the skill does not ask.	The skill checks standards and spec conformance in parallel. Add a third axis, context fit: what did encountering this implementation reveal about the request’s assumptions, categories, purposes, or setting? The third axis is the only one permitted to conclude that the spec was wrong.	/code-review against main, then answer: what did building this reveal that the spec did not know?
prototype	Before shipping, to stage the encounter deliberately rather than waiting for it.	Produces a runnable artifact a non-developer can drive. Ask a practitioner to complete a real episode with it, including the interruptions and workarounds, and treat their hesitation as data.	/prototype the review flow as a walkthrough the operations lead can click through
grilling (via /grill-me)	When the encounter produces a misfit and before anyone files it.	The interview sorts what kind of misfit it is: defect, category, purpose, or method. Its stopping condition is not that nothing remains assumed but that enough is resolved to take the next bounded step.	/grill-me the objection that the report is correct but unusable
domain-modeling	When the misfit turns out to be a word carrying two meanings, or a relationship the model lacks.	Records the distinction in CONTEXT.md and the decision in an ADR, so the correction lives in the project’s vocabulary rather than in one person’s memory.	/domain-modeling: “complete” versus “accepted for handoff”
wayfinder	When the misfit is about purpose, and the destination itself needs to change.	The map’s destination governs scope; revising it is how a discovered purpose becomes the new frame instead of a feature bolted onto the old one.	/wayfinder: revise the destination in light of what use revealed
to-spec	After the frame is revised.	Rewrites the spec from the corrected frame. The old spec is kept as a snapshot, which Pocock’s conventions already treat it as.	/to-spec
handoff	At the end of the session in which the misfit was resolved.	Carries the learning to the next session by pointing at the ADR, the glossary entry, and the revised issue, rather than by repeating the story, so the correction is not lost in a fresh context.	/handoff for the next session: implement the revised review flow

Sources

• Chris Krycho, Seeing Like a Programmer: Resiliency, Limits, and Moral Hazards in Software Engineering.
• Justin Etheredge, 20 Things I’ve Learned in my 20 Years as a Software Engineer, items 2 and 9.
• David Chapman, When engineering gets 100% meta-rational.
• The context-fit review and the sorting of misfits are adapted from a mapping of Chapman’s table onto Pocock’s skills prepared for this project.