Appendix A — Story bank

Personal stories and anecdotes for Taming Complex Systems, told by the author and sourced into chapters by writing agents. This is editorial material. It is rendered as an appendix of the draft book while the manuscript is being written and will be removed before publication.

The book’s voice opens with a scene and turns it into a technique (STYLE.md, section 2). Those scenes have to be real and have to be the author’s. This file is where they live before they are written up.

Rules for agents

  1. Never invent a first-person story. If a chapter needs a scene and no entry here fits, write [[NEEDS AUTHOR: one-line description of the scene the chapter needs]] in the draft and add a placeholder entry below under the chapter. The linter reports the marker so it cannot ship unnoticed.
  2. Only use entries with status ready. placeholder entries are prompts for the author. drafted entries need the author’s sign-off on facts, names, and permission. used entries are already in a chapter; reuse only as a callback, never as a second full telling.
  3. Keep the facts as written. Do not sharpen numbers, add dialogue, or move the story to a different company. If a detail is missing, ask; do not fill.
  4. Respect the sensitivity line. Names of people, teams, customers, and employers appear in the book only when the entry says so. Otherwise use “a team I ran”, “a colleague”, “a customer”. Vendor and tool names in AI stories carry a date (STYLE.md, Register).
  5. Label the epistemic status in the prose. A story is evidence of what happened once. It supports a hypothesis; it does not prove a rule. Write “on one team” and “in my experience”, never “teams always”.
  6. Record where it was used. When a story lands in a chapter, set the status to used, fill in the Used in line, and note the framing so the next agent does not tell it again with a different moral.
  7. One story, one point. If an entry lists three lessons, the chapter takes one. The others stay here for another chapter or get cut.

Entry template

Copy this block for each new story. Keep the field order; agents parse it by eye, not by script, but consistency keeps the file scannable.

### S-NN Short title

- **Status:** placeholder | drafted | ready | used
- **When and where:** year or range; company, project, or context (as much as may be published)
- **Sensitivity:** what may be named; what must be anonymized; whose permission is needed
- **The scene:** two to five sentences. What the reader would have seen if they stood next to you. Concrete: the file, the page, the meeting, the number on the screen.
- **The turn:** the moment it stopped being routine. One sentence.
- **What it cost or saved:** measured numbers with what was measured; otherwise "not measured"
- **The point:** the one thing the story shows. One sentence, no moral yet.
- **Lenses:** cognitive load | predictability | feedback | agency (pick the one or two that carry the point)
- **Candidate chapters:** numbers from `chapters/03-book-outline.qmd`, best fit first
- **Candidate rule:** the one-line rule the chapter could close on, if this story carries it
- **Do not use for:** points the story does not support, so nobody stretches it
- **Used in:** chapter and section once placed; the framing it was given there
- **Author notes:** anything else, including what you are unsure about

Stories already visible in published writing

These come from the author’s blog, the 2026 post on the Agent Experience team, and the site’s biography. The facts listed are the published ones; the author fills in what the published version left out and decides what may be retold. Nothing here is ready until the author says so.

S-02 Four weeks without writing code (Project Deep End)

  • Status: drafted
  • When and where: January 2026; one engineering team at Poolside
  • Sensitivity: published by the company; confirm which internal details beyond the post may be used, and whether the team may be described further
  • The scene: For four weeks no one on the team writes code by hand. People write task specs and prompts and review output against the spec, not the diff. A correction to an agent counts as the team’s failure, because the harness had not captured the framing. Every trajectory lands in the pull request.
  • The turn: The bottleneck moved from the agents to everything around them: review queues, context in one person’s head, skills that died in one repo.
  • What it cost or saved: published: time to resolution for reported bugs dropped “from a queue to minutes” (not a measurement; author to say whether one exists)
  • The point: Cheap production exposes comprehension, review, and shared context as the limiting capacities.
  • Lenses: feedback, agency
  • Candidate chapters: 1 (introduction), 7 (bounded delegation)
  • Candidate rule: When an agent needs correcting, fix the harness, not the agent.
  • Do not use for: a claim that agents can replace review; the post says the opposite
  • Used in: not yet
  • Author notes: [[NEEDS AUTHOR: one concrete stumble from Deep End, with what the harness change was]]

S-03 The migration skill distilled from two years of pull requests

  • Status: drafted
  • When and where: January 2026; Poolside, during Deep End
  • Sensitivity: published; confirm whether the review comments’ content (locking, backfills, rollout order) may be quoted more specifically
  • The scene: Database migrations had collected the same careful review comments for years. An agent was pointed at two years of those pull requests and asked to distill them into a skill. Agents then wrote migrations the way the most experienced reviewers demanded, before a human saw the diff.
  • The turn: Accumulated judgment became a capability every future agent starts with.
  • What it cost or saved: not measured
  • The point: Knowledge that lives in review threads is knowledge the next person cannot use until it is made explicit.
  • Lenses: cognitive load, feedback
  • Candidate chapters: 6 (accumulation), 3 (mental models you can test)
  • Candidate rule: Turn the third identical review comment into something the system enforces.
  • Do not use for: a claim that generated skills are correct without checking; the point is the transfer, not the accuracy
  • Used in: not yet
  • Author notes: none

S-05 Sixty providers and eighteen thousand tests

  • Status: drafted
  • When and where: around 2013 to 2019; an integration platform with more than 60 provider implementations talking to real backends (blog, 2024)
  • Sensitivity: the employer is not named in the post; author to decide whether it may be
  • The scene: A newcomer building a provider ran the platform’s conformance suite and watched more than 18,000 tests run against their code without writing one. The suite told them the platform’s expectations on data formats, error handling, and capabilities.
  • The turn: The test suite was the specification that onboarded people, not the document.
  • What it cost or saved: not measured beyond the counts
  • The point: An explicit, executable contract lets a boundary explain itself to the next person without a meeting.
  • Lenses: predictability, feedback
  • Candidate chapters: 4 (boundaries that contain reasoning), 5 (feedback), 6 (accumulation)
  • Candidate rule: If the contract is not executable, it is a rumor.
  • Do not use for: arguing that every project needs a compatibility kit
  • Used in: not yet
  • Author notes: [[NEEDS AUTHOR: the newcomer’s exact reaction, and one edge case that one provider found and the suite then caught in others]]

S-06 “Shouldn’t we just rerun those tests?”

  • Status: drafted
  • When and where: same platform as S-05
  • Sensitivity: as S-05
  • The scene: Provider tests ran against real endpoints and sometimes failed on network glitches. The recurring conversation was whether to rerun them. The answer was no: the tests were not flaky, the services were, and the platform had to handle that in production too.
  • The turn: Reclassifying a “flaky test” as a report about the platform’s fault handling.
  • What it cost or saved: not measured
  • The point: Whether a signal counts as noise is a decision, and the decision determines what the team learns.
  • Lenses: feedback
  • Candidate chapters: 5 (feedback), 2 (overwhelm and flow)
  • Candidate rule: A flaky test is a fact about the system until proven otherwise.
  • Do not use for: advice about retry policies in CI
  • Used in: not yet
  • Author notes: none

S-07 The ghost in the logging framework

  • Status: drafted
  • When and where: 2019; a colleague’s end-to-end test that failed only with trace logging enabled
  • Sensitivity: the colleague is named in the blog (Holger); confirm for the book
  • The scene: A test that did HTTP requests failed consistently with trace logging on and passed with it off. Someone had “fixed” it by capping log size. Profiling a 2 MB response took 50 seconds to log. The cause: the logging framework recursively substituted ${...} variables, and the responses contained more than 3,000 of them, so the server closed the connection mid-log.
  • The turn: The working hypotheses (encoding, unicode) were wrong; the measurement pointed elsewhere.
  • What it cost or saved: measured: 50 seconds to log one response before the fix, half a second after
  • The point: A confident explanation that fits the symptom is not evidence; the profiler was.
  • Lenses: predictability, feedback
  • Candidate chapters: 3 (mental models you can test), 5 (feedback), 1 (introduction)
  • Candidate rule: Measure before you explain.
  • Do not use for: the security angle (log injection) unless the chapter is about hidden assumptions
  • Used in: not yet
  • Author notes: none

S-08 Git archeology

  • Status: drafted
  • When and where: 2021 and earlier; working in unfamiliar areas of large codebases
  • Sensitivity: none
  • The scene: Needing to know why a check exists before removing it. git blame shows a rename or a formatting commit; the real change is layers down. Peeling back commits, using pickaxe to find an error message that no longer exists on main, ignoring known noisy revisions.
  • The turn: Tests say what the code does; history says why.
  • What it cost or saved: not measured
  • The point: Understanding a change often means reconstructing the decision that produced it, and the tooling for that is underused.
  • Lenses: cognitive load, agency
  • Candidate chapters: 5 (mental models), 9 (accumulation), 12 (AI-assisted exploration, as the thing agents can do well)
  • Candidate rule: Before you remove a rule, find the commit that added it.
  • Do not use for: a tools tutorial; the book is not a git manual
  • Used in: not yet
  • Author notes: [[NEEDS AUTHOR: one real case where the history changed the decision]]

S-10 Reading code at speed

  • Status: drafted
  • When and where: 2018; a contribution to 97 Things Every Java Programmer Should Know
  • Sensitivity: none
  • The scene: Code that breaks the reader’s eye movement: three validations in three shapes, a list built with add calls except for one constructor argument that the eye skips.
  • The turn: Extracting a method is not about line count; it guides the eye so the reader can decide whether to stop.
  • What it cost or saved: not measured
  • The point: Readability is about what the reader can skip safely, and the writer controls that.
  • Lenses: cognitive load
  • Candidate chapters: 2 (overwhelm and flow), 4 (boundaries that contain reasoning)
  • Candidate rule: Write code the next person can skim without missing the important line.
  • Do not use for: speed-reading claims about people; the numbers in the post are about reading, not code
  • Used in: not yet
  • Author notes: none

S-11 Kaylie and the Konami code

  • Status: drafted
  • When and where: 2021 blog post; Kaylie is invented
  • Sensitivity: must be labeled as an invented case if used (STYLE.md, Citations and claims)
  • The scene: A senior engineer joins a company with a large, undocumented codebase and takes on a feature. She writes a system test first, traces a path through the code without touching it, hacks the path through with every shortcut allowed, resets, then does the refactorings the spike revealed before implementing for real.
  • The turn: The hack is exploration, not implementation; its output is a list of what stands in the way.
  • What it cost or saved: not measured
  • The point: Separating the learning pass from the building pass reduces what has to be held in mind at once.
  • Lenses: cognitive load, predictability
  • Candidate chapters: 5 (mental models you can test), 13 (bounded delegation, as the human version of specify-then-build)
  • Candidate rule: Don’t fake anything you don’t know yet.
  • Do not use for: anything presented as a real team
  • Used in: not yet
  • Author notes: The rule is one of the author’s best lines. Consider giving it a real story instead of Kaylie.

S-12 Copilot: the demo and the product

  • Status: placeholder
  • When and where: 2021 to 2023; founding team of GitHub Copilot (site biography: first context engine for Copilot Chat, an intent classifier, the A/B pipeline that lifted completion acceptance by 15 percent, caching and debouncing to cut inference cost)
  • Sensitivity: [[NEEDS AUTHOR: what may be said publicly beyond the biography]]
  • The scene: [[NEEDS AUTHOR: one moment where a change to context selection changed what users accepted, and how the team found out]]
  • The turn: [[NEEDS AUTHOR]]
  • What it cost or saved: 15 percent lift in completion acceptance is published on the author’s site; define the measure before use
  • The point: [[NEEDS AUTHOR: candidate: the feedback loop, not the model, decided what shipped]]
  • Lenses: feedback
  • Candidate chapters: 5 (feedback), 3 (mental models you can test)
  • Candidate rule: [[NEEDS AUTHOR]]
  • Do not use for: product claims about Copilot
  • Used in: not yet
  • Author notes: none

S-13 Why the open source people were so good

  • Status: placeholder
  • When and where: 2022 talk The Open Source Effect, given at DevoxxUK, EclipseCon, Voxxed Days, XP Days
  • Sensitivity: the talk names colleagues’ careers; confirm each before use
  • The scene: [[NEEDS AUTHOR: the two or three career stories from the talk, one paragraph each]]
  • The turn: [[NEEDS AUTHOR]]
  • What it cost or saved: not measured
  • The point: [[NEEDS AUTHOR: candidate: working in public on systems you did not build teaches the reading and reasoning skills this book is about]]
  • Lenses: agency, cognitive load
  • Candidate chapters: 6 (accumulation), 8 (practice)
  • Candidate rule: [[NEEDS AUTHOR]]
  • Do not use for: advocacy for open source in general
  • Used in: not yet
  • Author notes: The talk could not be transcribed when this file was created. The author’s own notes or slides are the source.

Placeholders by chapter

Stories the outline calls for and the bank does not yet hold. Each is a prompt; the author replaces the bracketed text or deletes the entry.

Part I. The human constraint (chapters 1 and 2)

S-14 A change you could not tell was safe

  • Status: placeholder
  • Candidate chapters: 1
  • Prompt: [[NEEDS AUTHOR: a real change, ideally recent, where the patch was ready in minutes and deciding whether it belonged took much longer. What did you have to open to decide? Who did you have to ask?]]

S-15 Small code, large model

  • Status: placeholder
  • Candidate chapters: 1
  • Prompt: [[NEEDS AUTHOR: a short piece of code (concurrency, a scheduler, a retry) that took disproportionate effort to reason about, and a large subsystem that was easy to change because its invariants were explicit]]

S-16 The adapter that was cheaper than the conversation

  • Status: placeholder
  • Candidate chapters: 2, 6
  • Prompt: [[NEEDS AUTHOR: a time you, or someone on your team, added a wrapper, copy, or special case because finding the owner or understanding the shared design was too expensive that day. What was the deadline? What did it cost later?]]

S-17 Two feedback loops for the same change

  • Status: placeholder
  • Candidate chapters: 2, 5
  • Prompt: [[NEEDS AUTHOR: the real version of the three-second local check versus the 35-minute integration loop in WORKLOG.md. Which project, what did people do while waiting, how did that change what they batched?]]

Part II. Design for bounded understanding (chapters 3 and 4)

S-18 Reconstructing a request path

  • Status: placeholder
  • Candidate chapters: 3
  • Prompt: [[NEEDS AUTHOR: a time a trace or a debugger session contradicted the mental model you had built from reading code]]

S-19 The rule that lived in three places

  • Status: placeholder
  • Candidate chapters: 4
  • Prompt: [[NEEDS AUTHOR: a business rule duplicated across a service, a flag path, and a job, and what happened when one copy changed. This is the recurring example’s real ancestor if one exists]]

S-20 The wrapper that leaked

  • Status: placeholder
  • Candidate chapters: 4
  • Prompt: [[NEEDS AUTHOR: an abstraction that simplified callers until a hidden behavior (duplicate side effects, retries, caching) forced everyone to learn the implementation anyway]]

Part III. Keep understanding alive (chapters 5 and 6)

S-21 The passing test and the production trace

  • Status: placeholder
  • Candidate chapters: 5
  • Prompt: [[NEEDS AUTHOR: a unit test that was green while production disagreed, and how the team found out which one was lying]]

S-22 The temporary exception, four releases later

  • Status: placeholder
  • Candidate chapters: 6
  • Prompt: [[NEEDS AUTHOR: one “temporary” flag, branch, or fallback that outlived its reason, and who eventually had to understand it]]

S-23 Waiting for the one expert

  • Status: placeholder
  • Candidate chapters: 6
  • Prompt: [[NEEDS AUTHOR: a team where changes queued behind one person, and what you did about it as the lead. What worked, what you would not repeat]]

S-24 A decision you made as a lead that moved complexity instead of removing it

  • Status: placeholder
  • Candidate chapters: 6, 8
  • Prompt: [[NEEDS AUTHOR: the leader’s-angle story. A boundary, platform, or process you introduced that helped one group and made another’s work harder. The book needs at least one of these told against yourself]]

Part IV. AI and the practice of tractability (chapters 7 and 8)

S-25 The patch and its tests agreed on the same wrong rule

  • Status: placeholder
  • Candidate chapters: 7
  • Prompt: [[NEEDS AUTHOR: an agent-generated change whose generated tests shared its misunderstanding, and what independent evidence caught it. Date, tool, and model version]]

S-26 Using the agent to learn instead of to finish

  • Status: placeholder
  • Candidate chapters: 3
  • Prompt: [[NEEDS AUTHOR: a time you used an agent to map a repository, reconstruct history, or find dependencies, and could explain the result afterward. Compare with a time you accepted a summary and could not]]

S-27 Rehearsing recovery before delegating

  • Status: placeholder
  • Candidate chapters: 7
  • Prompt: [[NEEDS AUTHOR: a delegation to an agent where you specified the change, reviewed against the spec, and had a rollback ready. Include one where the rollback was needed]]

S-28 The same feature, a year later

  • Status: placeholder
  • Candidate chapters: 8
  • Prompt: [[NEEDS AUTHOR: a system you returned to after time away, with agents in the loop. What was still tractable, what was not, and which of the four lenses explained the difference]]

Sourcing log

Record here when a story is taken into a chapter, so agents can see at a glance what is spent.

Story Chapter and section Date Framing given
none yet