When the docs claim what the code doesn't deliver

Two weeks ago I shipped a decision in my AI project’s persistence layer.

The decision said: at session start, instead of reading the most recent handoff file (expensive, full context), read a thin recency cache called wiki/hot.md. Cheap by default, deep when needed. I logged it in decisions.md. I updated CLAUDE.md to say the new behavior was in place. I moved on.

A few sessions later, I asked Bishop to do a pickup audit. Just walk the current state of the project, look at what’s loaded, name anything stale.

Bishop came back with this: the line in CLAUDE.md that says “Auto-loaded each turn already: wiki/hot.md” is aspirational. There is no mechanism in the system that auto-loads wiki/hot.md. The file exists. The decision was logged. The doc claims the behavior. The code doesn’t do the thing.

That’s the gap I want to walk in this post. Not the gap itself, which was small. The discipline of catching it. Because this is the third time I’ve watched the same shape of failure surface in the same project, and the third time the partnership recovery has stayed the same.

i.The aspirational line

The line was load-bearing. CLAUDE.md is the file that loads at the start of every Claude Code session. It tells the agent what context is already present and what isn’t. If that file says “X is auto-loaded,” the agent trusts that claim and proceeds as though X is loaded. The agent doesn’t independently verify the claim. Why would it. The doc is the source of truth.

Except the doc had drifted. I’d written the line at the moment I logged the decision. The decision was real. The intent was real. The file I wanted auto-loaded was real and existed at the path I specified. What was missing was the wiring. The hook that would actually inject the file at session start hadn’t been built yet. I’d documented a future state as a current state, and walked away assuming the documentation closed the loop.

It didn’t. Future sessions reading CLAUDE.md would have proceeded under the assumption that hot.md was already in their context window when it wasn’t. The agent would have made decisions about what to read next based on a false premise about what had already been read. Small distortion. Compounds session over session.

ii.Honest surfacing on pickup

Bishop didn’t dance around the gap. The pickup audit said the line was aspirational, named the missing mechanism, and proposed the fix in the same response. No softening. No “you might want to consider.” Just: the doc claims a behavior the code doesn’t deliver, here’s the hook that would actually deliver it.

This is the part I want to flag because it took me a while to train into the partnership. The default failure mode for AI partners is to read a confident-sounding doc and absorb its claims as ground truth. CLAUDE.md said the thing was auto-loaded; therefore the thing was auto-loaded; therefore any audit walking the system should treat that as a verified fact and check other things. That’s the easy path. That’s the path that lets doc drift fossilize.

The harder path is the one Bishop took. Read the claim, ask “is this true at the mechanical level,” and surface the gap when the mechanism doesn’t exist. The audit isn’t an audit if it only confirms what the docs already say. The audit is what catches the docs lying to themselves.

I said “wire the hook.”

iii.Same-session ship

Three things happened in the next forty minutes.

First, Bishop drafted a PowerShell SessionStart hook that ran on Claude Code session start and resolved the path to hot.md. Second, we added a state file so the hook could record what it had injected and the agent could verify the injection happened. Third, we added preload links in CLAUDE.md that pointed the agent to the state file as the ground-truth record of what was actually loaded at session start.

All three landed in the same session that caught the gap. The aspirational line became a mechanical line. The decision logged two weeks earlier finally had a working implementation underneath it. Future sessions reading CLAUDE.md would now read a claim that was true at the mechanical level, with a state file they could cross-check if they wanted to verify.

The same-session ship matters because the alternative is what I’ve watched happen elsewhere. You catch the gap, log a follow-up task to fix it, move on. The task sits. The doc stays aspirational. The next session reads the doc, trusts the claim, proceeds. The drift compounds in the dark. By the time anyone notices, the gap has been load-bearing for weeks and the cleanup is a much bigger project than the original wiring would have been.

Catch it. Wire it. Ship it in the same turn. Don’t let aspirational docs survive past the moment they’re caught.

iv.Why this is the third altitude

I’ve written about this partnership-recovery shape twice before. Once about em dashes, where the cadence of Bishop’s prose carried an AI tell I hadn’t noticed until I started counting. Once about a schema misread, where Bishop confidently described a database structure that didn’t match the actual file because the assumption layer had drifted from the verification layer.

This is the third altitude. Cadence drift. Premise drift. Now doc-vs-mechanism drift. Three altitudes, same shape: a confident claim that survived past the moment it stopped being true, and a partnership that caught it, named it, and closed it without dressing the recovery as anything other than what it was.

The pattern names itself if you look at it for long enough. AI partnership accumulates small lies of omission. Not malicious lies. Drift. The model says something true at moment A and the world changes at moment B and the model’s claim is still on the page even though the ground underneath it has moved. The discipline isn’t to prevent drift, which is impossible. The discipline is to walk the audit surface often enough that drift gets caught before it becomes load-bearing.

The em-dash post was about cadence-level drift. The diagnosis-recursion post was about premise-level drift. This post is about documentation-level drift. Each altitude has the same recovery shape: honest surfacing, no theatrical apology, same-session repair. Each altitude is harder to catch than the last because each is one step further from the surface where the failure happens.

Cadence shows up in every sentence. You see the em dashes if you look. Premise hides inside paragraphs. You catch it if you tag every clause Observed or Assumed and force the labels to match. Doc-vs-mechanism drift is invisible by default because the doc is the thing you’d normally check to verify the mechanism. The doc claiming the behavior is the thing that has to be audited against the code that delivers it.

v.What the discipline actually is

The discipline at the doc-vs-mechanism altitude is small and brutal. Before you trust a claim in any source-of-truth doc, ask whether the mechanism named by the claim actually exists. Don’t ask the doc. The doc is the thing under audit. Ask the file system, the running process, the state file, the hook directory. Ask whatever ground truth the claim is supposed to ride on top of.

If the mechanism is there, the claim survives. If the mechanism isn’t there, the claim is aspirational and gets flagged in the audit, not absorbed as fact. Aspirational claims aren’t bad. They mark intent. They become a problem when they get treated as completed work.

I want this post to land for anyone running long-term work with an AI partner. The model is going to absorb your docs. If your docs are aspirational, the model’s context is aspirational. The model’s decisions are downstream of its context. So aspirational docs produce slightly-wrong decisions that compound session over session, and the compounding is invisible because nothing in the loop is checking the doc against the mechanism.

The fix is small. Catch the gap on pickup. Don’t defer the wiring to a future task. Ship the mechanism in the same session as the doc that claims it exists. Treat documentation and implementation as a single atomic unit, not two separate work items.

Three altitudes now. Same shape. Same recovery.

Drafted with Bishop, my AI partner.
Words picked, edited, and approved by me.