Appendix C — Case Studies

Every field note in this playbook — every nicknamed bug, every three-deploy chase, every "we thought it was X, it was actually Y" — comes from one of six real projects. The first is a full-stack production web application built by a small team over more than two years, heavy on agent collaboration from early days, shipped through some thirty public releases from its founding sprint through its most recent major version — which itself was built in parallel waves with survey agents, two-stage review, and mandatory wire-level integration tasks, and contributed several of the second edition's new rules. It's live. It has users. It has the kinds of scars a project gets when you ship things on purpose, read your own retros, and write the next one anyway. This appendix intentionally anonymizes product identity across all six case studies — the point of the playbook is the practice, not the products — so what's described below is the shape of each effort: team size, velocity, release cadence, coordination pattern, and what each one added to the rules.

The retrospective practice is the part that matters for this playbook. Every release — feature, patch, infrastructure cycle, emergency hotfix — got a narrative retro at the end. Not a changelog and not a feature list: an actual story, written in voice, with the bugs named by the nicknames they earned while people were fixing them. The Doorbell That Never Rang. The Health Check That Wasn't. The Month That Wasn't Thirty Days. The Vitest Cache Incident. The discipline of writing those retros is what generated the raw material this playbook is curated from. Part V's field-note gallery is the short list — the entries that transferred cleanest to a rule — but every other inline vignette traces back to one of those retros.

They appear in this playbook as inline vignettes rather than as links for one reason: the reader is not assumed to have access to the source. That is the whole point of this portable version. Every story this playbook actually relies on is told in full, right where it's cited. You do not need to click anywhere. If the vignette feels thin, the rule above it is still carrying the weight; if the vignette feels thick, you have what you need without leaving the page.

The same practice, applied to any project with any tech stack, would generate the same kind of material. Your bugs will not be our bugs. Your deploy script will fail in ways ours never did. Your agent will invent helpers your team will never use. Those become your field notes — and they will, at the time you are writing them, feel exactly as load-bearing as ours did to us.

The specific project is not the point. The practice is the point. Your project's field notes are going to look different and be just as load-bearing.

Second case study — a parallel-agent protocol server

Partway through curating this playbook, we pressure-tested it against a second project with a very different shape: a single-binary server whose work was implementing a large catalog of external network-protocol specifications as plug-in adapters behind a narrow shared interface. Over nine releases and roughly six months, it grew from three adapters to more than seventy, spanning TCP, UDP, TLS, HTTP, IPC, binary wire protocols, text protocols, XML streams, binary-encoded formats, and build-tag-gated platform-specific primitives. The project is a single Go binary with two external Go dependencies and two sidecar Python dependencies, approximately 15,000 lines of code, and a five-method interface that never changed across any release. It was built almost entirely by parallel agents — four, six, seven, sometimes twelve at once — with humans holding the planning, retros, and judgment calls.

The shape is completely unlike the first case study. No production database. No user-visible UI. No deploy drama (it ships as a container image and a docker-compose file). No quarterly release calendar. The work is rhythmic, mechanical, and heavily parallelizable by construction. If the first case study is "one team shipping a web app to real users for two years," the second is "can a small group of humans direct a fleet of agents to implement dozens of protocol specs, and keep the results coherent?" Different question, different scars.

What held without modification. Verification (§8), the loop (§5), retros (§16), memory hygiene (§6), trust boundaries (§9), and plan quality (§14) all landed in the second case study the same way they landed in the first. The core rules are not artifacts of one project's shape — they're the disciplines that make agent-directed work legible at all.

What the second case study amplified. Parallel agents (§13) gained three new rules' worth of evidence: the interface-as-coordination-protocol insight, the wave pattern, and the explicit merge-point discipline. Every one of these was implicit in the first case study and load-bearing in the second. A five-method adapter interface absorbed more than seventy adapters across every protocol family in networking history without ever changing — the strongest evidence for interface-first design this playbook contains.

What the second case study stress-tested. Three rules needed qualifiers rather than rewrites: agent judgment (§1) is stronger when trade-offs are mechanical, delegating understanding (§1) is safer when the understanding lives in authoritative external specs, and the five-minute-step rule (§14) is a proxy for small blame radius that can relax when the architecture provides it for free. The first case study couldn't have surfaced any of these qualifiers because its work lives on the other end of each spectrum — social trade-offs, head-based understanding, judgment-heavy steps. Two projects, two positions on each axis, one honest set of rules.

What the second case study added. Two entirely new rules that the first case study had no way to generate: the nested-cycles rule in §5 (the second case study's nine themed releases are the clean exemplar) and explicit descoping in §14 (its v1.0.0 "Descoped Four" is the clean exemplar). Both rules were already implicit in the first case study's practice; the second case study's different shape is what forced them out into the open as explicit rules.

The practice that generated the second case study's material is the same one that generated the first's: a narrative retro at the end of every release, written in voice, with nicknamed adapters and named lessons. The Wave Pattern. The Interface That Never Needed a Sixth Method. The Docker Port Mappings That Weren't. Hand-Rolling the Legacy State Machine. The second case study's retros sit alongside the first's as the raw material for the playbook's second pass — and reading them against each other is how every field note from the second case study in this document earned its place.

Two projects, very different shapes, same practice, same rules — and this was only the second pressure-test.

Third case study — a high-velocity time-tracking web app

Partway through the second pressure-test, we brought in a third project: a time-tracking web app (React, TypeScript, Supabase, Netlify) built to support retroactive block painting rather than real-time timers. The shape is closer to the first case study than to the second — full-stack web app with a real auth surface, a real database, a real cloud deploy, a real user-facing UI — but the velocity is on a different planet. The third case study shipped nine major versions in three days, from scaffold to PWA: local foundation, week view and analytics, goals/streaks/CSV export, cloud deploy, security hardening, accessibility and keyboard shortcuts and undo/redo, TanStack Query migration plus sharing plus PWA, half-hour granularity across ~35 files, and a pure tech-debt release to pay off carried debt. Two hundred unit tests, an E2E suite, axe-core accessibility tests, Lighthouse CI, Sentry, Playwright on chromium and mobile, all running as gates.

The project has its own codified workflow document — docs/WORKFLOW.md — that independently describes the same practice this playbook describes: CLAUDE.md as single source of truth, versioned backlog with themed milestones, changelog per release, narrative retrospectives per version, git-flow, dual-deploy with backend-first ordering, quality gates with visual QA, and AI agent coordination via team spawning and file-boundary parallelism. None of this was copied from the first case study's practice; the third case study's team arrived at the same shape from first principles.

What held without modification. Every rule in the playbook that applied. The loop, retros, verification, memory, skills, trust boundaries, plan quality — the third case study ran all of them and benefited from all of them. The three-layer thesis is the most visibly true on this project: at nine-versions-in-three-days, the human cannot be doing laborer's work anywhere in the stack or the tempo collapses. The velocity is the signal that all three layers were doing their own jobs.

What the third case study added. Two contributions that weren't present in the first two projects.

The first is the v6 → v7 worktree pivot, which forced a new failure mode into §11 and a new qualifier onto §13's worktrees rule. v6 tried five parallel agents in five separate git worktrees on five separate feature branches and produced branch confusion, cross-contaminated commits, and orphaned refs that had to be recovered by hand. No agent was undisciplined. The coordination architecture had a hidden shared-git-state dimension the setup didn't anticipate. v7 pivoted to a team-in-one-worktree approach with explicit file-boundary ownership, and shipped cleanly. Same agents, same discipline, different architecture, different outcome. This is the clearest demonstration in any of the case studies of a failure that is not a discipline problem and cannot be fixed by installing more discipline — you have to change the topology of the collaboration itself. The partnership-architecture failure mode in §11 exists because of this release.

The second is the v7.0.1 and v7.0.2 hotfix pair, which sharpened §8's "evidence before assertions" rule with a new angle the playbook didn't previously name. Both hotfixes shipped within 24 hours of release despite a full green test suite — because the tests answered a different question than the humans assumed. The TanStack Query migration broke cache-hit paint because no test exercised the cache-hit path; the iPad tap failed because no test exercised a touch gesture on a real device. The unit tests were not lying. They were answering the question "does the data layer work?" when the humans were reading the green check as "does the feature work?" Those are different claims, and the distance between them is where this class of bug lives. The playbook now names this directly: the right evidence for the wrong claim is still theater.

What the third case study stress-tested. One rule stretched rather than broke. §13's subagent qualifier — "automated gates can count as reading when the domain supports it" — was written as an exception clause on the main rule. At this project's tempo it becomes the default mode, with human line-by-line review reserved for craft-sensitive code (interaction design, data migrations, auth boundaries). The rule is still correct; the relationship between the rule and its qualifier inverts at high velocity. I noted this inline rather than rewriting the rule.

Fourth case study — an audit-driven community-data web app

The fourth pressure-test was a community-data web application with admin moderation: React 18 + Vite + TypeScript + Tailwind on the frontend, edge functions in a managed serverless runtime on the backend, managed Postgres for storage, OAuth for optional user accounts, Vitest for unit tests, Playwright for integration. The shape overlaps the first and third case studies — full-stack web app with a real auth surface, a real database, real users, real moderation workflows — but the distinguishing feature is the explicit audit cadence that runs alongside feature work: a scheduled security audit pass in one release produced fifteen findings that a year of normal review cycles had walked past (lost-update races, TOCTOU on entity creation, missing UUID validation, regex injection vectors, materialized views that were never being refreshed), and a later visual audit pass walked every page of the app in both light and dark themes on both desktop and mobile, producing six UX fixes nothing else had surfaced. Neither audit was a feature release; neither was driven by a user complaint. Both came from the human deciding "I'm going to look at our work, systematically, until I see what we missed" — and both produced more value than any feature release that cycle could have shipped.

What held without modification. Same as the others — the loop, retros, verification, memory, skills, trust boundaries, plan quality. The fourth case study ran them all.

What the fourth case study added. The systematic audit as craft work — a rule now pinned explicitly in the Coda. The first three case studies all had audits in their retros, but only this project ran them as scheduled work with their own releases and their own retros, and the results made it impossible to treat auditing as a nice-to-have. Audits are now named in the playbook as a discipline the agent cannot substitute for and the pipeline cannot catch — the one irreducibly human move that the three-layer thesis is trying to free attention for.

It also sharpened the extract-when-the-pattern-stabilizes-vs-duplicates-drift discussion in §7 with the naivePlural() scar: a small utility function copy-pasted across three edge functions instead of extracted into a shared helper, one copy of which silently drifted by forgetting to handle irregular nouns, producing user-visible "1 mice" / "1 mouses" inconsistencies across code paths. Duplicates are fine when the pattern is still finding its shape; duplicates that have already drifted are a bug waiting to be reported. The fourth case study is what moved that distinction from implicit practice into an explicit clause on the rule.

Fifth case study — an epistolary journaling app with a deterministic classifier

The fifth case study is the second edition's largest new source: a one-sentence-per-day journaling PWA in which one of five historical-figure personas replies to each entry from a hand-written template corpus, routed by a deterministic keyword classifier. "No AI in the response path" is the project's load-bearing non-negotiable — which makes it a fascinating stress test for this playbook, because the product refuses the very technology that builds it. React, TypeScript, a managed Postgres backend, roughly twenty-four tagged releases and twenty narrative retros in about three months, zero to 375 tests. One human, one primary agent, with model-tier escalation for voice work (a mid-tier dispatcher, top-tier per-figure corpus dispatches) and periodic four-agent report-only audit fleets.

What the fifth case study added. More new rules than any project since the first. The whole of §10 (build the lab, read the trace, exploration-vs-production mode, suspect the runner) came from its classifier-misfire arc — the release that shipped a diagnostic surface instead of a fix, and the afternoon that closed four misfires because the lab existed. §15's claims-downstream-of-code and probe-the-gate rules came from its audit season (The Lock That Wasn't, the privacy policy that described an unpurchased backup tier). §1's agent-vocabulary rule came from its wordlists ("the wordlist reveals what the writer was thinking about, not what the user is going to write"). §16's arc-not-tag qualifier and the write-the-reversal-down norm came from its patch-release clusters and its self-correcting retro directory. §2's model-tier rule came from its corpus work. And the "things we deliberately didn't do" clause in §14 is its standing practice.

What the fifth case study stress-tested. The retro discipline itself, at high frequency and small scale — twenty retros in three months, including one for a session that produced zero code, and one the agent recommended skipping ("the boring retro") that the human insisted on and that earned its keep in one line: "The retro is boring because the work was on schedule. We should not stop writing the boring ones."

Sixth case study — a fleet of single-user instrument apps

The sixth case study is not one project but a constellation: small, sharply-scoped, single-user "instrument" apps — a once-daily rendered front page that consumes the others over versioned HTTP contracts, a daily anti-optimization health journal, a family dinner planner — each too small to generate a playbook on its own, and together generating something none of them could alone: evidence about how practice transfers between projects. One human, one agent at a time, shared platform, shared scar tissue.

What the fleet added. §6's file-your-neighbor's-scars rule — a dependency bug filed as theoretical in one repo and cashed in as a live fix in another two days later ("we imported the cure with the disease"). §4's elicitation rule — the zero-code session that caught the agent misidentifying the product's heart and proposing "a streak in a trenchcoat" as a success metric. §9's secrets-hygiene rule — one deploy that rotated a key because it had transited the transcript, and the next deploy engineered so the count of printed secrets was zero. §2 and §3's resilience clauses — the truncated-secret CLI, the _redirects precedence trap, and the recognition-on-sight payoff of cross-project memory. The fleet is also where the playbook's portability claims get tested in practice: its newest projects inherit instructions files, pipeline patterns, and retro discipline from their older siblings through the repo, not through any single harness.

Six projects, six different shapes, same practice, same rules — plus the set of sharpenings each new project forced out of the rules that already existed. If the rules hold across six independent projects with different shapes, different languages, different velocities, different team sizes, and different review cadences, the rules are not artifacts of any one project. They are the shape of the practice itself.

Companion — the DevOps playbook

This playbook has a sibling: the DevOps playbook, derived from the same first case study and the same retro practice. The two documents are explicitly paired. The DevOps playbook tells you how to make the pipeline boring — health endpoints that report real dependencies and the build SHA, blue-green deploys with automated rollback, lint/test/scan on every push, conventional commits and release-please, manifest-driven production state, Docker parity between dev and prod. Its thesis is one line: you are done when the pipeline is boring. This playbook tells you how to work inside a boring pipeline with an agent.

Read together, the two playbooks are the two halves of a single practice. The DevOps half builds the mechanics layer; the engineer-agent half works inside it. The thesis — we can create art and beauty with a computer — depends on both. Without the pipeline half, the agent becomes something you babysit and the human becomes the laborer. Without the engineer-agent half, the boring pipeline just runs empty cycles under nobody's direction. Neither playbook is self-sufficient. Both together are.

If the rules in this document feel like they're leaning on a precondition you don't have — fast CI, reliable deploys, parity between environments — go read the companion first. Build the rails. Come back. Everything here will cost less once you do.