14KB
Spec Driven Development — Chapter-25: 11 - The Whole App Was Born From Five Loops
- Source: /library/Spec Driven Development/source-file.pdf
- PDF pages: 480–488
- Pages without text: none
11 - The Whole App Was Born From Five Loops Stop and Look Back The app is ready. You can open the To-Do now, create a task, complete it, filter the list, delete what no longer serves and edit what you changed your mind about. Five capabilities where, at the start of this journey, there were none. It is tempting to move on, close the editor and consider the matter closed. Don't close it yet. Before moving on, it is worth stopping in front of the finished app and looking back, not to touch anything else, but to see how you got here. This chapter opens no sixth feature and runs no more cycles. It does the opposite of what the earlier ones did: instead of building, it consolidates. It is a retrospective. What we are going to look at is not the To-Do's screens. Screens are forgotten, and nobody needs one more task app in the world. What we are going to look at is the path each feature walked, because it was always the same path, and it is the one you carry with you to the next project. From up here, with the whole app in view, that path becomes visible in a way no single chapter could show. The Whole App Is Five Merges Into main
Look at the project through the git history, and its shape appears without evasion. main , the main and stable line, did not grow all at once. It received five integrations, one at a time, and between one and the next it stood still, whole, ready to use. Each integration was a merge, and each merge brought in a whole feature that had been built far away, on a separate branch. There were five branches, and none of them existed by chance. Each branched off main , sheltered the development of a feature from start to finish and came back through the merge when the feature was ready and whole. Creating and listing tasks branched off, walked the path, came back. Completing and reopening, the same. Filtering, deleting, editing: each in its turn, each on its branch, each with its merge. And inside each branch, always, the same cycle. The feature was not improvised in a hurry or written all at once. It was born from a specification, was planned, split into tasks and built under tests, exactly as Chapter 5 promised. Five branches, five loops, five merges. Add the three and you don't have five loose features: you have a whole app, which is the accumulated result of five disciplined repetitions of the same process. The app was not born all at once or from a burst of inspiration. It was born from one lap, repeated five times. The Timeline in One Figure Seen from above, this story fits in a single figure. It is the same language as the diagram in Chapter 5, main branching off and receiving the merge back, now applied to the To-Do's real history, with the true branch names and the five merges in the order they happened.
Read the figure once and it becomes a reference: it is the project's real history in the same language as the map you already know. Each Feature Lit a Spotlight The five laps were identical in form and different in focus. Each chapter kept the whole cycle running, but lit a spotlight on one step, so you could see it up close without the others stealing the scene. Set side by side, the five passages are the cycle seen from every angle. Creating and listing tasks lit the spotlight on specify . Here you learned that what comes out of the first step is a draft, not the finished spec: the tool organizes your sentence into scenarios, requirements and criteria, gets the skeleton right and guesses at the flesh. The content stays yours to review, fix and complete, and it was that review, not the generated text, that shaped the
feature. Specifying well was less about writing a lot and more about deciding what the feature is, and what it explicitly is not, before a single line of code exists. Completing and reopening a task lit the spotlight on clarify . The lesson was simple and sharp: a question you don't answer does not disappear, it just changes place. Leave an ambiguity open in the spec and the one who will decide for you is the agent, at implementation time, picking some path, plausible, maybe wrong, and moving on without warning. clarify exists to bring that decision back to you, and early, while it costs an answer, instead of discovering it down the line as an assumption already buried in the code. Filtering tasks by state lit the spotlight on plan and checklist . It was where you saw intent become design before becoming code: which layers, which flow, which success criteria decide whether the thing is ready. And you saw the quality gate, checklist , check whether the spec and the plan were complete and clear enough to move forward, instead of discovering a hole only down the line, when fixing it already costs dearly. Planning and validating was the step that turned a good intention into a route the agent could walk without guessing. Deleting a task lit the spotlight on tasks and analyze . tasks broke the plan into small, ordered, verifiable steps, each a unit the agent executes and confirms done before moving to the next. analyze crossed spec, plan and tasks looking for conflict, gap and excess, and taught fixing at the source: the defect is fixed in the artifact where the truth is born, the spec or the plan, so the fix comes down the whole chain, not in an isolated patch at the end, in the task or the code. Editing a task lit the spotlight on implement . It was the step that turns tasks into code that passes the tests, on the beat of the red- green cycle, reading the versioned artifacts instead of the chat
history. And it was where a real defect appeared at build time, and the right reflex was not to open the code and patch the condition in a hurry, but to go back to the spec, fix at the source and let the fix come down guided by a test that first failed. Code as the consequence of a process, the exact opposite of trying again until it works. That episode is told in full in Chapter 10.5, in the order it happened and with the text of each artifact before and after: it is the only one of the five laps the book records from requirement to second iteration, and it is worth rereading if the mechanics of fixing at the source still feel abstract. Together, They Covered the Whole Cycle The spotlight, though, was never the whole cycle: on every branch, without exception, the feature walked the complete lap, and only then the merge. What changed from chapter to chapter was where the light fell, not the path walked. That is why the sum of the five passages recomposes the whole cycle in your head, and in the best possible way: through repetition. You did not see the cycle once. You saw it five times, from five angles, on five different problems. It is repetition, and not the isolated command, that gets internalized and becomes reflex. One Constitution Governed the Five Loops There is one piece that appeared in the diagram above everything and belongs to none of the five laps: the constitution. You wrote it a single time, back in Chapter 4, before the first feature existed. And you never rewrote it. The five features were born, walked the cycle and were integrated under the same rules of architecture, layers, error handling, quality principles. Five loops, one constitution.
That places it in a different spot from the rest. The constitution is not the first step of the cycle, which would repeat with each feature. It is above the cycle, governing every lap without being part of any. While specify , plan and implement each ran five times, it stood still at the top, stable, consulted every time plan needed to check whether the feature respected the fixed principles. Governance is the frame within which the repetition happens, and a frame does not run in a loop. Going deeper: governance is not a step of the loop. It is easy to confuse the constitution with a first step of the cycle, since it comes before everything. The difference is in the frequency. A loop step runs once per feature: five features, five specify s. The constitution ran zero times per feature, because it was written once for all of them. It is the level of the general, lasting rules, above the day-to-day decisions. Touching it is an amendment, a rare and versioned event, not a step of the flow. The Cycle Is Yours Now Set the To-Do aside for a moment and look only at what is left in your hand. It is not a task app. It is a cycle: branch off main , write the spec of what you want, let clarify resolve the ambiguities, plan, validate with checklist , split into tasks, check consistency with analyze , implement under tests and integrate back into main through the merge. That path has nothing specific about personal tasks. It serves any software. That is what makes the cycle transferable. Tomorrow, in a project of yours that has nothing to do with lists, you branch off, write the first spec and run the same lap. The start is always the
same: a branch and a specify . You already know where to begin because you have done it five times. And in steering the agent, two reflexes you saw along the way make the biggest difference. The first: ask it to ask questions. When something in the spec admits more than one reading, force the ambiguity to surface in clarify , instead of letting it become a silent assumption in the code. The second: demand grounding. Do not accept a plan decision or a fix without understanding why it is this way and not another. The agent speeds up the work, but the one who governs the process is you. The cycle is what keeps that governance possible. Governing the agent is also deciding what it sees and when, and that is the subject of Context Engineering (2026, https://books.kodel.com.br/en/books/context-engineering/), the third volume in this trilogy: what the agent sees right now, in the window of this one call, and at what cost. The two reflexes above are already enough to run the cycle with discipline; the third volume only turns into method what is a habit here. Going deeper: how to demand grounding in practice. Demanding grounding is asking each decision to point to its origin, without gratuitous suspicion. Faced with an architecture choice, ask which constitution principle supports it. Faced with a fix, ask in which artifact the defect was born and why the fix goes there, and not in the code. When the answer is “because the spec says” or “because principle X requires it,” the process is healthy. When the answer is “because it worked,” you are back to improvisation. What If I Did This Without SDD?
It is worth facing head-on the objection that may be in your head now. If I simply asked an agent “build a task app with create, complete, filter, delete and edit,” wouldn't it spit out something similar in a fraction of the time? No branches, no specs, no seven steps? For a To-Do, probably yes. A task app is the kind of thing agents do with their hands tied behind their back, because it is ubiquitous in the data they were trained on. Asking for the whole app at once, off the cuff, would come close to the result, and there is no point pretending otherwise. But that is exactly where the trap of the example lies. The To-Do is trivial on purpose, so that the mechanics of the process would never stay hidden behind the difficulty of the problem. It was never the proof of SDD's value. The proof shows up when the project stops being trivial. In real life, software is not a task list: it grows, gains rules that contradict each other, lasts months, passes from hand to hand. That is where improvisation starts to charge. Vibe-coding loses track of why each decision was made, loses the governance that keeps the parts coherent and loses consistency as the context overflows. The cycle you learned was not invented for the To-Do. It was invented for the day the To-Do becomes a real system, and improvisation no longer copes. The To-Do Was the Vehicle; the Process Was the Protagonist Go back now to the uncomfortable question everything started with, back in Chapter 0: if artificial intelligence already builds on its own, why waste time specifying? The finished app is the answer, and it is in the git history, not in the rhetoric: five times
you described what you wanted before asking for the code, and each line came out of a clear spec, a decided plan, ordered tasks and tests guiding. That is why the app mattered so little and the path mattered so much. The To-Do was the vehicle, and you can discard it without losing anything. What you don't discard is the cycle, because it is the same for any software you build afterward. The protagonist was never the task app. It was Spec-Driven Development, and the To-Do only served so that you could watch it work, end to end, five times. Each of those five slices landed in an architecture that never changed shape, and that is what FOCUS Architecture (2026, https://books.kodel.com.br/en/books/focus/), the second volume, digs into: where each rule lives and why dependencies point inward. This book closes on its own what it set out to show; the second volume answers a different question, it does not complete this one. The material ends here. Not because there is nothing more to say on the subject, but because what it set out to show is already shown: the whole cycle, in action, from nothing to an integrated app. We did not open a final chapter comparing tools or weighing alternatives; that decision was deliberate, and the place to compare tools has already passed. What remains is simpler and more yours: a process you saw work and that you can now run on your own. The next branch is yours.