diff options
| author | Craig Jennings <c@cjennings.net> | 2026-07-27 13:58:35 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-07-27 13:58:35 -0500 |
| commit | 931f364864441676eb250cecd074c4876012a1cd (patch) | |
| tree | 3531a0fc7f8e8d8af1bcfab4083952e0876eb35b /review-code | |
| parent | d74d98d03e7321b6c69dae9ef427da66b0f6fbc6 (diff) | |
| download | rulesets-931f364864441676eb250cecd074c4876012a1cd.tar.gz rulesets-931f364864441676eb250cecd074c4876012a1cd.zip | |
refactor(rules): split commits.md into invariants plus a publish skill
commits.md was 12,800 tokens, larger than the next four rules combined, and it loaded in every session in every project whether or not anything was being published. Most of it is procedure that only applies when a commit or PR is in play.
I split it by blast radius rather than by size. What stays always-loaded is what must hold whether or not I'm publishing, and where a violation is permanent and reaches other people: author identity, the no-AI-attribution ban, the generated-document byline rule, and the public-artifact content-scope rules. That core is 1,027 words, about 2,342 tokens.
What moved into the publish skill is everything about how a message gets written, reviewed, approved, and published. The pre-flight reconcile, the code-review gate, the draft and voice and approval gate, conventional-commit format, Voice and Focus, PR description structure, the three review shapes, merge strategy, and the pre-commit checklist.
The failure modes are why the line falls there. If the skill doesn't load I don't know the publish flow and have to be told, which is visible and recoverable. I don't silently commit with AI attribution, because that guard never moved. Only the recoverable half is on the skill-triggering bet.
I verified the split by using it. The skill registered mid-session and I invoked it to publish this commit, and it loaded with the flow intact.
Content is conserved: 5,561 words in, 5,898 across both files, the difference being the frontmatter and the pointer I added to the core. I repointed five cross-references in voice, review-code, inbox.org, and no-approvals.org that named sections which moved.
One thing I left alone. The skill is a single 4,871-word file, and both posts argue a long skill should split internally rather than sit as one blob. It loads on demand now, which is the win worth taking today. Splitting it further is its own change.
Diffstat (limited to 'review-code')
| -rw-r--r-- | review-code/SKILL.md | 2 |
1 files changed, 1 insertions, 1 deletions
diff --git a/review-code/SKILL.md b/review-code/SKILL.md index 3757404..a2b3c2b 100644 --- a/review-code/SKILL.md +++ b/review-code/SKILL.md @@ -446,7 +446,7 @@ None. The summary body and the inline pins work as a pair: scannable verdict on top, full coaching conversation in the pins. Read this section paired with Inline Comment Voice below — the summary is terse precisely because the inlines carry the teaching weight. -The structured report above stays local. When the verdict is posted as a GitHub review (per `commits.md` Step 2 Shape 1), keep the summary body terse — one long sentence or a few short ones is plenty. Vary the phrasing run-to-run so consecutive reviews don't read templated. Voice: an encouraging senior dev who doesn't like to talk. Lead with the substantive pointer — the design note or blocker that's pinned inline — and close with the verdict; the summary carries no praise clause. +The structured report above stays local. When the verdict is posted as a GitHub review (per the `publish` skill, Step 2 Shape 1), keep the summary body terse — one long sentence or a few short ones is plenty. Vary the phrasing run-to-run so consecutive reviews don't read templated. Voice: an encouraging senior dev who doesn't like to talk. Lead with the substantive pointer — the design note or blocker that's pinned inline — and close with the verdict; the summary carries no praise clause. The summary body carries no praise — not a named good thing, not a bare positive. The author made the change and already knows its merits, so a compliment in a terse summary reads as filler or sycophancy. If a genuine positive is worth surfacing, it goes as a single inline pin on the relevant line (see below), never the summary body. Elaboration in the summary is for the substantive pointer and for findings — what's wrong, the failure mode, the fix — never for compliments. |
