prose-review
Grade the prose in a patch against prose-style.md and report the findings; apply them with --fix. Covers code comments and javadoc by default, and commit messages, the PR description, or release notes when asked. Use this skill when the user asks to review, audit, grade, clean up, fix, tidy, or restyle comments, javadoc, commit messages, a PR description, or release notes, says "the comments need work", "check the prose on this branch", "do a comment pass", or asks for prose-style.md to be applied to anything. It reports by default and edits only with --fix. It never reviews code correctness; /code-review does that.
rustyrazorblade · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add rustyrazorblade/skills --skill prose-reviewAbout this skill
name: prose-review description: > Grade the prose in a patch against prose-style.md and report the findings; apply them with --fix. Covers code comments and javadoc by default, and commit messages, the PR description, or release notes when asked. Use this skill when the user asks to review, audit, grade, clean up, fix, tidy, or restyle comments, javadoc, commit messages, a PR description, or release notes, says "the comments need work", "check the prose on this branch", "do a comment pass", or asks for prose-style.md to be applied to anything. It reports by default and edits only with --fix. It never reviews code correctness; /code-review does that. argument-hint: "[path | commit range | --staged | --working] [--commits] [--pr] [--notes] [--all] [--fix]"
Prose review
Grade every in-scope passage against prose-style.md. Report the findings. Apply them only when
Jon passes --fix.
You judge words. You never judge code, and you never edit code.
Grader agents do the grading. You resolve the scope, you merge their findings, and you apply them. Sections 1 to 5 and 8 to 9 are your work. Sections 6 and 7 are the contract you hand to a grader.
1. Read the style reference first
prose-style.md is the authority. Read the whole file before you grade a single passage. Do not
work from memory of it.
Find it in this order:
prose-style.mdat the current repo root.prose-style.mdin a parent directory, walking up.${CLAUDE_PLUGIN_ROOT}/references/prose-style.md, this plugin's bundled copy.
A repo's own copy always wins; the bundled copy is the fallback, so the skill works in a repo that has no copy of its own. Never hardcode a path to a copy in some other repo. If you find no copy at all, stop and say so. Do not substitute general style knowledge.
Resolve the path to an absolute path and keep it. Every grader gets that path and reads the file itself. Never paste the file's contents into a prompt, and never summarise it for a grader.
Every rule below is a pointer into that file, not a replacement for it. When the two disagree,
prose-style.md wins.
2. Resolve the artifacts
Two dimensions: which prose, and which change. Resolve the prose first.
| Flag | Adds |
|---|---|
| (none) | Code comments and javadoc / API docs. The default. |
--commits | The commit messages in the resolved range. |
--pr | The pull request description for the branch. |
--notes | Release notes the patch touches. |
--all | All of the above. |
Comments are the default because they are the only artifact that ships inside the code and the only one every patch has. Everything else is opt in. Never widen past what Jon asked for. If you see a violation in an artifact he did not select, name it in Left alone and leave it.
3. Resolve the scope
Use the argument if Jon gave one:
- A path: every artifact in that file or directory.
- A commit range or a single revision: every artifact the range touches.
--stagedor--working: the staged or unstaged diff.
With no argument, review the current branch's patch. Get its base from the tracked upstream:
git merge-base HEAD @{upstream}
If the branch tracks nothing, ask Jon for the base branch. Do not guess it, and do not assume
trunk or main.
Print the resolved artifacts, the resolved scope, and the file count before you start.
What a patch scope includes
- Every passage on a line the patch adds or modifies.
- Every pre-existing passage the patch made wrong.
A pre-existing passage that is merely nearby stays out of scope. Say so in the report if you see a bad one, and leave it alone.
4. Run the Axis 1 pre-pass
Axis 1 violations are the highest severity and the cheapest to find. Run this pre-pass yourself, once, over the whole scope, before you fan out. Grep the in-scope files for the tells:
grep -nEi '(previously|formerly|used to|originally|in the first version|as of v|now correct|changed from|per review|review feedback|no longer|refactored|improved|new implementation|updated to)' <files>
Run the same grep over git log output when --commits is in play.
Treat every hit as a candidate, not a verdict. "No longer" and "instead of" have honest uses. A hit is a violation only when it references this branch's own unmerged history. A reference to merged history, a shipped release, or an open upstream bug is legitimate permanent context.
Split the hits by file and hand each grader the hits for its own files. A grader still greps its own artifact; your pass gives it a head start and gives you the whole-scope picture the shards cannot see.
Read prose-style.md's squash-target section before you judge a contrast drawn against a sibling
commit. A fixup commit that exists only to correct an earlier commit on the same unmerged branch is
itself an Axis 1 violation, whatever its wording. Report it and point at /squash. Never rewrite
history to fix it yourself; see the guardrails.
5. Fan out the grading
You never grade. Every verdict comes from a grader agent.
Spawn every agent in one message, so they run at the same time. Each one is
subagent_type: general-purpose, model: opus. Grading rewrites prose against a style authority;
that needs the strongest tier, not a fast lookup.
One grader per file shard. Sort the in-scope files by path. Deal them into shards of at most eight files. Cap the fan-out at six graders; past 48 files the shards grow instead of the agent count. A one-file scope still gets one grader; you do not grade it yourself.
Shard by whole files, never by line range. A grader needs the whole file to check an anchor and to check a referent.
One agent per opt-in artifact. --commits, --pr, and --notes each get their own agent,
spawned alongside the file graders. Release notes are prose in a file, so that agent works from the
file, not from the diff alone.
Every prompt carries, verbatim:
- The absolu