One Domain, Done Properly — and the Bugs Three Reviewers Caught

I built verified, concept-first knowledge for the most dangerous corner of the system by not reading it myself. Then the review loop found two errors that would have killed the whole mechanism.

Part 2 of 10 — Teaching a Coding Agent the Parts of a System It Keeps Getting Wrong.

*Part 1 framed the problem: the load-bearing knowledge an agent can’t see.*

In Part 1 I set the constraints: documentation written for a coding agent has to stay true as the code moves, cost nothing when it’s irrelevant, and surface exactly when it is relevant. Three properties, all of them in tension. The fastest way to find out whether an idea like that actually holds is to aim it straight at the worst case — so that’s where I started.

Picking the hard corner on purpose

I deliberately chose the most operationally central, invariant-dense corner of the system as the pilot: the scheduling-and-visits domain. It owns reusable activity templates, scheduled visits, the jobs generated from them, sign-off with counter-signatures, the recommendations for what to schedule next, and the integration with the rules engine that decides what work is even required in the first place.

That single domain reaches into authorization, billing entitlements, a background rules engine, a notification system, calendar export, and both a web and a mobile client. The reasoning was simple: if the approach could survive here, it could survive anywhere else in the system.

How I built it: fan out, don’t read

I didn’t read the subsystem front to back myself. Instead I fanned out ten read-only exploration agents in parallel, each scoped to a single slice and each under explicit instruction to cite file:line for every claim and to report only what the code actually says. One agent mapped the data model — tables, columns, relationships, the status enums. Another traced the bundle lifecycle: the visit state machine and every transition. A third followed the job state machine, learning how jobs are generated, scoped, completed, and skipped. The rest took the recommendation algorithm, the rules-engine integration, the permission middleware, calendar export, notifications, the web client, and the mobile client's offline-and-sync surface — one slice each, no overlap.

$ dispatch 10 read-only explorers over the scheduling domain   (in parallel)
  ✓ data-model         → findings cited file:line
  ✓ bundle-lifecycle   → visit state machine: DRAFT → SCHEDULED → IN_PROGRESS → …
  ✓ job-state-machine  → one job per control-schema scope, generated in a transaction
  ✓ recommendations    → what the system proposes next, and the frequency rule
  ✓ rules-integration  → synchronous RPC path vs. async queue path
  ✓ permissions        → the auth + entitlement chain per route
  ✓ calendar-export    → one-time-token model, public vs. authed split
  ✓ notifications      → which events fire on which transitions
  ✓ web-client         → how the front end consumes the contracts
  ✓ mobile-client      → the offline / sync surface
  wall-clock: ~2 min · only conclusions returned to the orchestrator — not file bodies

The parallelism mattered for two reasons. The first is obvious — the whole sweep finished in a couple of minutes of wall-clock time instead of an afternoon of sequential reading. The second is the one that makes the entire project work: because each agent returned only its conclusions, never the file contents, my own working context stayed lean. I was spending a junior army’s worth of reading to produce a senior’s worth of summary, without ever paying the summary’s cost in my own context window.

With the findings in hand, I synthesized them into a small set of skills — every claim carrying a cited path back to the code it came from.

The review loop earned its keep on the first pass

I opened the work as a pull request, and three independent automated reviewers went at it. They caught two things immediately, and both are worth dwelling on, because they are exactly the failure modes this whole project exists to prevent.

The triggering bug. Every file path I’d written carried a leading directory prefix that doesn’t actually exist in this repository’s layout. On its face that looks harmless — a cosmetic slip. It isn’t. Claude Code decides whether to load a skill by matching the skill’s description text, and a description pointing at a non-existent path would simply never trigger. The documentation was correct in its content; the prefix was a plausible-looking lie that only a layout check would ever expose.

The dead-column error. I had described a pair of database columns as “written by no code path — future work.” A reviewer pointed straight at the background-Worker line that writes them today, and at the report assembler that reads them. I had reproduced, in my very first batch of docs, precisely the kind of confident-but-wrong tribal claim I was trying to eliminate.

Sit with the first one for a second. The documentation would have been correct in content and dead on arrival in practice — every fact right, and the skill would never once load, because its description pointed into a directory that isn’t there. No test catches that. No human skim catches that. It is the kind of error that ships green and then silently does nothing at all for a year.

And the second one is the project’s own thesis turned against its author. I set out to kill confidently-wrong tribal knowledge, and in my first batch of docs I wrote a confidently-wrong tribal claim — that two live columns were dead. A reviewer with the diff in front of it pointed at the writing code path in seconds.

The principle that fell out

The doc-builder needs adversarial verification as much as the code does.

I now treat the AI reviewers as a standing, free verification layer: if a skill contradicts the code, and the relevant diff is in the pull request, they will usually catch it. That single observation later became load-bearing in the self-update design — because a verification layer you already run on every pull request is a verification layer you don’t have to build twice.

The pilot shipped as eleven skills. It was correct, it was verified, and it was — I realized almost immediately — built on a pattern that would detonate the moment I tried to scale it.

The takeaway

You can produce genuinely trustworthy domain documentation with a parallel swarm of read-only agents — but only if every claim is verified against source, and only if you let an adversarial reviewer try to break it. The swarm makes the reading cheap; the review makes the writing honest. Skip either one and what you’ve built is a fast wiki of plausible lies.

But “eleven skills, verified” is a sentence with a time bomb ticking inside it. The bomb is arithmetic.

Next in the series — Part 3: “The Arithmetic That Reframed Everything.” Eleven skills for one domain worked fine. Then I multiplied by ten domains and watched the design collapse under a tax I hadn’t counted — and found the one-line pattern that fixed it. Have a look...