Rig Proof

rig-proof — proofread what an agent wrote

Two verbs over one source of truth:

• find (default) — check prose against the project's writing-style guide and return findings with line references. Read-only.
• fix — apply them, then re-check.

The guide is the only rulebook. Its path is style.guideFile in .rig/config.json (default .claude/STYLE.md). This skill has no style opinions of its own: read the guide, walk its rules, cite them by number. When a project prunes or extends the guide, this skill follows automatically — the same relationship /rig-review has to REVIEWER.md.

Why this exists

The personas already tell agents how to write. Instructions decay under load: an agent 40 tool-calls deep, writing the PR body last, has spent its attention elsewhere. This is the gate that catches what the instruction missed — the same reason /rig-task runs a pre-PR self-review instead of trusting that the coder internalized the review catalog.

Configuration

Reads .rig/config.json:

• style.guideFile — the writing-style guide, and the only rule source (default .claude/STYLE.md, then .rig/STYLE.md). If no guide is found, say so and stop — don't substitute your own preferences.
• vcs.baseRef — diff base when checking changed Markdown (default origin/main).
• project.repo — owner/name for gh calls when the target is a PR.

Scope — what to check, and what to leave alone

Default to one named target. This skill is a proofreader, not a repo-wide linter; pointing it at every document in the tree produces a finding pile nobody asked for.

Resolve $ARGUMENTS to a target in this order:

Never check code. Source files are out of scope: identifiers and comments follow the conventions of the code around them, not a prose guide. Skip generated files, vendored directories, and CHANGELOG.md.

Only sweep the whole repo when the user explicitly asks for it. Report per-file counts first and let them pick where to start. Don't dump every finding at once.

find — the read-only pass

1. Read the guide. Resolve style.guideFile, read it, and keep its rule numbers — every finding cites one.

2. Run the mechanical pass first. It costs nothing and it removes the word-spotting work from your plate:

   <SCRIPT> --json <target-file>        # or: … --stdin  (text on stdin)
   

   where <SCRIPT> = .claude/scripts/check-style.ts if present, else .rig/scripts/check-style.ts, else <RIG_DIR>/scripts/check-style.ts (run with bun). It harvests the banned terms from the guide itself and greps for them, plus flags over-long sentences. Code, fenced blocks, and link targets are masked, so it never flags a snippet.

   Its findings are candidates, not verdicts. just, simple, and obvious have legitimate uses; a 34-word sentence can be the clearest way to say something. Triage each one — you're the judgment the script doesn't have. Drop a candidate that reads fine and say nothing about it.

   If the script is missing or reports 0 harvested terms, do the whole pass yourself and note that the mechanical half didn't run.

3. Read the prose yourself for what no grep catches. This is the half that matters:

   • Buried conclusion. Does the first sentence carry the answer, or does the reader wade through process narration to reach it? This is the most common defect and the most expensive.
   • Passive voice where the actor matters — especially in a sentence the reader has to act on.
   • Hedge stacks. it seems like it might possibly — either go check, or say plainly that you didn't.
   • Unanchored claims. An assertion about the code with no file:line, command, count, or SHA behind it.
   • Unmarked guesses. Something inferred, presented as observed.
   • Structure. Three-plus parallel items still in a paragraph; a comparison that wants a table; ordered steps in prose.
   • Self-narration — preamble, apology, closing offer of further help.
   • Untestable acceptance criteria, when the target is a ticket.
   • Anything else the guide's rules call for that the script can't see.

4. Report. Lead with the verdict, then findings in document order. One entry per finding, each citing the guide rule and the line:

   3 findings — 2 that change how it reads, 1 nit
   
   12:1  [rule 1: answer first] The verdict is in the last paragraph. Move
         "the filter breaks the webhook path" to the first sentence.
   18:34 [rule 3: active voice] "the lookup should be scoped" — say who
         scopes it.
   24:7  [rule 8: cut filler] "it's worth noting that" — delete.
   

   Rank by how much each one costs a reader: a buried conclusion outranks a filler word. If the prose is clean, say so in one line and stop — don't pad the report to look thorough. Then offer fix.

fix — apply the findings

1. Get findings. Use the caller's find output if passed; else run find.
2. Rewrite. Apply the changes to the target, smallest edit that fixes each finding.
   • Preserve meaning exactly. Rewriting prose must not change a claim, a number, a file path, a severity, or a conclusion. If a sentence is unclear because the underlying fact is unclear, that's not a writing problem — report it and leave the sentence alone.
   • Never touch code, code spans, or fenced blocks. Not the identifiers in them, not the commands.
   • Keep the artifact's required structure. A PR body still needs its tracker link and ## Architecture note; a ticket still needs its acceptance criteria.
3. Re-check. Run find again. Report what changed and what you left, with the reason for each thing you left.
4. Show the diff for a durable artifact. A local file you may edit directly. When the target is already published — a PR body, a filed ticket — show the rewrite and get a yes first, then push it (gh pr edit --body, gh issue edit --body, Linear save_issue).

Calling it from another skill

find is cheap and read-only, so the flows run it before the artifact lands, not after:

• /rig-task Step 5 — on the PR body, before gh pr create.
• /rig-issue create — on the ticket body, before filing.
• /rig-spike — on the writeup, before posting it back to the ticket.

A caller may thread {target} or pipe the draft text in on stdin. Return the finding list, and the rewritten text when called with fix.

Notes

• Read-only by default. find reports; only fix edits.
• Degrades: no guide → say so and stop. No check-style.ts → model-only pass. Neither is a hard failure.
• Not a bug hunter. Wrong claims are /rig-review's job; this checks how the writing reads, not whether it's true. If you notice a false claim while proofreading, say so — but don't go looking.
• Don't proofread the same artifact twice. If find came back clean once and the text hasn't changed, there's nothing to add.