The third article through the DVLAW gate read enriched compared to what the process documentation described. I noticed. Asked: “have we changed the method?” The honest audit found two drifts: triage had become a gate step, and variant count had become part of the decision. Neither had made it into the docs. The fix that session: update the gate docs to match practice.
That is treating the symptom.
The same pattern has appeared three times in the captainrandom repo. Work accumulates without a home. The documentation doesn’t follow. Then something surfaces the gap (a question, a review, a feature that needs to reference work never formally captured). The fix, each time, is the same: give the work a folder with a PRD, a roadmap entry, and a devlog trail.
What drift looks like
It doesn’t arrive as a gap you can see. It arrives as confusion.
In May, the DVLAW gate had two undocumented steps. The process doc said N steps; actual practice was N+2. Nobody changed the doc. The extra steps accreted across sessions, each time feeling like a small adjustment, never like a protocol change. When I compared the documented gate against what the third article actually passed through, the diff was obvious. Until I looked, it wasn’t.
In June, the /learning/ page work had accumulated across sessions without a home. No PRD. No roadmap phase. Brainstorms scattered across wherever they’d been written down. Three problems surfaced when I asked for the work to be properly documented: the roadmap had been silently lost at some point in the session, the brainstorms had no canonical location, and no single document described what the work was supposed to accomplish.
Neither looked like documentation failure while the work was happening. Both looked like documentation failure immediately once I tried to point at the canonical record.
Why scattered notes don’t hold
A note in a session can describe what changed. It can’t tell the next session what was intended. A comment in a commit describes the diff; it doesn’t carry the reasoning. A brainstorm in the wrong directory gets lost when the directory it sits in doesn’t have a reason to exist.
Scattered notes work at the scale of one session. They fail across sessions, especially when the work is iterative, where each session adds a step to a process, extends a feature, or refines a decision. The trail becomes unreliable precisely when you most need it.
The enclosure pattern
Three occurrences, same fix.
May 2026, devlog creation. docs/devlog.md spun up to mirror the BBBrain convention. The global hook at ~/.claude/hooks/agent-audit-preflight.py already exempted the devlog path, so creating the file made the exemption meaningful. Format is append-only: one entry per feat: or fix: commit, one paragraph describing what changed and why.
May 2026, DVLAW gate docs. Drift A and Drift B identified, written back into the process document. The gate became six documented steps; variant-count guidance was added. The fix was a session’s work. The lesson was that the gate docs needed a home that wasn’t a session.
June 2026, learning hub PRD enclosure. docs/specs/learning-hub/ created. PRD written. Roadmap Phase 11 added. Brainstorms refiled into the new directory rather than left wherever they’d landed. Three problems resolved by creating a folder and establishing it as the canonical location before continuing the work: lost roadmap, scattered brainstorms, no spec.
In each case, the enclosure takes the same shape: a folder, a PRD describing intent, a roadmap entry naming the phase, a devlog trail tracking changes. The folder makes the work addressable; the PRD makes intent legible. The roadmap entry makes the commitment explicit, and the devlog makes the history auditable.
The infrastructure that enables it
The roadmap rollout in May (Wave 4a, bringing docs/roadmap.md to captainrandom after BBBrain PR #119 established the convention) wasn’t about documentation for its own sake. It laid the surface that makes drift detectable later. Without a roadmap file, there’s no place to put a Phase 11; without a Phase 11, there’s no signal that /learning/ work is formally tracked. The devlog created in May serves the same function: without the file, the pre-commit hook exemption has nothing to target, and the convention doesn’t take hold.
Structure before work isn’t bureaucracy. It’s the scaffolding that makes drift visible when it happens, rather than only after it compounds.
Why this works
The folder creates a contract with itself. When the process changes, there’s one document to update and one location to find it. When a roadmap phase advances, there’s one entry to tick. When a later session asks what /learning/ was supposed to accomplish, there is one place to look.
Scattered notes don’t create that contract. They create a search problem. The folder eliminates the search problem by making the location part of the structure rather than part of memory.
There is a cost. Creating the folder before starting the work adds friction at the start of a sprint, and writing the PRD before the first commit takes time. That friction is the point: it forces the question of what this work formally is. If I can’t answer that in two paragraphs, the work is underspecified. The enclosure surfaces the underspecification early, when it is cheap to resolve.
What I’d do differently
Start with the folder, not the work.
The /learning/ drift happened because the work started before the documentation structure existed. DVLAW gate drift followed for a different reason: the process evolved without a designated home for process documentation. Both ended up in the same sequence: work first, structure second, reconciliation third. The reconciliation is expensive relative to starting with structure.
The sequence that avoids the drift:
- Name the work. One sentence. If I can’t name it, I don’t start.
- Create the folder.
docs/specs/<feature>/. - Write the PRD. Two paragraphs: what this is, what done looks like.
- Add the roadmap entry. Phase number, short title.
- Start the work. Every session appends to the devlog.
Five steps before the first commit. The work that skips these steps isn’t faster; it’s deferring the reconciliation cost to a later session, when there is more to reconcile.
The check
If a feature or process in the repo cannot be located via a roadmap phase entry naming it, a PRD describing it, and a devlog trail tracking changes to it, the enclosure is missing.
That doesn’t mean the work didn’t happen. It means the next session starts a search problem rather than a continuation. The three occurrences above each resolved by creating the missing structure. The goal now is to not reach three.
