From decision records to user stories

A case study: what happens to a project whose specification is prose, and what changed when it was not.

The project is a private infrastructure build — a network, the hardware it runs on, and an appliance that configures it. By any ordinary standard it was well run. It had written everything down.

It was four days old and carried 86,524 words of prose.

That is the number to hold on to. Not a legacy system, not a decade of accumulated documentation — a project that began on a Thursday and by the following Monday had fifty markdown files, twenty-five decision records that contradicted each other, and no way to tell which parts were true.

Details are omitted because the repository is private. Every number below is from its history.

Where it started

The project kept its thinking in the shape most well-run projects use:

Nothing here is bad practice. This is what a careful team produces, and it produced it in four days — the decision records were written across three of them. The facts of the project lived in nine places, every one of them somebody's copy of a fact whose original was elsewhere.

Prose grows faster than anyone expects, and nothing in a normal process notices. There was no point at which somebody decided to write 86,524 words. Each document was reasonable when it was written.

The four things that went wrong

1. A status was true because somebody typed it

Each decision record carried Status: accepted. It said accepted because a person had written accepted, and nothing anywhere disagreed — including:

• six that had been superseded by later decisions,
• one whose central assumption a physical survey had disproved,
• two describing a design the owner had explicitly rejected.

Nine of twenty-five were wrong, and every one of them read exactly like the sixteen that were right. There was no way to tell them apart without reading all twenty-five and reconstructing the chronology, which is the work the records existed to save.

This is the failure that motivates everything else here. A document cannot fail. It has no mechanism by which it can stop being believed. Whatever is written in it stays true-looking until a human happens to reread it and happens to notice.

2. Copies do not rot together

The clearest single instance: a claim about survivorship was stated in the project's top-level guidance file. That claim belonged to a spec that was deleted. The prose copy went on being read for three days after its original stopped existing, with nothing able to say it was orphaned.

The habit outlived every attempt to fix it. Two commits after one such document was removed, a test was written that parsed a different markdown table as data — a fact restated inside prose, read by a regex. The project's own note on this is worth quoting: the pull toward writing a fact into whatever document is open survived deleting the document.

3. The prose outgrew every role

By the end, no role could work from the artifacts. There was too much to read, and the reading did not converge: any two documents might agree, might contradict, and nothing said which was current. An analyst could not tell what was decided. A developer could not tell what was built. The owner could not tell what remained.

The backlog was the sharpest case, because it looked the most useful. One of its lines said buy a $15 meter. It was stale — the meter was already in a drawer. The line was not wrong when written and nothing ever made it wrong; it simply stopped corresponding to the world, silently, in a file 1,379 lines long where nobody was going to notice.

4. Decisions circled

Because no artifact could say a question was settled, the same questions came back. One session produced three separate decision records off a single question. Elsewhere a retired architecture survived inside a chapter that had quietly kept it, and surfaced later as a vocabulary collision — two names in use for one device. The first instinct was to fix the vocabulary, inventing two words so both readings could be correct.

That instinct is worth naming, because it is the expensive one: a vocabulary fix that makes a stale claim coherent is worse than leaving the contradiction visible, because it launders the error.

The conversion

It took one working day. The order mattered: the chapters were written first, and the documents were retired only as their content found a home.

1. Write the chapters — one process each, named from a person's side. Seven of them: a person gets on the internet, the equipment is replaceable by somebody who did not design it, the network can be handed to somebody who did not build it. Each is a flow with a start, an end and steps between; each step is a story in its own right.
2. Move each decision in as a subject. What a record decided became a claim in the chapter that owns it, with its status derived from a run instead of typed into a field.
3. Rewrite the citations before deleting anything. 222 markdown links into the decision files, across 44 files, were rewritten to plain ids first — a link breaks and an id does not. Zero dangling paths afterwards.
4. Sort the backlog into three kinds, and keep two. Facts that cost real time to learn went to the node they constrain — as its closing argument, or as the Domain of the element they are about. Questions became open unknowns anchored to the subject they affect. Work was dropped — an unproven subject is the work item.
5. Retire the requirement ids. The requirements document had shrunk to a mapping table, and a mapping table is a list. Every live citation was rewritten to name the subject carrying the claim. The old numbers deliberately resolve nowhere: an id that resolves only through a lookup table is a second name for something that already has one.

Net effect on the prose: 86,524 words down to 25,271, and 50 markdown files down to 20. Nine retirement commits alone deleted 8,927 lines and added 918. Seventy-one per cent of the writing was removed, and nothing was lost that anybody has since gone looking for.

The output was 42 subjects, zero gate faults, and a board reading 30 proven and 1 unproven — for the first time, a single artifact that said what was built and what was not.

What it found immediately

Writing the chapters found defects that nothing else was going to catch, because a claim that has to be checkable is a claim somebody has to check. Seven, in the final pass alone. A sample, generalised:

• A resolver was answering for five hostnames nobody used while the five real ones left over the WAN and came back — the identical failure the file's own comment recorded having fixed once, now recurred in the opposite direction, underneath a comment still reading verified.
• The recovery image kept for the appliances was the wrong variant for the hardware. The project had diagnosed that exact incompatibility months earlier, written it down, and kept the wrong image anyway.
• A switch carrying every network segment answered to a default SNMP community at read-write level.
• Two planned routes did not exist. Nothing had said so, because the document describing them described the plan.

Three subjects were deliberately left reading inert — cited by tests that read the repository's own copy of what the hardware should be, rather than the hardware. Declaring them structural would have claimed inspection settles them. It settles only that the record agrees with itself.

That restraint is the point. The method's value is not that it turns everything green. It is that the things which are not proven say so, in the same place and the same vocabulary as the things which are.

The split that only became visible afterwards

Once the project had chapters, one thing was obvious that had never been visible in prose: two different products were in one repository.

There was a general-purpose appliance — configuration that moves a router to different hardware, useful to anybody — and there was one particular household's network: its zones, its cabling, its rack survey, its electricity costs. In prose these had interleaved for two years, because a document about the network naturally mentions both.

The chapters could not interleave them, because a chapter is one process and the box died and the network has to come back as itself is not the same story as this house's fiber reaches the outbuildings. Once each had its own chapters, the boundary was a line you could point at, and the product left in its own repository.

Note what the split is between. It is not code versus documentation. It is the tooling — which is general, shippable, and belongs to whoever installs it — versus the process that defines the business flow, which is one owner's and could never be handed to anybody. Prose does not make that boundary visible, because both halves are equally describable in English. A flow does: the actors are different people.

The spec moved with the product, and that was not a preference. Citations resolve by reading a source tree against a spec directory; split the code from the spec and the citations resolve nowhere and the board is permanently empty.

The same shape at twenty times the size

Four days and 86,524 words is a small project moving fast. The trajectory does not improve with scale, and the largest project run by the same owner shows what it looks like given room:

Roughly nine to one. The governance repository holds 45 decision documents, 16 epics, 14 principles, 14 architecture documents, plus goals, workflows, risks, a roadmap, a quality bar and a review checklist. It is not junk and it is not stale — it is kept for reference, and it is a perfectly respectable body of enterprise project governance.

It is also, by its own existence, the finding: the apparatus for deciding things had grown until it needed a repository, and the project had stopped moving. What got it moving again was a gold-spec one ninth its size. The governance was not deleted and did not need to be; it stopped being the thing anybody worked from.

That is the argument for doing this early. At four days the conversion was one working day. At 191,048 words it was not attempted, and the spec was written alongside instead.

The control

The same owner runs a second project that started with this method on day one, and it has never had any of the above. That is worth stating plainly because it bounds the claim:

Nothing here argues that a conversion is a good use of a week. It argues that the state the conversion escaped is reachable by ordinary good practice in four days, and that it does not announce itself. The project did not feel like it was in trouble. It felt like a project with excellent documentation, right up until somebody asked which parts of it were true.

The cheap version of this case study is: start with the chapters.

What to take from it

1. This happens in days, not years. 86,524 words and twenty-five conflicting decision records took one long weekend of careful work. If you are waiting until the documentation problem is big enough to be worth solving, it already is.
2. Anything with a hand-typed status will be wrong, and will not look wrong. The proportion here was nine in twenty-five.
3. Every restatement is a copy, including a helpful one. A claim repeated in a README is a second home. It will not rot at the same rate as the original, and nothing will tell you.
4. A backlog is a list, and lists go stale from the moment they are written. Sort its contents into facts, questions and work — and keep only the first two, anchored to subjects.
5. Rewrite citations to ids before deleting a document. A link breaks; an id does not.
6. Drawing the flow is what finds the defects. Not writing the prose about the flow. The prose is what let three of them sit undisturbed.
7. Expect the first pass to go red, and let it. Four gaps stayed red because the world had not changed yet, which is the mechanism working rather than a result to be tidied away.

Next: Getting started walks through one complete chapter, part by part.