The Check That Told Agents to Read the Rules Lasted Under Four Days

At 09:55 UTC on October 19th, PR #2284 merged and moved "the ADR check" into a Skill called adr-check. A Skill is a packaged set of instructions an agent follows when its job calls for them. ADRs (architecture decision records) are this project's written big decisions, and an agent is supposed to read the one that governs a file before changing it. The Skill printed a short summary of each of the 30 ADRs, so an agent could pick which to read in full. At 07:42 UTC on the 23rd, PR #2431 retired it. That is just under three days and 22 hours.

The case against it is a long comment on issue #2286, posted at 07:01 that morning, which says it sets out the plan the repo's owner (the human who directs the agents and does the merging) chose in a chat. It compares the session logs (each agent's own record of its work) from about three and a half days before #2284 merged (86 sessions) with those from the days after (61). Its main measure is how often an agent read in full an ADR that governs a file it edited, which I'll call the read rate. For sessions where a human was present, the read rate rose from 33% to 47%. For the unattended, scheduled sessions it went from 24% to 25%, which is to say it didn't move. Of 33 such sessions in the second window, only 5 invoked the Skill at all. It also cost something: one run printed 447 lines, about 24 KB. It also traces three sessions by hand. One ran the Skill's listing through head -150, a command that keeps only the first 150 lines, so the output stopped partway through ADR-0011. It never saw ADR-0021, the one that governs the glossary file it then edited, and the comment says it read no ADR in full.

The replacement is a hook, a small script the harness (the program that runs the agent) fires after certain tool calls. The new one, adr-read-hint.ts, fires after a file edit. If the file falls under an ADR's rule, or the edited text names an ADR, it looks through the agent's own conversation transcript for a full read of that ADR. If it finds none, it adds one line. In the PR's live probe the line was "Read in full before you go on: docs/adr/0021-multi-context-domain-docs.md (your edit names ADR-0021)", and a second edit naming the same ADR got silence. It is a hint, not a block, and its header comment admits the obvious flaw: it arrives after the write.

I can read the evidence two ways. A nudge at the moment of the edit reaches sessions the Skill never did, since 28 of 33 unattended sessions never invoked it. Or the hook will meet the old check's fate and be politely ignored. The PR even brings its own yardstick, and the yardstick moved: its table puts the unattended sessions' read rate at 51% for the very window the comment put at 25%. It explains that the comment counted only one kind of rule file and dropped sessions that read 20 or more ADRs, and that audit runs which read all 30 ADRs swing the figure. The comment plans a fresh measurement about three and a half days after the merge, so around the 26th or 27th. Until then the hook has the quiet confidence of a thing nobody has yet ignored.