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

You cannot know yet: spikes and prototypes

Aspects: relationship with reality · effective action (meta-systematic) · contingencies · epistemology (relating formal and informal)

Signals you are in this situation

Section titled “Signals you are in this situation”
  • Estimates for one piece of work differ by an order of magnitude.
  • Approaches are being compared from documentation rather than from trials.
  • A key dependency has never been exercised by anyone on the team.
  • The design discussion keeps returning to the same unresolved question.
  • People say they will find out when they build it, then plan as if they knew.

The situation

Section titled “The situation”

Before GitHub built what became GitHub Apps, Keavy McMinn was researching how the platform might integrate better with third-party data. She knew she would need buy-in from company leadership, so she wrote a strategy document and backed it with a handful of spikes: small pull requests, never merged, each stringing a few parts together to show how one piece of the idea could work. The spikes did what the document alone could not. They turned a debate about plausibility into something people could read and run, and the project went ahead.

The same post describes the opposite use. A manager suggested a direction that felt wrong to her, and rather than argue it on theory she built a spike, understood exactly why it would not suit, and could say so with evidence. Shape Up tells a matching story from the other side of the ledger: Basecamp once bet six weeks on a home-screen redesign without checking during shaping that a viable design existed. It did not, the team could not find one under deadline, and the project was abandoned.

The meta-rational perspective

Section titled “The meta-rational perspective”

Rational planning assumes the approach is known and only the effort is uncertain. Early in any non-trivial piece of work, the approach is what is uncertain, and no amount of estimation will convert that into a number. Shape Up describes the difference as the shape of the risk: well-understood work has a thin tail, where the worst case is an extra week, while work with an unresolved technical unknown or an unsolved design problem has a long tail that can stretch to several times the appetite. The rational move is to estimate harder. The meta-rational move is to change what kind of activity you are doing until the tail is thin.

That change is from arguing to touching. McMinn’s point about exploring three approaches rather than two is a point about how understanding is produced: with two options, the discussion turns into a contender and a decoy; with three spikes in hand, the trade-offs become palpable in a way no opinion can be. The knowledge you need is not yet in anyone’s head, so it cannot be elicited by interviewing. It has to be made, cheaply and disposably, by putting a formal object into contact with the real system and watching where it strains. That is why spikes must not go to production: their value is entirely in what they taught, and keeping them would convert a question-answering instrument into a commitment.

Two distinctions matter. A spike is for engineers: it may have no interface and no meaningful output, and it exists to compare ways of building a piece of the guts. A prototype is for the people who will use or judge the result: complete enough that a non-engineer can drive it and react. Confusing the two produces prototypes that engineers find shallow and spikes that stakeholders mistake for progress. And there is a third activity that Shape Up separates out: patching the rabbit holes you can see up front. Some questions are not worth a spike; they need a decision made in advance so the team is not asked to untangle a knot under deadline. Knowing which questions call for which treatment is the judgment this situation trains.

The discomfort is part of it. McMinn is explicit that starting with spikes feels amorphous and exposed, and that the answer is to get comfortable with not knowing a lot rather than to skip to a plan that only looks known.

Failure path

Section titled “Failure path”
1 Raw idea arrives “integrate with third-party data” 2 Debate approaches on theory alone: contender vs decoy 3 Pick a direction the loudest opinion wins 4 Spike it skipped 5 Estimate and commit rabbit holes still unseen 6 Build unknown surfaces in week three 7 Project stalls “no viable approach”, budget gone abandon, argue again later
How the situation goes wrong when handled purely rationallyHow to read

The approaches are debated on theory, so the argument is won by whoever is most confident. Nobody builds anything disposable, so the rabbit holes stay invisible until the team is inside them. The estimate is made on the assumption that the approach is known, and the project is committed on that estimate. When the unknown surfaces in week three, there is no budget left to try another way, and the work is abandoned or dragged out, to be argued about again later on the same theoretical footing.

Corrected path

Section titled “Corrected path”
1 Raw idea arrives “integrate with third-party data” 2 Talk to people 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 Map the unknowns wayfinder: Charts work too big for one session as a map of decision tickets with a named destination.wayfinder research: Sends a background agent to primary sources and writes cited findings to a file.research 4 Spike each approach three, not two; throw them away prototype: Builds throwaway code that answers one design question.prototype 5 Patch rabbit holes settle the hard calls in advance grilling: Interviews you round by round until nothing about a plan is left silently assumed.grilling 6 Specify the bet to-spec: Synthesises the conversation into a spec and publishes it to the tracker.to-spec 7 Build one slice core, small, novel tdd · implement: The red-green-refactor loop with rules for tests worth keeping.tdd · implement iceberg in the slice: spike it, do not estimate it an approach fails: that is the answer
The same path with skills inserted at the break pointsHow to read

Talking to people comes first, because it tells you which unknowns matter. The unknowns are then written down as questions rather than absorbed into a plan. Each candidate approach gets a spike, and a spike that fails is a result, not a setback: it goes straight back into the map as a settled question. Only once the remaining holes are patched or declared out of bounds does a spec get written, and the first thing built is a single vertical slice chosen because it is core, small, and novel, so that the next iceberg is found in days rather than weeks.

Skills for this situation

Section titled “Skills for this situation”
Skill When to invoke it here What it changes Example
grilling (via /grill-me) Before any spike, to separate what is unknown from what merely feels unknown. The interview forces the team to name each open question and say what would settle it. Questions with a factual answer go to research; questions only an artifact can settle go to a spike; questions that need a decision get decided now. /grill-me the plan to integrate third-party data
to-questionnaire When the unknown belongs to someone outside the team, such as the owner of the system you would integrate with. Turns the gap into a document for that person to fill in, so a spike is not built on a guess about their constraints. /to-questionnaire for the platform team: what does the events API guarantee about ordering?
wayfinder When the work is too large for one session and the unknowns interlock. Charts the unknowns as a map of tickets, some marked research and some prototype, with the fog explicitly left unspecified. Spikes become tickets with a question and a verdict, not side projects. /wayfinder: destination is a decision on the integration approach
research For unknowns that primary sources can settle. Sends a background agent to read the documentation or source and write up what it found, so a spike is only built where reading cannot answer. /research how the vendor API handles rate limits and retries
prototype For each approach the argument cannot settle, and later for anything a non-engineer needs to react to. Produces throwaway code marked as such, runnable from one command, with no persistence or polish. The skill captures the verdict on the issue and commits the code to a throwaway branch, which is the discipline of throwing it away. Choose the logic branch for a spike and the UI branch for a prototype. /prototype the state model for a webhook-driven sync, so we can compare it with polling
to-spec Only after the spikes have been compared and the rabbit holes patched or fenced off. Synthesises what the spikes taught into a spec that records the chosen approach, the patches, and the no-gos, so the team is not handed the knot. /to-spec
tdd and implement For the first slice, chosen to be core, small, and novel. The build is ordinary once the approach is known. The meta-rational choice is which slice to build first, so that the next unknown is met early. /implement the sync slice from issue #21, end to end, before anything else

Sources

Section titled “Sources”