I had hotfix-ITEM-6738-messaging-visibility open, a customer was waiting on a text-delivery fix, and git stopped me on .claude/skills/item/SKILL.md.
Not on a source file. Not on a database migration. On the prompt file that tells Claude how to run a ticket session.
My first reaction was mild irritation. Merge conflicts on prose files feel bureaucratic, not dangerous. I thought: this is just instructions, I’ll read the diff, pick the version that makes sense, move on. That was wrong. I was treating a policy file as soft configuration.
what the /item skill actually does
The /item skill at .claude/skills/item/SKILL.md is how I open a work session on any HTO ticket. I type /item ITEM-6738, and the skill drives everything that follows. It resolves the ticket, decides whether to cut a hotfix/ branch or a feature/ branch based on issue type and severity, claims the repo lock, fires the JIRA transition from preparing to CODING, posts a session-intent comment to the ticket, and pins the clone so no other session stomps on it mid-work.
That list matters. It is not a checklist I run manually. Claude reads the skill and executes it. The skill is the branching policy. The skill is the JIRA state machine. If the skill says to cut a hotfix branch, a hotfix branch gets cut. If the skill says to post a comment, a comment goes up. If the skill’s logic for customer-type tickets is wrong, every customer-type ticket session misbehaves until someone edits the file.
I had thought of it as a prompt I could refine freely. By April 3rd, three tickets in one day taught me otherwise.
what changed that day
ITEM-6738 was the text-delivery investigation. Customers were reporting unreceived texts. The session produced a new diagnostic page in the admin panel, and a set of JIRA transitions through the hotfix flow. Somewhere in that session I updated the skill to handle customer-type ticket priority correctly. The existing logic was ambiguous about how to sequence a customer-type issue through JIRA versus a standard staging ticket.
ITEM-6739 came next: tournament org structure. The session produced a second diagnostic page in the admin panel. To work that ticket cleanly, I needed the skill to be smarter about role disambiguation, specifically how it handles tickets that sit at the intersection of multiple JIRA components. I edited the skill again.
ITEM-6744 was a docs-viewer root-path fix. Smaller in scope but it exposed something in the branch-creation step. The skill had been cutting branches immediately at session open. The fix for a particular edge case was to defer branch creation until the first edit was actually imminent, after a fetch and sync step confirmed the clone was at the right base commit.
Three edits, three tickets, one day. Each edit felt like a local patch to address the ticket at hand. And then I tried to merge hotfix-ITEM-6738-messaging-visibility back, and git showed me that the skill file had diverged in two directions at once.
the conflict is not the bug
My first reading of the conflict was: this is a coordination problem. I touched the same file on two branches, now I have to reconcile them. Standard merge hygiene.
That reading was incomplete. The real problem was that I had been editing a file that governs production behavior on any branch where the edit seemed relevant, without thinking about what branch-specific skill edits mean once those branches interact.
When a hotfix branch changes the skill’s JIRA transition rules and a feature branch changes its branch-deferred-creation logic at the same time, the conflict is not a text editor problem. It is a policy collision. Two branches are now shipping different definitions of how the agent should behave on every future ticket. Merging the file is making a policy decision about which behavior wins. I had not treated it as that.
The fetch/sync step that landed in ITEM-6744’s session is a good example of why this matters. That step runs before branch creation and verifies the clone’s remote state. It was added to prevent the agent from cutting a branch on a stale base. That is a safety invariant for every ticket, not just ITEM-6744. Once it’s in the skill file, it runs everywhere. Putting it in on a feature branch and not thinking about whether it conflicts with anything on the hotfix branch in flight is exactly the kind of casual editing that creates real problems at merge time.
The blast radius of a skill edit is every future ticket session that runs on a clone with that version of the file. A prompt file with that blast radius is not soft configuration. It is a policy file, and it deserves the same change-control caution as the code it orchestrates.
what changes now
The immediate fix was mechanical. Resolve the conflict, read both sides of the diff carefully, write a merged version that captured the customer-type priority fix from ITEM-6738’s edits, the role disambiguation from ITEM-6739’s edits, and the deferred branch creation from ITEM-6744’s edits. That took about twenty minutes and produced a clean merge.
The structural change is slower. I’m now treating edits to .claude/skills/item/SKILL.md the way I’d treat edits to the JIRA workflow configuration or the bamboo build pipeline. They happen on a branch with intention. They get reviewed before merge. They don’t get patched casually as a side effect of ticket work. If a ticket session reveals a skill gap, the fix goes into a tracked commit with a note, not an ambient edit that blurs into the ticket’s history.
The open question from that day is still open. Should the skill be split into a stable policy layer and a per-ticket behavior layer, so that hotfix branches can tune local behavior without touching the shared policy file that every ticket depends on. I don’t have an answer yet. The conflict was the first real indication that the skill is big enough to need that kind of architecture.