Add author experience to core chapters

Author: flemming-n-larsen

content/mindset.md

@@ -32,9 +32,15 @@ With coding agents, the safer habit is to think in terms of intent: which decisi
 
 Most AI coding advice loses me here. It talks about prompts, models, autocomplete, demos, and product comparisons instead of asking what the team needs to document before an agent touches code. Then it skips the professional part: separation of concerns, domain modeling, module boundaries, trade-offs, security restrictions, existing structures, tests, and review.
 
-When working on security, the agent starts from the current security practice and the governance rules the company and team selected. There is no room for improvisation here.
+When working on security, the agent starts from the current security practice and the governance rule the company and team selected. There is no room for improvisation here.
 
-The decisions, checks, and constraints belong to the product whether the code was typed or generated. That is why treating the agent as a source of original insight goes wrong so quickly. Code still matters, but with coding agents it starts to look more like output than authorship. I read the shift as a compiler move: a compiler translates sources into machine code, and a coding agent translates intent into application code.
+I first felt this shift before coding agents while working from OpenAPI definitions. The generator did the tedious work faster and more consistently than I did, which left me with the implementation choices I cared about. Coding agents pushed the same feeling into tests. I like tests that demonstrate how a component or service works. I have never enjoyed writing another test only to move a SonarQube coverage number.
+
+Current coding agents changed the balance again for me. In my recent work, a well-planned task often comes back close to how I would have written it, including details I might have patched in later. A few years earlier, the output still carried the rookie mistakes I expected from a junior developer. I no longer assume that implementation is the challenging part, which is stating the intent completely enough that nothing important gets omitted.
+
+After forty years of programming and a gradual move into architecture, documentation and knowledge sharing already occupied more of my time than typing code. Coding agents finished that transition. I still inspect what they produce, but I no longer regard manual coding as the center of my work. The specification has become my programming surface.
+
+The decisions, checks, and constraints belong to the product whether the code was typed or generated. Code still matters, but with coding agents it starts to look more like output than authorship. I read the shift as a compiler move: a compiler translates sources into machine code, and a coding agent translates intent into application code. The comparison only goes so far. A compiler receives formal input. A coding agent works from prose and project context, where something will remain unstated. The developer has to find those gaps and decide whether the result is right.
 
 Software engineering has been moving in this direction for years. Developers already write one artifact and let tools emit another. Coding agents push the same move one layer up. The maintained artifact is no longer only the source code the compiler accepts. It also includes the written intent the developer cites in the review to justify the change.
 

content/preface.md

@@ -19,15 +19,17 @@ This book answers one question: how do you use coding agents in professional sof
 
 Vibe coding is fine for quick prototypes and mocks. Use it when you need a screen mock, a rough feature sketch, or a quick way to tease requirements out of somebody who cannot state them cleanly yet.
 
-The prototype is not the product. Throw it away and start again with the real requirements.
+The prototype is not the product. I have joined teams expected to take over a codebase described as 90 percent done, only to find the challenging 90 percent still missing. The happy path worked. The system did not scale, could not run in the production environment, and had no useful metrics or deployment instructions. Calling it production-ready did not make it so.
+
+My choice in such a situation is to scrap the prototype. Keep the ideas and the feedback it produced, then build from the real requirements. The architecture work usually makes the old implementation look naive anyway. Starting again gives the team something more valuable than rescued code: an understanding of the system and enough control to trust it.
 
 This should not be new advice. Fred Brooks wrote it down in 1975: plan to throw one away. You will anyway. In 1975, throwing work away hurt, since rebuilding from scratch took weeks.
 
 *Sources: Frederick P. Brooks Jr. "The Mythical Man-Month: Essays on Software Engineering" (1975), plan to throw one away.*
 
 In 2026, when most of the build is done by a coding agent, that second pass is cheaper. Rebuilding is less painful than it was when a fresh start took weeks.
 
-The second build is sharper: the dead ends are already mapped and the framework is already picked. The prototype was the conversation, not the artifact.
+A prototype still has a good job. It lets you show an idea, challenge assumptions, and compare designs for a small service or component. Sometimes the right result is a better prototype, followed by another. Once the architecture, operational constraints, authentication, and delivery path are known, the prototype has finished its job. Use what you learned when designing the production system, then start its implementation separately.
 
 A coding agent is not reading your mind. In 2026, a vague prompt still produces the wrong code in production work. State the rules, the intent, and the stack. Use the agent as a sparring partner for architecture and design, but keep the thinking on your side.
 

content/quality/tests-as-evidence.md

@@ -12,7 +12,11 @@ None of this is perfectionism. The minimum bar is automated evidence that the im
 
 ## The bar a test has to clear
 
-A test counts as evidence when it would fail if the implementation diverged from the spec. Otherwise, it is decoration. My favorite check is crude but honest: open the spec, pick a scenario, break the implementation on purpose, and run the suite. If everything stays green, the tests never exercised that scenario.
+A test counts as evidence when it would fail if the implementation diverged from the spec. Otherwise, it is decoration. My favorite check is crude but honest: open the spec, pick a scenario, break the implementation on purpose, and run the suite. If everything stays green, the tests never exercise that scenario.
+
+I also distrust a complex implementation with one positive test and no negative paths. To find out how the code fails, I have to read the implementation and work out which tests are missing. That takes time, and I might misunderstand the behavior and write the new test against the wrong assumption. Worse is a simple behavior buried under pages of mocks and test setup. At that point I do not only question the test. Code that takes more effort to fake than to execute is often asking for a redesign.
+
+I have seen tests piggyback on shared test helpers carrying their own assumptions and defects. The test appears to exercise the subject under test, but most of the behavior lives in scaffolding nobody is reviewing. This happens when passing the coverage check becomes the goal. A developer writes the quickest test that turns CI green, and a weaker coding agent generates more tests built on the same bad assumptions.
 
 Most suites contain a mix of evidence and decoration, and mutation testing is the practical detector: flip an operator, change a constant, invert a boolean, and see whether anything complains. If the suite still passes, whatever you touched was not under test. ThoughtWorks Technology Radar Vol 34 (April 2026) recommends mutation testing as a feedback control suited to agentic delivery, which matches my reading: it is the automated version of breaking the implementation on purpose.
 

content/spec-driven/why-small.md

@@ -50,17 +50,19 @@ Embed the size discipline in the agent's instructions. The human review process
 
 ## The Rule of Ten
 
-Quantity has a threshold. This book calls it the Rule of Ten: ten tasks in a spec, ten files in a PR. I picked ten because it is round, easy to count toward, and easy to recall when you are busy; eight would work, twelve would work. The point is this: a number you cannot hold in your head under deadline pressure is not useful. It is a footnote.
+This book calls the size warning the Rule of Ten: ten tasks in a spec, ten files in a PR. I picked ten because it is round and easy to recall when you are busy. The useful threshold might be eight for one team and twelve for another. Treat it as a reason to inspect the change, not a build gate.
+
+I use it in personal projects and in my team's Way of Working. The count makes me stop and look at the shape of the work. Eight complicated tasks with nested subtasks often turn into thirteen clearer tasks after I split them properly. Fifteen trivial tasks sometimes stay together because the work is still obvious. I do not split those to satisfy the number.
 
 The limit is for the reviewer on the change, not the agent. The agent re-reads a long task list at every step. The reviewer cannot re-read a long diff while also judging whether the intent was right. Past a certain point, the reviewer is sampling the diff instead of checking the whole change.
 
-Calibrate the number to your stack. Go and Java touch interfaces, mocks, and call sites that a dynamic language collapses into one edit, so the practical ceiling is higher. A terse codebase pulls it down. Move it to eight, move it to twelve, tune it to your stack. What does not move is the reason: one reviewer, one pass, the whole change visible at once.
+Task count and file count do not move together. A short `tasks.md` sometimes generates changes across many files, while ten tasks might touch only one or two. The count warns me. Gut feel makes the call: will my colleagues understand this in a review, and will I understand it when I need to fix the code later?
 
-When the task list goes beyond 10, stop. The spec is describing two changes. Find the natural seam, the point where each half ships and stands on its own, and split there.
+Calibrate the number to your stack and team. Go and Java touch interfaces, mocks, and call sites that a dynamic language collapses into one edit. Move the warning to eight or twelve if the review experience supports it. When the count rises and the change stops fitting in one reviewer's head, find the natural seam and split there.
 
 If you cannot find the seam, ask the coding agent to propose the split. It usually sees clearer boundaries than you will. Two specs, two branches, two PRs, with the second proposal referencing the first by spec ID.
 
-Splitting is not a failure: a spec that spawns a Part 2 was correctly scoped. The mechanics of turning acceptance criteria into a task list, one task per criteria cluster, live in the [Spec Lifecycle](./spec-lifecycle) chapter. The rule here is only about when the count is telling you to split.
+Splitting is not a failure. A spec that spawns a Part 2 might be better scoped than the smaller task list you started with. The mechanics of turning acceptance criteria into a task list, one task per criteria cluster, live in the [Spec Lifecycle](./spec-lifecycle) chapter. The number starts the review. It does not settle it.
 
 ## When the change is genuinely large
 

content/team/what-is-still-evolving.md

@@ -26,6 +26,14 @@ Multi-LLM critique (using a second model to review a spec before implementation)
 
 ## What is genuinely open
 
+Documentation freshness worries me more than agent handoff. Files under `docs/` age quickly after a run of change proposals. One or two people end up nursing the documentation and checking whether archived changes altered a decision, design, architecture boundary, or constraint. Agent instructions do not detect the missing update. A skill helps only when somebody remembers to run it. I still resort to asking an agent to compare the documentation against the source tree, which is useful but not a durable control.
+
+OpenSpec and current Spec-Driven Development (SDD) workflows focus on the change and its code. In the workflows I reviewed for this book through mid-2026, I found no convincing feedback path from a completed change into the durable documentation set. [Keeping Documentation Up to Date](../quality/keeping-docs-up-to-date) offers structural tripwires, but those checks detect suspect files rather than understand whether the design is still true. This part needs more work.
+
+Infrastructure is another weak spot in my experience. Continuous Integration and Continuous Delivery (CI/CD), environments, and metrics belong in the intent, but I have worked on product teams that did not own those systems. A separate pull request and another group stood between the feature team and a change to development, staging, or production. The repo-local loop in this book does not account for that coordination cost yet.
+
+There is also a capability floor. Among the coding agents I have used in 2026, weaker and cheaper models miss decisions and ignore instructions often enough to make this workflow frustrating. The book should not imply that any model with file access will behave the same way. Better models will move this floor, so I expect this assessment to need revision.
+
 Multi-repo planning remains a gap in the SDD sources reviewed for this book. When one feature needs coordinated changes across three repositories, somebody still has to sequence the work, line up the PRs, and decide which repo carries the contract change first. OpenSpec's Workspaces roadmap names multi-repo planning as an in-development team problem. That is a straight admission of a gap, not a workflow.
 
 Agent-to-agent handoff, where one agent completes a spec and hands the change folder to a different agent for implementation (across session boundaries), is experimentally described by Yegge's Agent Fleets framing but not yet practiced in any consistent form. The tooling does not yet support reliable agent memory across session boundaries in a way that makes handoff predictable.
@@ -38,10 +46,10 @@ No framework in the sources reviewed for this book has delivered governance with
 
 The bar this book applies to itself is simple: strong claims need strong evidence, synthesis gets labeled, and moving practices get time bounds.
 
-The individual practices (Foundation, Agent Instructions, Spec-Driven Development, Quality) are far enough along to teach directly. The team practices are not. The evidence base is thinner, the patterns are looser, and I expect some of the advice in this chapter to age badly. Better to say that plainly than to sand it down into certainty.
+The individual practices (Foundation, Agent Instructions, Spec-Driven Development, Quality) are far enough along to teach directly, but documentation feedback is not solved. There is less evidence for the team practices, and teams have not converged on one way of working. I expect to revise parts of this chapter as the field develops.
 
 The current SDD tool set is still fragmented: multiple frameworks, different trade-offs, no dominant approach, significant experimentation still underway. That is the picture this book found. The individual-developer story is further along. The team and organization story is still messy.
 
-These are live practice questions, not decorative caveats. A few should settle before the next edition. A few will come back with new names and the same operational headache. That is the view from inside a young field: half the work is learning which problems are still real.
+These questions are unresolved. Some tooling gaps will close before the next edition. Documentation drift, ownership boundaries, and weak review discipline will remain when frameworks get new names. The work now is to distinguish limitations in today's tools from problems that require engineering judgment.
 
 *Sources: ThoughtWorks, Technology Radar Vol 34, April 2026, semantic diffusion across spec-driven development and harness engineering terminology, with no single dominant framework named. The "fragmented" reading of that assessment is this book's.*