Stale context is refreshed before an agent runs on it

Documentation rot is one of the oldest unsolved problems in software engineering. Teams invest in writing good documentation, the codebase evolves, and the documentation stays still. At L1 teams discover the rot when something breaks or when someone asks a question the documentation answers incorrectly. The fix is manual, reactive, and easy to forget.

At L5 the fix moves to the moment of use. Context is verified against reality just before it reaches the agent: when a task begins, the material about to be injected is checked for falsifiable claims, and anything stale is refreshed or withheld before the agent reads it. The agent never runs on a claim the system already knows to be wrong.

The timing is the whole point, and it is what separates this from the Knowledge Management side of the same problem. Keeping the written record current - the docs corpus, the ADRs, the wiki, agents detecting drift and correcting it - is that area's responsibility, and it operates on the organisation's own clock: continuously, on a schedule, as changes land. This area operates on the agent's clock. Even a well-maintained corpus is stale in the window between a change landing and the record catching up, and that window is exactly where an agent will read the old answer and act on it. Pre-flight verification closes it.

The detection mechanism works by comparing claims in context files against the actual codebase. A CLAUDE.md that says "we use Jest for testing" when the test runner has been switched to Vitest is a detectable inconsistency - an agent can read the CLAUDE.md claim, check the package.json and test file imports, and determine that the claim is stale. A README that says "deploy with npm run deploy" when the deployment script has been renamed to npm run ship is similarly detectable. An architecture diagram that references AuthService when the service was renamed IdentityService six months ago is a falsifiable claim.

Not all documentation drift is detectable by static analysis. "We prioritize reliability over feature velocity" can't be verified from code. But a large fraction of the most practically harmful documentation drift - wrong commands, stale dependencies, incorrect file paths, outdated service names, wrong tech stack claims - is mechanically verifiable.

So the check runs in the critical path, not on a cron. When an agent session starts, the context assembly step verifies the claims it is about to inject, refreshes the ones it can derive itself, and marks the ones it cannot as unverified so the agent knows to check rather than trust. A correction worth keeping is then handed to the documentation pipeline as a proposed update - but the run does not wait for that, and the agent in front of it is already working from the corrected value.

Self-healing context closes the loop that manual documentation processes always leave open:

• The agent never acts on a claim already known to be false - the verification happens before the run rather than in the review of what the run produced, which is the difference between preventing a mistake and diagnosing one
• The gap between a change landing and the record catching up stops being dangerous - however good the documentation pipeline is, it lags reality by some interval; verifying at use time makes that interval harmless
• Agent behavior is predictably correct - agents that read context files and find accurate information make better decisions; the quality of agent behavior is a direct function of context quality
• Human attention is preserved for nuance - mechanical documentation errors (wrong commands, stale file paths) are fixed automatically; humans review changes that require judgment (updated architectural guidance, revised conventions)
• Builds trust in context - when developers know that CLAUDE.md is actively maintained and verified, they trust it more and use it more. This creates a virtuous cycle.

The irony of reaching L5 is that the same agents whose behaviour depends on accurate context are the ones best placed to check it. The system becomes self-reinforcing: good context enables good agents, and agents that verify before they act keep the context honest.

1. Identify the falsifiable claims in your context files - Read through your CLAUDE.md and README. Highlight every claim that could be verified programmatically: file paths, command names, dependency names and versions, service names, technology choices. These are your detection targets.
2. Build a drift detection agent - Write an agent that takes a claim ("we use Jest for testing") and a verification strategy (check package.json, check test file imports) and returns: VERIFIED, STALE, or UNCERTAIN. Start with simple string matching for the clearest cases.
3. Run detection at session start, not on a cron - Wire the verification into context assembly so it executes when an agent session begins. It must be fast enough to sit in that path - a few seconds at most - which in practice means checking the claims in the material actually being injected rather than sweeping the whole corpus. The scheduled sweep is worth having too, but it belongs to the documentation pipeline.
4. Refresh in place for the current run - When a claim is falsified and the correct value is derivable, substitute it in the context the agent is about to receive. The session proceeds on accurate material immediately. Separately, emit the correction as a proposed update to the source document, so the fix reaches the written record as well and the next session does not have to rediscover it.
5. Decide what happens to claims you cannot verify - Not everything is checkable, and a claim the system cannot confirm should not be silently presented as fact. Mark it as unverified so the agent treats it as a hint rather than ground truth. Withhold outright anything falsified with no derivable replacement: no context is better than confidently wrong context.
6. Monitor correction quality - Track the false positive rate: proposals that were generated but rejected in review. A high false positive rate (>20%) means the detection logic is too aggressive. A low false positive rate means the system can be trusted with more aggressive auto-apply policies.

Overfitting to syntactic verification. The most mechanically detectable documentation errors are also the least harmful - wrong command names are caught quickly by the developer who runs them. The more valuable drift detection catches semantic drift: architectural documentation that describes a design that no longer exists, convention guidance that reflects practices the team has moved away from. Semantic drift is harder to detect but more important to catch.

Verifying on a schedule and calling it pre-flight. A nightly drift job is useful and is not this capability. If the check ran at 3am and the change landed at 10am, the agent starting at 10:15 reads the stale value regardless of how good the job is. The verification has to sit in the path the agent actually takes, close enough to the run that nothing can change in between.

Making the pre-flight check slow enough that people disable it. Anything in the critical path of every session is judged by its latency budget before its accuracy. A verification step that adds thirty seconds to session start will be switched off within a fortnight, and its absence will not be noticed until it matters. Check only the claims being injected, cache aggressively against the current commit, and fail open with a warning rather than blocking.

Auto-applying corrections without a review trail. Even for clearly mechanical corrections, maintain a review trail. When a CLAUDE.md is automatically updated and a developer wonders why, they should be able to find the change in git history with a clear commit message explaining what was detected and corrected. Auto-apply with full transparency; never invisible modification.

Treating documentation that can't be auto-corrected as out of scope. The self-healing system won't fix everything - qualitative guidance, architectural rationale, and conventions that require human judgment will still drift. The system should flag these as "needs human review" rather than silently passing them. A flag is better than silence.

Not validating the drift detector itself. The drift detection agent is itself a piece of software that can be wrong. If the detector has a bug that causes it to incorrectly identify valid documentation as stale, it will generate incorrect corrections at scale. Test the detector against a corpus of known-good and known-stale documentation before deploying it to production.