8.5KB
Spec Driven Development — Chapter-24: 10b - Iterative Refinement: The Spec After It Already Exists
- Source: /library/Spec Driven Development/source-file.pdf
- PDF pages: 474–479
- Pages without text: none
10b - Iterative Refinement: The Spec After It Already Exists No Document Is Born Finished The cycle you followed five times treats the spec as a starting point. It gets written, reviewed, approved, and then plan, tasks, code. Read that way, from the outside, the specification looks like a document you write once. None of the five worked like that. All of them changed after they were finished, and the last one changed after the code was already written and passing its tests. That is not a failure of the method: it is the method working. A spec that never changes is either luck, or a spec nobody is using. What this chapter does is look at the movement itself. When a spec changes, what exactly changes in it, who found out it needed to change, and what else has to move along with it. The fifth feature's lap, file by file, is in Chapter 10.5; what matters here is the shape of the movement, which will serve your specs, and yours will have nothing to do with a to-do app. Four Doors the Change Comes Through A spec can be corrected at four moments in the cycle, and each one uncovers a different kind of defect. Know all four by the question each one is able to ask, because that also tells you what
none of them catches. clarify catches the ambiguity you can see yourself on a reread. It works by closed question, one at a time, and what it uncovers are decisions the spec left open without noticing: does the filter survive closing the app? is completing what is already completed an error? The change it produces always has the same shape: a clarification recorded with its date and a requirement either added or rewritten. It is the cheapest of the four doors, because there is no plan and no code yet to undo. checklist catches the structural gap. It knows nothing about your domain, and that is what makes it useful: it checks whether the spec has the parts a spec has to have. It was checklist that noticed the filter spec fixed three views and never said which one appears when the screen opens. A human reading that document would agree with it three times without spotting the hole, because the list of options looked complete. analyze catches the contradiction between artifacts. It cross- checks spec, plan and tasks, and cross-checks the current spec against the earlier ones. It is the only one of the four doors that sees outside the document, and that is why it is the only one that can find the same verb meaning two things in different features. Manual validation catches what was consistent and wrong. This is the door that matters most, because it is the one left over. The three before it check form, completeness and coherence, and a spec can pass all three while being ambiguous, as long as it is uniformly ambiguous. That is what happened on the fifth lap: checklist with no gap, analyze with no conflict, green tests, and the defect waiting for the first time somebody edited only a task's description.
Hold on to that, because it is the practical conclusion of this chapter: no automatic step can tell that a clear sentence means something else in the head of whoever reads it. Only use tells. The Chain, in the Order Things Move Chapter 6b already named the defect of fixing at the end of the chain and said why it ruins the method. From there comes the question that separates the two cases, asked before you open the code file: which artifact was this defect born in? A typo was born in the code; a behavior nobody had agreed on was born in the sentence that failed to agree on it. Suppose the answer is that it was born up top. What this chapter adds is the mechanics: fixing at the source has an order, and it is the cycle's own order. Each link moves only after the one before it is right. The spec first. Rewrite the requirement and record the new clarification, with the reason. The record matters as much as the correction: without it, three months from now somebody will look at that odd sentence, with an explicit exception that reads like paranoia, and “clean up” the text back into the ambiguous version. Then the plan. Often nothing changes, and checking that nothing changes is part of the work. If the correction is a matter of wording, the plan stays valid and you note that. If it touches a technical decision, the plan changes before the tasks do. Then the tasks. A new or widened requirement usually becomes a new case in a test task that already exists, not a new task. The sign that it became a new task is that the correction opened up behavior that was not foreseen anywhere.
Then the test, red. This is the link you cannot skip. The test that reproduces the defect has to be written and has to fail before the fix exists, because that is what proves it is testing what you think it is testing. The code last. It tends to be the smallest part. On the To-Do's fifth lap it was one more condition in a comparison. Notice that this sequence is the same thing as the whole cycle, at a smaller scale. You are not stepping outside the method to fix an exception; you are taking a short lap inside it. What Changes and What Does Not Not every spec correction is the same, and it pays to tell three sizes apart, because the cost differs a lot. Precision: the rule was right and the sentence was loose. It is the most common case and the cheapest. One line of the spec changes, one test case changes, little code changes. The To-Do's fifth lap was this size. Decision: the spec said one thing and you concluded it was the wrong thing. Here the requirement really changes, and the plan and the tasks quite likely change with it. It is still the same feature. Boundary: what turned up does not belong to this spec. Somebody asked for the filter to remember the last view chosen; that is a new capability, with state of its own and a life cycle of its own. The right correction is to record the refusal in the clarification, with the reason, and leave it for a future spec. A spec that absorbs someone else's boundary out of convenience stops fitting in one lap, and Chapter 6b already showed what that costs.
Confusing the three is what produces the feeling that “specifying is pointless, everything always changes”. Almost nothing ever changes. One sentence changes, and the sense of chaos comes from treating all three with the same ceremony. When the Spec Stops Being Trustworthy There is a limit, and it deserves saying. If the same spec has come back for repair four or five times, the problem is not the wording of each sentence: it is that the document is trying to describe something that has not been understood yet. The sign is the nature of the corrections, not their number. Several precision corrections are a document being sharpened. Decision corrections in a row, each reversing the one before, are a document being discovered, and discovery is exploration work, not specification work. The honest way out is to stop, poke at the code without ceremony until you understand what the question is, throw away what you made, and write the spec with the answer in hand. That is not abandoning the method. It is the same good sense from Chapter 2c, applied later: SDD pays off when you know what you want and you need someone else, human or machine, to do exactly that. It does not pay off while you are still finding out what you want. The Document That Outlives the Project A spec maintained across five laps becomes something that was in nobody's plan: the record of why the system is the way it is.
Look at the five clarifications of the To-Do's last feature. They do not explain what the code does, which the code already explains on its own. They explain why it does it that way: why editing does not reorder the list, why editing something that vanished returns an error instead of blowing up, why keeping your own title does not count as a duplicate. Each of those answers cost a question, and none of them is in the code. That is why keeping the spec updated is worth it even when nobody is going to read it again that week. The document is not there to guide an implementation that already happened. It is there for the next person, who may be you in six months, with no memory at all of the conversation that produced that line. Five laps have closed. What they taught together, which none of them taught alone, is the subject of the next chapter.