chore(ai): move versioned-writer checklist from CLAUDE.md to a skill

[kaseywright]

Targets mrace/feature/271-verse-audio-conflict-detection so it can merge into #281 before that lands on main.

Why

#281 adds CLAUDE.md at the repo root (the repo's first) alongside .cursor/rules/versioned-resource-writers.mdc. Both carry the same versioned-writer checklist, but they load very differently:

• The Cursor rule is gated — globs: src/**/*.{service,repository,route}.ts, alwaysApply: false. It loads only when you touch those files.
• Root CLAUDE.md has no equivalent gate. It enters context for every task in this repo, including ones nowhere near a version token.

The CLAUDE.md copy had also lost the rationale: compare "Every state-mutating write bumps the version token" against the Cursor rule's version, which explains why (a concurrent existing-unit writer that read the old token can still win its CAS and silently demote the first uploader). The reasoning is the part that makes the rule usable.

What changed

• Removed CLAUDE.md.
• Added .claude/skills/versioned-resource-writers/SKILL.md — the direct analogue of the Cursor rule's on-demand loading. A skill is selected by its description when the work matches, and costs nothing otherwise.
• Content mirrors the Cursor rule verbatim, since that version is the better of the two.
• Added a reciprocal pointer in the Cursor rule so the two don't drift silently.

Two copies remain, but that duplication is now legitimate — Cursor cannot read a Claude skill, and vice versa. Each tool gets a scoped, on-demand copy in its own format.

Two things for you to decide

Both carried over as-is rather than changed unilaterally:

1. The "AI review hygiene" section. It tells a reviewer what to treat as blocking vs. non-blocking. That's process guidance rather than repo knowledge, and it arrived in the PR it would govern the review of. Worth considering whether it belongs in CONTRIBUTING.md as a team decision instead of in an AI-context file. Left verbatim here.

2. Concurrency rule 3 may be too absolute. "Every state-mutating write bumps the token" — markConflictPreservingActive mutates conflictStatus and does not bump. That looks deliberate and fine, but it means the rule as written is already contradicted by the code it was extracted from. Might be worth narrowing it to link/advance paths.

Notes

No source changes — docs/config only. The checklist content itself is unchanged from what you wrote.

🤖 Generated with Claude Code

https://claude.ai/code/session_011FGa3gAfArR7GpjC8yBRuh

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fcf88caa-1125-4191-8807-6d942932b4af

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mattrace-gloo]

Approving — the reasoning is right and I'd have got this wrong on my own.

The gating asymmetry is the part I'd missed: I wrote the Cursor rule with globs + alwaysApply: false and then dropped the same content into a root CLAUDE.md without noticing I'd thrown the gating away in the process. A skill is the correct analogue. Agreed too that two copies is legitimate duplication rather than drift waiting to happen — neither tool reads the other's format, and you've added the reciprocal pointer.

Your two judgement calls

1. "AI review hygiene" placement — move it, and not to CONTRIBUTING.md in this PR.

You're right that it's process guidance rather than repo knowledge, and right to be uneasy that it arrived in the PR it would govern the review of. I'd add a third objection: I wrote it partly as a reaction to one review round, which is a bad sample size to codify from.

Suggest cutting the section from both copies here and proposing it separately as a team decision, where people can disagree with the blocking/non-blocking split without it being bundled into an audio feature. The remaining three sections are all repo knowledge and belong exactly where you've put them.

2. Concurrency rule 3 — agreed, and I've narrowed it.

markConflictPreservingActive is deliberate: it flags a conflict without changing what the recording points at, so it invalidates nobody's token and has nothing to bump. The rule as written was contradicted by its own source code, which is a good way to get it ignored.

I've reworded it on the base branch (c2c090d) to scope it to paths that advance state, with the conflict-flag case named as the explicit exception. Same commit adds two rules that came out of the latest review round:

• Clearing a conflict is its own operation — if ordinary writes can also clear it, the client that caused the conflict settles it by retrying with the token the conflict response handed back. That was a live bug in #281.
• Sweeps that delete are CAS too — re-check "still unreferenced" inside the deleting statement under a lock on the parent row, and delete rows before bytes so a concurrent re-upload can't have its revived object collected. Also a live bug in #281.

What that means for this PR

Sorry — that edit lands your SKILL.md out of sync before it merges. Since the whole point is the two staying mirrored, could you rebase and re-copy? If you'd rather not, I'm equally happy to take the rebase myself and merge, or to merge this first and mirror the rule changes on top. Your call, and thanks for opening it against the branch rather than main — that saved a round trip.

On your earlier point about disparate vendor usage: agreed that Cursor + Claude gets the 80/20, and the offer to wire this into a PR gate stands whenever the team wants it.

[kaseywright]

Both done, thanks for the quick turnaround.

Rebased onto c2c090d and re-copied the rule into the skill — it now carries the reworded rule 3, the two new rules (5: clearing a conflict is its own operation; 6: sweeps that delete are CAS too), and the Present + malformed → 400 row. The two files match again apart from frontmatter and the reciprocal pointers.

Cut "AI review hygiene" from both copies. Your third objection is the one that convinced me — generalising from a single review round is the weakest part, and it's the part that would age worst. Left the other three sections in place.

I'd also rather not be the one to propose the replacement: the blocking/non-blocking split is a call about how your team wants reviews to land, and I've been on one side of exactly one such review here. Happy to write it up as a strawman if that's useful, but it should be your team's decision, not a byproduct of this PR.

Also added the skill's own pointer back at the Cursor rule, so the sync obligation is stated in both directions rather than just one.

Reciprocal pointers are still the only thing keeping these in step, which works while it's two files and one checklist. If it grows, the sturdier answer is generating one from the other, or a CI check that diffs the shared body — the offer to wire that up stands.

One note while you're here: the bible_id divergence from the last review round on #281 (chapter-assignments.repository.ts:448 — the rollup filters on bt.bible_id while findForVerse and listByChapter don't) is the one item with no response yet in c2c090d. Not urgent, and not this PR's business — just flagging so it doesn't get lost.

[mattrace-gloo]

Thanks for turning this around so fast, and sorry for moving the base under you mid-review.

I diffed the two files at 43baea3 and they line up: identical bodies, with the only differences being the Cursor frontmatter vs the skill's name/description and the two pointers. Reworded rule 3, new rules 5 and 6, and the Present + malformed → 400 row all made it across.

On cutting "AI review hygiene" — agreed, and I think you're right about who should propose the replacement. Asking the reviewer to draft the blocking/non-blocking split for reviews they're a party to is an awkward position to put you in, and I shouldn't have. I'll raise it with the team as its own conversation; if we want a starting point after that I'll come ask, but the framing should come from us.

On the sync mechanism — reciprocal pointers feel like the right amount of machinery for two files and one checklist, and stating the obligation in both directions is a real improvement over the one-way version I had. If a second or third checklist shows up, generating one from the other (or your CI diff check) becomes the obviously correct answer and I'll take you up on it then.

One mechanical thing left, and it's mine, not the rebase's. GitHub is showing this as conflicting because c2c090d is no longer the branch tip — I pushed 4a5eef9 after you rebased, a CLAUDE.md-only doc fix, so it lands as a delete/modify conflict against the file this PR removes. The resolution is just "take the delete": everything that commit added to CLAUDE.md (the four token states and resolve-only) is already in the skill body, and the "Review triage" section it left behind is exactly the part we just agreed to cut. Since I caused it, I'm happy to push the rebase to your branch — say the word, or grab it yourself if you'd rather keep the branch yours.

On bible_id — good catch, and you're right that it's the one thing still unanswered. I walked it again: findForVerse matches on projectUnitId / bookId / chapterNumber with no bible predicate, while the rollup's bible_texts join requires bible_texts.bibleId = chapter_assignments.bibleId, so a unit whose assignment points at a different bible than its texts resolves in one and vanishes from the other. Real inconsistency, agreed it isn't this PR's business or #281's. I'll get it filed as its own item so it stops living in review threads.

[kaseywright]

@mattrace-gloo That all sounds great. Feel free to merge this PR into yours as you see fit.

[mattrace-gloo]

Went ahead and pushed the rebase since the conflict was mine — hope that's alright, and shout if you'd rather have driven it.

8bbb0dd, replayed onto 4a5eef9 with your two commits and authorship intact. CLAUDE.md resolved as "take the delete"; the three files are byte-identical to what you had at 43baea3, and the diff against the base tip is exactly the three this PR touches. Pre-push gate ran clean (format, lint, typecheck, 525 tests). GitHub now shows it mergeable.