docs(skills): add prose-pass skill for comment and changelog brevity

[sirtimid]

Comments, changelog entries, and PR bodies here kept needing the same correction: cut whatever a reader can derive from the code. That standard lived in per-session reminders rather than in the repo, so it only applied when someone remembered to give it. This checks it in.

prose-pass states the bar — the default is no comment, and accuracy alone does not justify one — then the judgements that follow: restatements, log-call preambles, TDD scaffolding, and rationale duplicated across files go; constraints, invariants, and test-shape rationale stay. Every rule is framed as information content rather than phrasing. The openers section is deliberate about this: it lists the patterns models produce constantly (Ensure, This ensures, Note that) but treats them as a signal to inspect rather than a delete list, so // Note that N must stay a power of two. survives.

Changes

• .claude/skills/prose-pass/SKILL.md — the standard, with separate sections for changelogs (the consumer test) and PR bodies (which need the narrative and testing note a changelog must not carry)
• commit, pr, and update-changelogs invoke it; commit's checks now run after it, since the pass can rename identifiers or extract functions
• code-review reads it as review criteria rather than invoking it — it edits files, and a review may have nothing checked out
• AGENTS.md points at the file by path, so agents with no Skill tool can still comply

Testing

No code changed, so this is prettier plus review of the text itself. Three review passes found real defects: the skill originally instructed deletions that break jsdoc/require-description, banned the testing note the pr skill requires in a PR body, and swept comments only after the review subagents had run. Each is fixed in the follow-up commits.

---

Note

Low Risk
Documentation and Claude skill workflow changes only; no runtime or package behavior changes.

Overview
Adds a checked-in prose-pass skill that defines when to cut comments, JSDoc, changelog lines, and PR prose (default: no comment unless the code cannot carry the information), and wires it into agent workflows.

commit now runs the pass on the diff before staging and moves lint-build-test to after the pass so renames or comment trims do not fail checks prematurely. pr runs it on diff comments before automated review (with optional trim commit/push), on the drafted PR body before gh pr create, and on changelog drafts via args="changelogs". update-changelogs and code-review reference the same standard (review reads criteria only; it does not invoke the skill). AGENTS.md links the skill for agents without the Skill tool, and .claude/settings.json allows Skill(prose-pass).

^{Reviewed by Cursor Bugbot for commit 51ff46d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 51ff46d. Configure here.}

[cursor]

Unscoped prose pass after review

Medium Severity

Phase 4 invokes prose-pass with no args, so the default full pass still judges comments and may rename identifiers after review. Those file edits are not committed before gh pr create, and can land unreviewed in the later changelog commit.

Additional Locations (1)

• .claude/skills/prose-pass/SKILL.md#L12-L14

 

^{Reviewed by Cursor Bugbot for commit 51ff46d. Configure here.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	72.55% ⬆️ +0.01%	9697 / 13365
🔵	Statements	72.4% 🟰 ±0%	9860 / 13617
🔵	Functions	72.99% 🟰 ±0%	2276 / 3118
🔵	Branches	66.91% ⬆️ +0.02%	3990 / 5963

File Coverage

No changed files found.

Generated in workflow #4701 for commit 51ff46d by the Vitest Coverage Report Action