Proposed Book Outline
On the Back Cover
Writing code has never been cheaper. An agent can produce a working feature before you have finished reading the ticket. Knowing what that feature will do to the rest of your system is as expensive as it ever was.
Taming Complex Systems is about that gap. The scarce resource in software engineering is no longer the ability to produce a change; it is the ability to understand one. Systems slip out of control when the people responsible for them can no longer explain what they do, predict what a change will break, or recover when it does.
This book shows how to keep systems within reach. It starts with the human constraint: why software overwhelms capable engineers, and why overwhelmed engineers make reasonable choices that add complexity. Then it turns to the engineering that works within that constraint. That means mental models you can test, boundaries that keep those models small, and feedback that tells you when they are wrong. Finally, it puts AI in its place, as a tool that can widen the gap between what we change and what we understand, or help close it.
For software engineers and technical leaders who work in systems no single person can hold in their head, and who want to keep changing those systems with confidence.
The Chapters at a Glance
Table 1 lines up the eight chapters on the four lenses, the part of the recurring example each one uses, and the story bank entries that could carry it. Each chapter below ends with a collapsed block holding the rest: topics, terms, loops, and the books on the reading list to check first. None of this is reader-facing; it is a working index for planning.
| Ch | Lenses carrying the point | Recurring example | Candidate stories |
|---|---|---|---|
| 1 | All four introduced; cognitive load, predictability | The whole feature, delivered by an agent | S-14, S-15, S-02 |
| 2 | Cognitive load, feedback, agency | The pricing adapter with its own copy of the cap | S-16, S-17, S-06, S-10 |
| 3 | Predictability, feedback | The checkout-to-invoice request path | S-18, S-26, S-07, S-08, S-11 |
| 4 | Cognitive load, predictability | The discount rule in three places; a retry wrapper | S-19, S-20, S-05 |
| 5 | Feedback, predictability | Green unit tests versus the invoice comparison | S-21, S-17, S-06, S-05 |
| 6 | Cognitive load, agency | The pricing-v2 flag that outlived its reason |
S-22, S-23, S-24, S-16, S-03 |
| 7 | Agency, feedback | A patch and tests that share the wrong rule | S-25, S-27, S-02, S-11 |
| 8 | All four, as a routine | The opening feature, revisited | S-28, S-24, S-13 |
Part I: The Human Constraint
1. Introduction: Comprehension Is the Scarce Resource
When producing a plausible change becomes easier than understanding its consequences, what should engineering optimize? This chapter makes the case for comprehension and introduces tractability: whether the people doing a given task on a given system can understand it well enough to change it safely. It separates size from reasoning burden and essential from accidental complexity, and shows how simplifying one place can move complexity to another. It also introduces the four lenses used throughout the book: cognitive load, predictability, feedback, and agency. In the opening example, an agent delivers a small feature in minutes. The engineer then needs far longer to reconstruct its assumptions across flags, jobs, and service boundaries.
- Question: When producing a plausible change is easier than understanding it, what should engineering optimize?
- Lenses: Introduces all four; the opening example leans on cognitive load and predictability.
- Topics: Comprehension as the scarce resource; size versus reasoning burden; essential versus accidental complexity; complexity that moves instead of leaving.
- Terms introduced: Tractability; the four lenses.
- Loops: The learning loop as the book’s backbone, previewed.
- Recurring example: An agent delivers the member discount change in minutes; the engineer reconstructs its assumptions across
pricing-v2, the nightly job, andbilling. - Stories: S-14 a change you could not tell was safe (placeholder); S-15 small code, large model (placeholder); S-02 Project Deep End (drafted); S-07 the logging ghost (drafted, third choice).
- Reading list: Brooks, No Silver Bullet; Meadows, Thinking in Systems; Page, Understanding Complexity.
- Open questions: WORKLOG 1 (enough understanding for a change), 10 (examples that challenge the thesis).
2. Overwhelm and Flow
What makes a difficult task feel manageable, and what happens to our work when it stops feeling that way? Overwhelm and flow are two ends of one balance. On one side is what a task demands; on the other, what we can bring to it: working memory, attention, clear goals, reliable feedback, and a sense of control. When the balance tips, capable people avoid unfamiliar code, copy patterns, and add wrappers, and those reasonable local choices make the next change harder. The chapter follows a developer who adds an adapter because finding the owner of the existing rule is too expensive. It then compares the same change under a fast local feedback loop and a slow, unreliable one.
- Question: What makes a difficult task feel manageable, and what happens to our work when it stops feeling that way?
- Lenses: Cognitive load, feedback, agency.
- Topics: Working memory and attention; flow conditions; challenge against capacity; risk-avoiding local choices (copy, wrap, avoid); feedback latency and batching.
- Terms introduced: Overwhelm and flow as one balance; defensive choices described in plain words, not as a term.
- Loops: Orientation to overload; the reinforcing complexity loop, as the learning loop running backward.
- Recurring example: A developer adds the pricing adapter with its own copy of the cap because finding the rule’s owner costs too much that day.
- Stories: S-16 the adapter cheaper than the conversation (placeholder); S-17 two feedback loops for one change (placeholder); S-06 rerun those tests? (drafted); S-10 reading code at speed (drafted).
- Reading list: Csíkszentmihályi, Flow; Hermans, The Programmer’s Brain; DeMarco and Lister, Peopleware; Leroy via Newport, Deep Work.
- Open questions: WORKLOG 4 (which psychological mechanisms transfer to software work).
Part II: Design for Bounded Understanding
3. Mental Models You Can Test
How do we move from unfamiliar code to an explanation good enough to guide a change? This chapter teaches one loop: ask a bounded question, inspect the evidence, build a model, predict an outcome, check it, and revise. Names, diagrams, documentation, history, and AI explanations all help, and all make claims that need checking. AI can run the loop faster, but accepting its summary is not the same as testing it. The example reconstructs a request path with an agent’s help, forms three predictions, and uses a surprising case to correct the model.
- Question: How do we move from unfamiliar code to an explanation good enough to guide a change?
- Lenses: Predictability, feedback.
- Topics: Bounded questions; evidence from names, diagrams, docs, history, and traces; predictions you can check; AI explanations as claims; exploration separated from implementation.
- Terms introduced: Mental model.
- Loops: The learning loop in full: question, evidence, model, prediction, check, revision; AI-assisted learning.
- Recurring example: Reconstructing the checkout-to-invoice request path with an agent, three predictions, and one surprising case.
- Stories: S-18 reconstructing a request path (placeholder); S-26 using the agent to learn (placeholder); S-07 the logging ghost (drafted); S-08 git archeology (drafted); S-11 Kaylie, invented (drafted).
- Reading list: Hermans, The Programmer’s Brain; Feathers, Working Effectively with Legacy Code; Tetlock and Gardner, Superforecasting; Parrish, The Great Mental Models.
- Open questions: WORKLOG 2 (observing comprehension beyond confidence).
4. Boundaries That Contain Reasoning
How much must someone understand before changing this one thing? Information hiding, contracts, state ownership, and explicit effects matter for the reasoning they let us skip. A good abstraction compresses what we need to know; a leaky one makes us learn two models instead of one. The chapter distinguishes boundaries that contain reasoning from boundaries that only separate deployments, and removing complexity from moving it. It follows one rule change through a module and through a multiservice request. Then a retry wrapper simplifies its callers until duplicate side effects force everyone to learn what it hides.
- Question: How much must someone understand before changing this one thing?
- Lenses: Cognitive load, predictability.
- Topics: Information hiding; contracts; state ownership; explicit effects; boundaries that contain reasoning versus boundaries that separate deployments; removing versus moving complexity.
- Terms introduced: Local reasoning; cognitive blast radius; abstraction as compression.
- Loops: None new; leaky abstractions double the model to carry.
- Recurring example: The discount rule in
orders, the adapter, and the nightly job; a retry wrapper whose duplicate side effects leak. - Stories: S-19 the rule in three places (placeholder); S-20 the wrapper that leaked (placeholder); S-05 sixty providers, 18,000 tests (drafted).
- Reading list: Evans, Domain-Driven Design; Fowler, Refactoring; Nygard, Release It!; Parnas on information hiding (not on the shelf).
- Open questions: WORKLOG 3 (is cognitive blast radius useful), 5 (abstraction versus concealment).
Part III: Keep Understanding Alive
5. Feedback That Corrects the Model
How cheaply can we find out that our explanation is wrong? Types, tests, CI, observability, and experiments are feedback at different distances from a decision, and each is only as useful as it is relevant, fast, reliable, and readable. A passing check supports a specific claim and nothing more. The example is a passing unit test and a production trace that disagree, and the work of finding out which assumption each one tested.
- Question: How cheaply can we find out that our explanation is wrong?
- Lenses: Feedback, predictability.
- Topics: Types, tests, CI, observability, and experiments as feedback at different distances; relevance, speed, reliability, readability; what a passing check supports.
- Terms introduced: None new; feedback qualities as a checklist.
- Loops: Hypothesis, small change, relevant feedback, revised model.
- Recurring example: Unit tests pass on both pricing paths; only the invoice-versus-checkout comparison disagrees.
- Stories: S-21 the passing test and the production trace (placeholder); S-17 two feedback loops (placeholder); S-06 rerun those tests? (drafted); S-05 sixty providers (drafted).
- Reading list: Freeman and Pryce, Growing Object-Oriented Software; Humble and Farley, Continuous Delivery; Beyer and colleagues, Site Reliability Engineering.
- Open questions: WORKLOG 8 (when passing tests miss the risk).
6. How Complexity Accumulates
Why do reasonable local decisions make future changes harder? Special cases, flags, duplicated patterns, and forgotten constraints pile up, and so does knowledge: a change that waits for the one person who understands it is complexity too. The chapter treats deletion, consolidation, and incremental refactoring as ways to win tractability back, with evidence that behavior still holds. It follows a temporary exception across releases until only one person can explain it, then removes the machinery it no longer needs.
- Question: Why do reasonable local decisions make future changes harder?
- Lenses: Cognitive load, agency.
- Topics: Special cases, flags, duplicated patterns, forgotten constraints; knowledge concentrated in one person; deletion, consolidation, and incremental refactoring with evidence.
- Terms introduced: None new; knowledge concentration in plain words.
- Loops: The reinforcing complexity loop; the distributed knowledge loop.
- Recurring example: The
pricing-v2flag stays temporary across releases until one person can explain it. - Stories: S-22 the temporary exception (placeholder); S-23 waiting for the one expert (placeholder); S-24 a lead’s decision that moved complexity (placeholder); S-16 the adapter (placeholder); S-03 the migration skill (drafted); S-08 git archeology (drafted).
- Reading list: Feathers, Working Effectively with Legacy Code; Fowler, Refactoring; Meadows, Thinking in Systems; Larson, Staff Engineer.
- Open questions: WORKLOG 6 (when outsourcing understanding is rational), 9 (how much organizational material).
Part IV: AI and the Practice of Tractability
7. Delegating Without Outrunning Understanding
What must be explicit for an agent’s work to stay reviewable, understood, and recoverable? Generation can outrun understanding, and generated tests can share the mistakes of the code they test. The answer is not to stop delegating but to bound it: clear task boundaries, acceptance criteria, small changes, independent checks, and a rehearsed way back. Producing evidence is not the same as judging that it answers the requirement, and that judgment stays with people. The example is a patch and its tests that agree on the same wrong rule, caught by a behavioral requirement established independently of both.
- Question: What must be explicit for an agent’s work to stay reviewable, understood, and recoverable?
- Lenses: Agency, feedback.
- Topics: Generation outrunning understanding; generated tests sharing the code’s mistakes; bounded delegation (task boundaries, acceptance criteria, small changes, independent checks, rehearsed rollback); judgment stays with people.
- Terms introduced: Comprehension gap; bounded delegation.
- Loops: The AI dependency spiral, as the learning loop running backward.
- Recurring example: An agent’s patch and tests agree on the wrong cap; the invariant that invoice total equals checkout total catches it.
- Stories: S-25 patch and tests agree on the wrong rule (placeholder); S-27 rehearsing recovery (placeholder); S-02 Project Deep End (drafted); S-11 Kaylie, invented (drafted).
- Reading list: Kahneman, Thinking, Fast and Slow (fluency, with replication caveats); Fry, Hello World; Huyen, Designing Machine Learning Systems; automation bias studies (not on the shelf).
- Open questions: WORKLOG 7 (performance now versus retained understanding), 8 (independent evidence).
8. A Practice of Tractability
What can we change next week, and how will we know it helped? The closing chapter turns the four lenses into a routine: pick a real task, map how much reasoning it takes, find where the uncertainty is, intervene, and repeat the task. Signals such as time to a verified explanation help, as long as nobody mistakes them for a universal complexity score. The book ends where it began, with the opening feature, and asks what engineers can now predict, explain, and recover.
- Question: What can we change next week, and how will we know it helped?
- Lenses: All four, as a repeatable routine.
- Topics: Pick a real task, map its reasoning, locate uncertainty, intervene, repeat the task; signals such as time to a verified explanation; why no universal complexity score.
- Terms introduced: None new; the coined terms put to work.
- Loops: The learning loop applied to the team’s own practice.
- Recurring example: The opening feature, revisited: what can the engineer now predict, explain, and recover.
- Stories: S-28 the same feature, a year later (placeholder); S-24 a lead’s decision (placeholder); S-13 the open source effect (placeholder).
- Reading list: Reilly, The Staff Engineer’s Path; Beyer and colleagues, Site Reliability Engineering; Wheelan, Naked Statistics.
- Open questions: WORKLOG 2 (observing comprehension), 12 (scope and length).