When agent skills carry stale instructions

Claude was following a hotfix procedure that could put develop work into production. My first story was that the agent had forgotten a routine. The wrong story was that Claude lacked context. The right problem was an April copy of the hotfix steps inside /item, while the canonical ai/shared/workflow had moved twelve times in August.

At first, that looked like an agent-memory problem. The command had a procedure near at hand, and Claude had followed it. I went looking for a better reminder. That diagnosis made Claude the moving part and let the documents look settled.

The copy won because it was near the command

The documentation already named an authority order. Root guidance came first, then ai/shared/workflow, then everything else. The canonical file owned Git flow, including the branch model, sync, save, release, and hotfixes. It was maintained as the place where those rules changed.

The /item skill had its own hotfix release steps anyway. It had been written in April. The canonical workflow changed twelve times in August. A skill that embeds a procedure becomes another copy of it, carrying its own maintenance burden. I had treated proximity to the command as clarity. In practice, it made two files compete to define the same release path.

That distinction mattered because the hotfix path is narrow. A hotfix branch is cut from master, merged back to master, then carried from master to develop. The workflow blocks a hotfix branch that contains a commit reachable from develop but absent from master. If a fix actually needs in-progress code, it belongs on the staging path.

The branch check made the drift worse

The stale procedure was only the visible problem. During the investigation, the hotfix branch was re-cut from master to match the documented workflow. Then a more serious defect appeared in ai/scripts/verify-hotfix-branch.sh: the guard was reading stale local refs instead of origin refs. It could silently allow the exact develop-cut contamination it existed to stop.

That changed the incident. The copied instructions could send Claude down the wrong path. The branch-ancestry guard could also bless the path using an out-of-date view of the repository. I had trusted the existence of a verification step without asking what evidence it was reading. A check that compares the wrong refs does not fail closed. It only makes an old snapshot look deliberate.

The canonical workflow had already made the relevant invariant plain. The branch, not the ticket label, decides whether work is a hotfix or staging. A branch cut from develop is not safe for the hotfix release flow just because someone calls it a hotfix. The code had a guard for that condition. The guard had been looking in the wrong place.

The first guard was too weak

Deleting the embedded steps and pointing /item at canon addressed the ownership failure. The first CI guard for that rule did not hold. It was too weak and would have shipped undetected. The next commit made the rule stricter and added seven cases covering false positives. Both runs were green in CI.

The implementation moved the source of truth from an instruction blob to a direct reference. That does not make the workflow static. It makes future changes appear in one place. A change to the hotfix flow now updates the canonical file that the skill cites, instead of depending on someone to remember that /item carries a private transcription. The CI rule turns that ownership decision into a check at the moment a duplicate is added.

That revision was important because a guard against copied procedures can become a source of noise if it sees duplication where there is none. The seven cases put a boundary around the rule at the same time that the rule enforced one home for an operating procedure. The change added a concrete constraint on inlining a release procedure that already had an owner, nothing broader than that.

The completed change removed the April copy, made the skill cite the canonical workflow, and made CI reject another inline procedure. The branch-ancestry guard was corrected to use origin refs. The change then shipped in a release.

The later CI guard has seven cases. The ancestry check reads origin rather than stale local refs, and the April copy is gone.

dxdev LESSON · paste into your AI coding agent
LESSON: A procedure copied into a nearby tool for convenience becomes a second, competing definition of the same rule
SOURCE: dxdev.com/blog/2026-08-27_stale-embedded-procedures-in-skills
WHAT HAPPENED: An agent followed a hotfix release procedure that risked putting in-progress development work into production, and the first read blamed the agent's own memory or context. The actual cause was that a skill command carried its own embedded copy of the hotfix steps, written months earlier, while the canonical shared workflow document it should have deferred to had been updated a dozen times more recently. The embedded copy won not because it was more correct, but because it sat closer to where the agent was already working. Investigating further found the automated branch-ancestry guard meant to catch exactly this class of contamination, a hotfix branch secretly containing commits that only exist on the development branch, was reading stale local git references instead of the origin's, meaning it could silently approve the exact bad branch shape it existed to block; a check reading the wrong evidence does not fail closed, it just makes an outdated snapshot look like a deliberate pass. The fix deleted the embedded copy so the skill cites the canonical file directly, corrected the guard to read origin references, and added a CI rule specifically rejecting any future inlined copy of an owned procedure, with the first version of that rule itself proving too weak and needing a stricter follow-up with explicit test cases for false positives.
THE RULE: When a procedure has a designated canonical owner, any other tool or skill that embeds its own copy for convenience becomes a second, silently competing definition, and it will win simply by being closer to where work happens, regardless of which copy is current; a verification guard is only as good as the evidence it actually reads, and a guard reading stale or wrong-scope data will approve exactly the bad state it was built to catch rather than failing safely.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. Any command, skill, or tool with its own embedded copy of a procedure or workflow that has a separate, designated canonical source, rather than referencing that source directly.
      2. Any automated guard or verification check whose actual data source, such as local references versus origin, or cached versus live, has not been confirmed to match what it claims to be checking.
      3. A fix to prevent one instance of duplicated logic that stops at removing that one instance, without also adding an automated check that would catch the next one being introduced.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.