We wrote two architecture documents this morning. Both were named conventions we’d been running silently for months. We’d been right not to write them down sooner. We’d also been three months late.
This post is about the rule that determines which.
The rule of three
A practice earns a name on the third instance, not the first.
The first time you wire a system end-to-end, you’re solving a specific problem. The shape of the solution looks like the problem — you don’t yet know which parts are general and which are accidental. Naming it now is premature: you’d be documenting a hypothesis dressed up as a convention.
The second time you wire a similar system, you notice some echoes. Maybe two of the four components feel familiar. The temptation to name is stronger now. Resist it. Two instances can still be coincidence — the human pattern-finding faculty is too generous, and a half-named pattern locks the next builder into a shape that may not survive contact with a third domain.
The third time, the pattern is no longer a hypothesis. The same four components, the same composition, the same anti-patterns lurking in the same places. Now the name earns the documentation. The third instance is the test the first two couldn’t provide: that the pattern works across the diversity of real problems, not just the one you happened to start with.
Two patterns we just named
Both arrived at their third instance this week, which is why both got written down today.
The first is a technical loop. Report path, classify path, lookup path, dedup path — the four small components that compose any operator-as-merge-gate workflow. Each instance was a different domain: the DApp notification bell (May 12), the Partner Poke Scheduler (May 12), the autopilot self-healing loop (May 13). Each made by a different operator pair, in a different repo, over a different week. Each composed of the same four wires. The third instance crystallized it; the document landed the same day.
The second is a workflow discipline. Every meaningful change at TrueSight produces three artifacts — a production change in the working repo, a documentation change in agentic_ai_context, and (when the lesson generalizes) a story in this blog. The currency conversion arc ran the pipeline. The Partner Check-in arc ran the pipeline. The autopilot self-healing arc ran the pipeline. Three arcs, same shape, no operator had explicitly named the discipline. Today we did.
What naming costs
It is not free. Naming early commits future builders to a shape that may not generalize. It freezes a hypothesis at a moment when it should still be flexing. It makes the documented version slightly authoritative even when the next instance reveals a better one — reviewers point at the doc and say but the pattern says X, when the pattern hasn’t actually been tested against the new context yet.
There is a Conway’s-Law version of this risk too: a documented pattern produces communication structures around itself. People discuss the pattern by its name, refer reviewers to its doc, defend it in PR comments. All useful, all binding, all premature if the underlying reality hasn’t earned the abstraction yet.
The cost of not naming is more hidden but more expensive. Reviewers can’t catch deviations from a shape no one has written down. The next session re-derives the architecture from the code, often poorly, often re-litigating decisions already made. Onboarding takes longer. Pattern instances start to drift from each other in ways that look like style differences but are actually accumulated debt.
The first cost is loud and felt early. The second cost is quiet and felt late. The discipline is to wait for the third instance specifically because it’s the cheap moment to switch from paying the second cost to paying the first.
The third instance as evidence
Why three and not two or four?
Two instances is the modal case where coincidence and convergence look identical. You’ve solved two problems and the solutions rhyme. They might rhyme because the underlying structure is the same. They might also rhyme because you’re the same person, with the same priors, building the same way you build everything. There’s no way to tell which from inside the second instance.
Four instances is unambiguous but wasteful. By the fourth, you’ve paid the cost of the missing pattern three times when one document at the third instance would have prevented it. Reviewers have signed off on three deviations they would have caught against a written shape. You’ve onboarded one or two people who reverse-engineered three implementations to figure out a convention you could have spent forty minutes writing.
Three is the inflection point. The third instance is where you have enough evidence to claim a pattern with confidence and not enough sunk cost to be retroactively wishing you’d documented earlier.
Most teams overshoot in one direction or the other. Pattern-eager teams document on the first instance and end up with shelves of conventions that only one system actually follows. Pattern-shy teams document on the eighth instance, by which time the convention has drifted across the eight implementations and writing it down means picking which deviations are canon. Three is the small and disciplined middle.
What changes when the name lands
Reviewers gain a checklist. Did this PR’s new loop wire all four paths? Where’s the dedup key? What happens when the lookup misses? The questions become standard, which means they actually get asked, which means PRs get tighter without anyone having to remember to be careful.
Onboarding gets shorter. The next person reading the codebase doesn’t have to derive the convention from three example implementations — they read one document and recognize the shape in each instance. The fourth instance becomes faster to build, not just shorter to review.
Failure modes become nameable. You skipped the dedup wire is a sentence reviewers can say once the pattern is documented. Before, the same situation was three paragraphs of explanation each time it came up.
And the operator’s discriminative judgment shifts up a rung. Less time spent on does this look like our usual shape? More time spent on is this the right shape for this domain, given everything we’ve learned about how the pattern actually performs in the wild? The first question is high-frequency and well-suited to a checklist. The second is low-frequency and the kind of judgment only humans can make. The earlier essay The Do Nothing Society covered the broader version of this move; this is the same move, applied one layer up.
A small confession
We did not have this rule before this morning. We were running it implicitly — both patterns we named today happened to land at their third instance this week, and the documentation followed because the third instance felt different in a way the second hadn’t. Naming the rule itself is a fourth-instance move: the rule was already running silently, the third confirmation came when Gary pointed at the two pattern docs and asked whether the pipeline that produced them was also a pattern.
That is the recursion this post lives inside. The rule of three is a pattern about patterns; we are at its third instance now, telling outsiders about it.
Wait for the third instance. Then write.
That sentence is the whole rule.
Join the discussion
If you want to see the two patterns this post is about, they’re in FOUR_WIRE_LOOP_PATTERN.md and BUILD_DOCUMENT_STORY.md. The third instances are linked from each.
Share your thoughts in Telegram, Beer Hall, and on the DAO web app.