Vary prose rhythm and add authorial voice

Rewrite the recurring "X is not Y. It is Z." contrast formula down to
at most one per chapter, merge mechanical staccato runs into flowing
sentences, and add first-person observations where the author has
real ground to stand on, including disclosures that the Plain Text as
Code Manifest and .principles are the author's own projects.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: flemming-n-larsen

content/agent-instructions/agents-md.md

@@ -49,7 +49,7 @@ The alternative is picking a vendor file as canonical. A repo whose source of tr
 
 ## Generated pointers, not authored duplicates
 
-A pointer file maintained by hand drifts from `AGENTS.md` the moment one update is forgotten. The fix is not better discipline. The fix is generation: a short script that writes the pointer from `AGENTS.md` (Python, TypeScript, or whatever your repo already runs). One or two lines either way, committed as output. The developer edits `AGENTS.md`, runs the generator, and commits the result. The convention lives in the generator, not in anyone's memory.
+A pointer file maintained by hand drifts from `AGENTS.md` the moment one update is forgotten. Better discipline will not fix that; generation will. A short script writes the pointer from `AGENTS.md` (Python, TypeScript, or whatever your repo already runs). One or two lines either way, committed as output. The developer edits `AGENTS.md`, runs the generator, and commits the result. The convention lives in the generator, not in anyone's memory.
 
 Generated files go into the commit without ambiguity. They are clearly outputs, not sources. A developer who sees a generated file in a PR review knows not to edit it: edit the source, regenerate, commit the output.
 

content/agent-instructions/instruction-hub.md

@@ -2,7 +2,7 @@
 
 Two developers, same repo, same language, same CI pipeline. Their pull requests still come back with different naming, different directories off-limits, different test structures. The rules diverged because the instruction files diverged.
 
-The fix is not better synchronization between two files. It is one source that both tools point to.
+The fix is one source that both tools point to, not better synchronization between copies.
 
 `AGENTS.md` is the entry point, and `.agents/instructions/` is what it points into. One directory, no vendor in the name, readable by every tool.
 

content/agent-instructions/instructions-that-work.md

@@ -12,7 +12,7 @@ The problem: you do not know what the agent will get wrong until it gets it wron
 
 An instruction written before a failure is a guess. The agent might never need it. Or the agent reads it in a situation you did not foresee, and the guess produces a failure of its own.
 
-The practical move in this book is to start minimal and add reactively. The agent violates a convention. Write the instruction that prevents it. That instruction is grounded in a real failure. It states the constraint that bit and prevents a repeat, instead of guarding against a problem you only guessed at. Write it immediately: the failure is in front of you, so you point to the exact wrong output and say what to do instead. Wait a day, and you are writing from memory, not from evidence.
+My practical rule is to start minimal and add reactively. The agent violates a convention. Write the instruction that prevents it. That instruction is grounded in a real failure. It states the constraint that bit and prevents a repeat, instead of guarding against a problem you only guessed at. Write it immediately: the failure is in front of you, so you point to the exact wrong output and say what to do instead. Wait a day, and you are writing from memory, not from evidence.
 
 Only writing after a failure keeps the file short: nothing enters unless a real failure earned it. A short file loads fast, stays readable, and carries only load-bearing rules. A file full of preemptive rules accumulates guesses the repo never exercises.
 

content/agent-instructions/skills-commands-hooks.md

@@ -76,7 +76,7 @@ The output should read like data, not terminal noise:
 }
 ```
 
-This is not polish. It is control. An agent should not have to scrape help text to discover which command lists datasets, which one mutates state, or which missing input blocked the run.
+This is control, not polish: an agent should not have to scrape help text to discover which command lists datasets, which one mutates state, or which missing input blocked the run.
 
 *Sources: Anthropic, "Building effective agents" (December 2024), predefined workflows, and deterministic paths. The command contract in this section is this book's synthesis.*
 

content/appendices/adoption-checklist.md

@@ -4,7 +4,7 @@ A starting point for applying the practices in this book to a new or existing co
 
 This is not a required sequence. Apply what fits your context. Stop when the cost exceeds the value. See [Honest Maturity](/appendices/honest-maturity) for how to label what you have versus what you are working toward.
 
-If you are using `iec` locally, `iec init` creates the directory scaffold and stub files. Edit each stub for your system before committing. Unedited stubs are worse than no docs.
+If you are using `iec` locally, `iec init` creates the directory scaffold and stub files. Edit each stub for your system before committing; an unedited stub only pretends to be documentation.
 
 If brownfield: harvest structure, dependencies, key decisions, design constraints, and business rules into `skeleton.md` and the permanent `docs/` set before any of the below. Review that recovery pass with a domain expert before the first change proposal. Move stable findings into `docs/architecture/`, `docs/design/`, and `docs/decisions/` rather than leaving the next agent session to reverse-engineer them again from `docs/skeleton.md`. See [Brownfield vs Greenfield](/foundation/brownfield-vs-greenfield).
 

content/foundation/brownfield-vs-greenfield.md

@@ -1,6 +1,6 @@
 # Brownfield vs Greenfield: Bootstrap with skeleton.md
 
-Consider a retry policy buried in a function called `do_it_again_lol`. The author left years ago, and nobody knows what it retries or why it retries at all. The system went through several rewrites and handoffs. The original architect was certain about several things, none of which are written down anywhere.
+Consider a retry policy buried in a function called `do_it_again_lol`. Every legacy codebase has one. The author left years ago, and nobody knows what it retries or why it retries at all. The system went through several rewrites and handoffs. The original architect was certain about several things, none of which are written down anywhere.
 
 An agent dropped into this environment improvises. At agentic speed, that improvisation compounds existing drift.
 

content/foundation/document-types.md

@@ -32,9 +32,9 @@ README and INDEX live in the same directory and share the same lifespan, but the
 
 ## Design docs
 
-Design docs live in `docs/design/` and hold per-feature thinking: options weighed, approach chosen, risks named. They are not decision records, and they are not specs. A design doc describes the approach. A spec defines the behavior.
+Design docs live in `docs/design/` and hold per-feature thinking: options weighed, approach chosen, risks named. They are not decision records, and they are not specs: a design doc describes the approach, a spec defines the behavior.
 
-Some teams write them and move on. Others keep them current. Both are reasonable. Pick one policy and apply it consistently, so the agent does not load a 2025 design doc as if it still described the 2026 implementation.
+Some teams write them and move on, others keep them current, and both are reasonable. Pick one policy and apply it consistently, so the agent does not load a 2025 design doc as if it still described the 2026 implementation.
 
 *Sources: `iec` repo conventions in this project family, the docs/design/ placement and write-and-forget vs. keep-current treatment.*
 

content/foundation/intent-engineering-and-the-sdlc.md

@@ -2,7 +2,7 @@
 
 This chapter rejects a tempting pitch: replace your SDLC with a new one. New ceremonies, new artifacts, a new review process. Existing tooling becomes legacy on contact.
 
-The pitch fails where the engineering process already has teeth: Continuous Integration (CI) catches mistakes, reviewers defend standards, and the Jira board drives planning. This chapter makes the opposite move. Keep the delivery flow. Change the artifacts moving through that flow.
+The pitch fails where the engineering process already has teeth: Continuous Integration (CI) catches mistakes, reviewers defend standards, and the Jira board drives planning. This chapter makes the opposite move: keep the delivery flow, change the artifacts moving through it.
 
 This book uses Spec-Driven Development for the broader practice of _writing intent before writing code_. Intent Engineering is this book's version of the practice. The Software Development Life Cycle (SDLC) stays in place.
 

content/foundation/plain-text-as-code.md

@@ -10,9 +10,9 @@ If the agent needs it, it lives in the repo. If it lives in the repo, it lives i
 
 Plain text means a format a human reads in a terminal, a Git diff shows line by line, and a language model processes without conversion: Markdown for prose, Mermaid for diagrams, and Markdown Architectural Decision Records (MADR) for decisions. Nothing exotic.
 
-This is not a migration project. The document starts in the repo, evolves there, and is reviewed in the same PR as the code it describes. If someone needs the same content in Confluence, in a PowerPoint deck, or on a wiki, produce an export, a one-way snapshot. The repo is the source of truth. Everything else is derivative output.
+This is not a migration project. The document starts in the repo, evolves there, and is reviewed in the same PR as the code it describes. If someone needs the same content in Confluence, in a PowerPoint deck, or on a wiki, produce an export, a one-way snapshot. The repo is the source of truth; everything else is derivative output.
 
-Docs-as-code is the established version of this idea, narrowed here to one rule and extended past prose to diagrams and decisions. The book author's Plain Text as Code Manifest (github.com/Plain-Text-as-Code) is the fuller statement. This chapter applies it to the Intent Engineering Foundation. The boundary is easy to write down and hard to enforce: which formats belong, and where in the repo they live.
+Docs-as-code is the established version of this idea, narrowed here to one rule and extended past prose to diagrams and decisions. I care enough about this rule to have written it down as a manifest: the Plain Text as Code Manifest (github.com/Plain-Text-as-Code) is the fuller statement, and this chapter applies it to the Intent Engineering Foundation. The boundary is easy to write down and hard to enforce: which formats belong, and where in the repo they live.
 
 *Sources: Write the Docs, "Docs as Code" guide (writethedocs.org/guide/docs-as-code, ongoing), docs-as-code as the established practice this extends. Plain Text as Code Manifest (github.com/Plain-Text-as-Code, ongoing), the book author's statement of the philosophy.*
 
@@ -30,7 +30,7 @@ If a decision or convention needs to exist, it lives in a Markdown file in `docs
 
 A C4 diagram in draw.io is opaque to agents and unreviewed by humans. The file format describes shape positions and styles, not graph semantics, and nobody opens the source to verify a PR description's claim that the architecture changed.
 
-Mermaid is different. The syntax encodes the graph itself, not a picture of boxes and arrows, but the relationships. The same diagram, as a source and as a render:
+Mermaid is different: the syntax encodes the graph itself, not a picture of boxes and arrows but the relationships. The same diagram, as a source and as a render:
 
 Mermaid diagram embedded in Markdown:
 
@@ -70,7 +70,7 @@ Mermaid covers [28 diagram types](https://mermaid.ai/open-source/intro/index.htm
 
 D2 is the more interesting format on its merits, but as of mid-2026, no major Git vendor renders it inline. A D2 block shows up as a code listing in a PR review, not a diagram. Mermaid is the right call for now.
 
-The C4 model gives a useful set of diagram types (**C**ontext, **C**ontainer, **C**omponent, **C**ode) that map cleanly onto `docs/architecture/README.md` (architecture overview) and per-feature design docs. Structurizr defines those models in a text DSL rather than a drawing tool, the same plain-text-as-code move applied to architecture. Diagrams show structure. They do not explain why the structure is what it is.
+The C4 model gives a useful set of diagram types (**C**ontext, **C**ontainer, **C**omponent, **C**ode) that map cleanly onto `docs/architecture/README.md` (architecture overview) and per-feature design docs. Structurizr defines those models in a text DSL rather than a drawing tool, the same plain-text-as-code move applied to architecture. Diagrams show structure; they do not explain why the structure is what it is.
 
 *Sources: Mermaid (mermaid.ai), the diagram format used throughout. Mermaid live editor (mermaid.live), the editing escape hatch. Mermaid diagram types (mermaid.ai/open-source/intro/index.html), 28 diagram types as of mid-2026. D2 (d2lang.com), the alternative format not yet rendered inline by Git hosts as of mid-2026. C4 model, Simon Brown (c4model.com), the diagram types mapping to architecture docs. Structurizr, Simon Brown (docs.structurizr.com), C4 models authored as a text DSL.*
 

content/foundation/why-structure.md

@@ -4,19 +4,19 @@ Your agent adds a new `POST /orders` REST endpoint.
 
 Consider a codebase that moved to gRPC months ago for typed contracts, streaming, and performance reasons that live in one architect's head and zero files in the docs. Every other service in the codebase is gRPC.
 
-REST is what the model reaches for by default. The decision to leave it behind and replace it with gRPC happened in a team meeting but never became a readable file, for the agent or anyone else.
+REST is what the model reaches for by default. The decision to leave it behind and replace it with gRPC happened in a team meeting but never became a readable file, for the agent or anyone else. Most of us have sat in that meeting.
 
 The handler compiles and passes its tests. The codebase now speaks two protocols. A reviewer misses the mismatch, client code starts to depend on the REST endpoint, and reversing the choice costs more than writing the Architectural Decision Record (ADR) would have.
 
 This one PR is the smallest version of the problem. The codebase holds hundreds like it, each one an undocumented decision waiting to be overwritten. The count keeps climbing. Every agent session widens the gap between what the team decided and what the code now says.
 
 ## Compounding drift
 
-The model did not fail. Given the available context, the agent reasoned correctly. The constraint was missing.
+The model did not fail: given the available context, the agent reasoned correctly. The constraint was missing.
 
 ThoughtWorks called this cognitive debt in their April 2026 Radar: the agentic-era analogue to technical debt, but harder to detect because no linter catches an undocumented decision. Code has static analysis. Context does not. A team that ships ten agent-assisted PRs a week makes ten chances a week to encode an unwritten constraint as a contradiction in the codebase.
 
-There is a flip side: the same agents that run up cognitive debt also clear code debt faster. A refactor that took a sprint now takes an afternoon. The debt does not disappear. It moves from the code to the gap between what the team decided and what the codebase expresses.
+There is a flip side: the same agents that run up cognitive debt also clear code debt faster. A refactor that took a sprint now takes an afternoon. The debt does not disappear; it moves from the code to the gap between what the team decided and what the codebase expresses.
 
 At human speed, drift like this used to take quarters to compound. At agentic speed, it takes weeks, sometimes days. Yegge's "Revenge of the junior developer" framed this as the velocity amplifier: agents make good architectures sharper and bad ones uninhabitable, both faster than before.