Why verify-hotfix-branch.sh Passed a Branch Cut From develop

Claude was following a hotfix procedure that could put develop work into production. The procedure was an April copy of the hotfix steps inside /item, and the canonical ai/shared/workflow had moved twelve times in August.

Our first story was wrong

We first read it as an agent-memory problem. That diagnosis made Claude the moving part and let the documents look settled. It was the wrong frame. The command had a procedure near at hand, and Claude had followed it.

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. A skill that embeds a procedure becomes another copy of it, with its own maintenance burden. We had treated proximity to the command as clarity. In practice, two files were competing to define the same release path.

That 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 was reading the wrong refs

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, so 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 ancestry guard could also bless that path using an out-of-date view of the repository. We had trusted that a verification step existed without asking what evidence it was reading. A check that compares the wrong refs gives a green result against an old snapshot, and the result looks deliberate.

The canonical workflow had already made the invariant plain. The branch, not the ticket label, decides whether work is a hotfix or staging. A branch cut from develop is unsafe for the hotfix release flow no matter what anyone calls it. The code had a guard for that condition, and the guard had been looking in the wrong place.

The first CI 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.

Those seven cases matter because a guard against copied procedures turns into noise if it sees duplication where there is none. They put a boundary around the rule, which now covers one thing: inlining a release procedure that already has an owner.

The completed change removed the April copy, made the skill cite the canonical workflow, and made CI reject another inline procedure. A change to the hotfix flow now lands in the one file the skill cites, and nobody has to remember that /item carries a private transcription. The branch-ancestry guard was corrected to read origin refs, and the change shipped in a release.

When an agent follows a procedure, find where that procedure lives and whether a second copy exists. Then check what each safety check actually reads.

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/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.