29 Surfaces, No System — The Night the Documentation Rebuild Started

The session opened with what looked like a small mechanical question. A configuration rule in CLAUDE.md — the project’s operating contract — had been silently broken for two days. Documentation commits pushed through the rule’s prescribed path were no longer triggering deployment. The trigger had been retargeted in an earlier architectural change, and the rule’s text never got updated.

Routine drift. The kind every project accumulates. Fix the rule, move on.

I almost did.

What stopped me was a smaller question on the way to fixing it: why did this take three commits, a session log, and a diagnosis document just to reconstruct what the rule was originally for?

That question opened a different one underneath it.

What the read-only investigation surfaced

Two read-only passes, no edits. First, the rule’s own history — eight commits across two months, three of them retargeting the deploy trigger without touching the rule’s prescribed path. Second, every documentation surface in the repo, mapped and counted.

The findings landed sharper than expected.

• 29 documentation surfaces across the repository
• 188 markdown files, 2.0 MB of prose
• Three competing homes for architectural decisions — none of them current
• One architectural decision (AD-031) filed in two paths simultaneously
• Two recent decisions (AD-037, AD-038) filed in no recognisable home at all
• 11 abandoned or orphan files, including 75 auto-generated release notes from a retired build flow
• Four surfaces describing the deploy mechanism, with internal contradictions across all four
• Roughly twelve module reference docs frozen at repository-seed timestamp while the underlying code shipped continuously

The archaeology cost was load-bearing in its own right:

• “Where is AD-037 documented?” → 4 files, no index
• “What is the current deploy mechanism?” → 4–7 files, mutually contradicting
• “What was the broken rule originally solving?” → 6 files

Three documentation drift incidents in 48 hours had each required this kind of archaeology to resolve. The Documentation Push Rule was not a one-off bug. It was symptomatic.

The diagnosis underneath the rule: every new architectural decision picked a new home depending on what was easiest that day, and no surface was authoritative for any single information type.

The reframe

The session pivoted from “fix the rule” to “we do not have a documentation system.”

That is a different problem with a different cure. Fixing the rule reproduces the same drift in a tidier location. Building a documentation system attacks the failure mode itself.

Tidying without verifying just relocates the archaeology.

What public consensus said

Before listing alternatives, I ran three searches across ten authoritative sources — Martin Fowler, AWS Prescriptive Guidance, Microsoft Azure Well-Architected, Cognitect (Nygard 2011), Code Soapbox, joelparkerhenderson, Architect View Master, Backstage.io, gov.uk Architectural Decision Record Framework, TechTarget.

The pattern came back unambiguous:

• One canonical home per information type. Define a piece of information once. Link from elsewhere.
• Architectural Decision Records as flat, numbered, append-only files in a single directory.
• Numbering is monotonic. Numbers are never reused. Numbers are never reset, even when adopting the discipline mid-project.
• Brownfield projects retroactively file ADRs for past decisions where the data is available.
• README inside the ADR directory as the canonical index.
• Verify documentation against code before consolidating. Tidying without verifying reproduces drift in nicer locations.

None of this was creative. The pattern Axia needed has been settled doctrine since 2011. The work was catching up to public consensus, not designing something new.

This matters more than it sounds. There is a failure mode in operator-AI work where the AI defaults to producing decision trees on questions where consensus already exists. It is a noisy failure mode — it looks like rigour, but it bypasses the cheaper move of reading the literature first. Three times in the session, that failure mode fired before I caught it. Each time, the cost of catching it was about five minutes of search. The cost of not catching it would have been a parallel system designed in isolation from the doctrine.

A new rule got drafted into CLAUDE.md, scheduled for the next stage: before listing alternatives or presenting a decision tree on a structural or conventional question, search public domain first. Only present options when public consensus genuinely diverges, or our constraints make consensus inapplicable. If consensus exists and applies, state it directly.

What shipped that night

Two commits to origin/main, both deploy workflows fired and verified on both VPSes.

Commit 1 — Housekeeping (79fb386):

• Documentation Push Rule retired and replaced with a “Deploy Mechanism” section reflecting current single-trunk reality
• Aliases repointed to the actual deploy target
• Two stale READY briefs marked DONE (drift cleanup)
• One incomplete architectural change from earlier in the week (AD-037 Stage 4) closed retroactively, with explicit notes on what was missed at the original close

Commit 2 — META-DOC-CONSOLIDATION-001 (a65d330):

A 7-stage brief filed at READY status, gating all build queue work and all Phase 3 work. Stages cover: ADR template, retroactive filing for the four currently-homeless decisions, full verification pass on every kept surface (every claim cross-checked against code), architecture description migration to a canonical docs/architecture.md, archive of abandoned surfaces, README rewrite as orientation-only, CONTRIBUTING.md, glossary.

Commit 3 — Session log close (5f940d1):

The session itself captured with full design discussion, decisions, and methodology lessons. Next-session pickup point made explicit so the work is recoverable from a cold start.

The two lessons that came out of the night

The first one is the prior-art search rule above. That is now a CLAUDE.md commit waiting to land.

The second one is structural and worth stating directly.

The Scaffold methodology is built on human-in-at-decisions, AI-in-at-execution. Tonight surfaced the sharper version of what that actually means in practice.

The AI defaults to producing. The operator’s value at decision points is not approving the production. It is questioning whether the production is grounded.

Four pivot moments in the session each came from operator doubt, not operator approval:

• Ask the codebase rather than infer from memory.
• Check public consensus instead of constructing alternatives.
• Reframe the problem from a single rule to the whole system.
• Demand verification as load-bearing rather than as a footnote.

Without those four moments, the session produces a tidier-looking version of the same drift. Same 29 surfaces, more aesthetic foldering, same archaeology cost compounding underneath.

The line that makes Scaffold defensible against “couldn’t an AI just do all of this on its own” — the line worth saying out loud — is this. No. An AI alone produces 29 surfaces and calls it a system. The operator’s job is the doubt that catches it.

What this changes going forward

The next two weeks are tightening, not building. Phase 3 work — content generation, video integration, more API surfaces — waits until the documentation system can absorb new modules into known canonical homes. The bet is to pay the verification cost now, while the corpus is at 188 files and a hundred-ish commits, rather than after Phase 3 multiplies both.

The compounding factor is real. Every new module shipping into an untrusted documentation system carries the eventual verification cost forward, plus interest. Velocity-without-tightening creates bigger debt.

The instinct that drove the reframe is the same instinct public consensus has been articulating for fifteen years: documentation discipline is a velocity governor, and projects that defer it pay it back later in compounded archaeology.

Why this is on the public log

Most build narratives that get published online are about wins. Shipped a feature. Hit a milestone. Cleaned up a deploy.

This one is the opposite shape. The starting position was a system that looked like it was working until I checked, and the discovery underneath was a structural drift the surface had been hiding for weeks. The post-condition is one stage of a seven-stage brief at READY — not a fix, a foundation.

We publish the operator’s log because the system V8 sells is exactly this kind of work running on the client’s operations. Cadence when things go right, recovery when they go wrong, and — sometimes — a hard stop and a rebuild when the system you thought you had turns out to be 29 separate things pretending to be one.

For the build conversation about your specific operations, Scaffold is the engagement.

---

Alan Law is founder of V8 Global and architect of Axia. Operator’s Log posts document how AI-native systems get built — and operated — in practice. The blog you are reading is one of the systems doing it.