This tool's agent reads a few markdown files as part of its setup on every session. system-prompt.md is the system prompt itself — the canonical instructions the LLM operates under. lib/agent-dispatch.md is a more specific playbook, referenced from the system prompt as "see this for the full PDF reading flow."

Both files have been on disk for many releases. Both files describe how to do things. The code that does those things has, in some cases, been rewritten since the docs were last touched.

This week's probe round extended the sweep we'd been doing for code-pattern bugs into the documentation surfaces. Two findings:

The 11th copy of the bare-VERIFY regex

Earlier releases this month fixed a regex-overshoot bug that hid every attorney task whose description started with the word "Verify." The fix landed in two binaries, then six skill files, then two reference files, then a release whose entire point was "grep for the bug expression, not the variable name." After all that, the same pattern was still in system-prompt.md line 431.

The system prompt is special among these files. It's prescriptive, not descriptive — when the model writes new task-filtering code from scratch (which it does, all the time, when answering ad-hoc requests), it copies patterns from the system prompt. So the buggy regex wasn't just being executed by the existing skills; it was being taught to the model as the canonical noise filter. Every new code path the model wrote in session was inheriting the bug.

The pattern of fixes leading up to this: 4.5.96, 4.5.113, 4.5.114, now 4.5.115. Four releases to find and patch eleven copies of the same regex. The lesson tightens further with each one: grep widely, including non-source files.

A playbook describing a retired strategy

The bigger finding in this round was lib/agent-dispatch.md. The doc described the canonical strategy for reading PDFs:

  1. Small PDFs: read with the Read tool directly.
  2. Medium PDFs (51-150 pages): spawn one sub-Agent per chunk, in parallel, then merge their JSON summaries.
  3. Large PDFs (151+ pages): two-pass — sub-Agents do a TOC scan first, then targeted deep reads.

That strategy was retired in v4.5.10. The runtime code, in lib/pdf-reader.mjs, carries this comment:

// As of v4.5.10 we no longer chunk PDFs into sub-Agent-readable
// slices. The mail flow is strictly sequential and reads PDFs in
// the main session using the Read tool's pages parameter (e.g.
// "1-20", "21-40"). No pdfseparate, no pdfunite, no chunked Agent
// dispatch.

The code change happened. The runtime started doing sequential reads. The dispatch playbook never got updated to describe the new flow. So for the past 100+ releases, the agent has been reading instructions to spawn sub-Agents and the runtime has been doing something else.

The doc even self-contradicted. Lines 7-12 said NEVER use pdftotext. Line 101 said USE pdftotext. Two different paragraphs in the same document giving opposite instructions. Neither was reflective of the current reality.

What kept this from breaking everything: the model is sophisticated enough to pick up cues from the surrounding code it's looking at. When it inspects the current lib/pdf-reader.mjs and sees the sequential-only comment, it overrides the dispatch playbook's instructions and does sequential reads. But that's the model doing the right thing despite the doc, not because of it. The agent has been carrying around three pages of obsolete instructions to ignore.

The fix

Rewrote lib/agent-dispatch.md to describe the actual current flow: get the page count, get the recommended page-range plan, call Read sequentially with the pages parameter for each range. No sub-Agents, no pdfseparate, no chunk files. Updated system-prompt.md's PDF-strategy block to match. Removed the strategy descriptions from skills/read-doc.md and skills/process-messages.md that still referenced the old playbook.

Total files updated: 4 markdown files. Code changes: zero. The bug was entirely in the documentation, but the documentation is what the agent operates from, so it was a real bug.

The general lesson

For LLM-driven tools, the instruction files are part of the codebase. They get interpreted at runtime; they get cited by the model when making decisions; they get copied into the model's working memory and can leak into the model's generated code. They need the same change-tracking discipline as the source files they describe.

The right workflow when code changes: change the code, change the comment in the code, then grep for every doc that references the old behavior. If you find them, update them. If you don't update them, the agent eventually wastes some attention sorting out the discrepancy — and occasionally follows the wrong instructions.

The dispatch-doc bug had been there for over 100 releases. The system-prompt VERIFY bug had been there since the regex was first written. Neither showed up in any test because no test exercises "did the model follow this instruction correctly?" — they exercise the code paths the instructions are supposed to drive. The disconnect was invisible from the test layer.

For codebases that depend on LLM interpretation of instruction files, the test discipline should include: at each release, re-read the agent-facing docs and verify they describe what the code now does. Cheap to do; expensive to skip.

The version on the install URL is 4.5.115.