Proofread Review Agent

What This Does

This playbook creates a specialized proofreading agent that only focuses on language quality — grammar, spelling, punctuation, word choice, and clarity. By limiting scope, it catches errors that generalist reviews miss.

Why a dedicated proofreader works: When Claude reviews code AND grammar at the same time, attention splits. A focused proofreader examines every word, catches "principal" vs "principle", spots missing articles, and flags awkward phrasing.

Prerequisites

• Claude Code installed
• Content to proofread (docs, comments, README, UI text, etc.)

Proofreading Report: [filename]

Issues Found: X

Spelling (X issues)

• Line Y: "recieve" → "receive"
• Line Z: "seperate" → "separate"

Grammar (X issues)

• Line Y: "The data are" → "The data is" (or vice versa, be consistent)
• Line Z: Fragment: "Which is why we use this."

Punctuation (X issues)

• Line Y: Missing comma after introductory clause
• Line Z: Incorrect apostrophe in "it's" (should be "its")

Clarity (X issues)

• Line Y: Ambiguous "it" reference — specify what "it" refers to
• Line Z: Sentence too long (40+ words) — consider splitting

Consistency (X issues)

• Lines Y, Z: Mixed "color"/"colour" — pick one
• Line W: "setup" vs "set up" — use "setup" (noun) vs "set up" (verb)

Summary: X spelling, Y grammar, Z punctuation, W clarity, V consistency

## Proofreading Rules

1. **Read every word**: Don't skim. Process each word deliberately.
2. **Check homonyms**: their/there/they're, its/it's, your/you're, affect/effect
3. **Verify proper nouns**: Product names, company names, technical terms
4. **Context matters**: "data is" vs "data are" depends on style guide
5. **Don't over-correct**: Preserve author's voice, fix only clear errors
6. **Flag uncertain**: If unsure, flag with [?] rather than silent change

## Common Errors to Catch

### Often Missed
- "it's" vs "its" (most common error)
- "affect" vs "effect"
- "compliment" vs "complement"
- "principle" vs "principal"
- "then" vs "than"
- Double spaces after periods
- Missing Oxford comma (or inconsistent usage)

### Technical Writing
- "setup" (noun) vs "set up" (verb)
- "login" (noun) vs "log in" (verb)
- "runtime" vs "run time"
- Inconsistent capitalization of technical terms

### Code Comments & Docs
- "todo" vs "TODO" vs "Todo" (pick one)
- Incomplete sentences in comments
- Outdated references ("see above" when moved)

## Invoking the Proofreader

proofread README.md proofread src/components/ --only-comments proofread docs/

## Integration with Other Agents

The proofreader runs independently. In a multi-agent review:

1. Code reviewer checks logic
2. Security reviewer checks vulnerabilities
3. **Proofreader checks language** ← This agent
4. Results synthesized

Each agent stays focused on their specialty.

Step-by-Step Setup

Step 1: Add to CLAUDE.md

Add the proofreading protocol to your project's CLAUDE.md file.

Step 2: Test on a file

proofread README.md

Claude should produce a detailed language-only report.

Step 3: Review the output

Check that Claude stayed focused on language issues and didn't drift into code review.

Step 4: Iterate on rules

If Claude catches too much or too little, adjust the "What You Check" and "What You DON'T Check" sections.

Example Usage

User:

"proofread the API documentation in docs/api/"

Claude:

Proofreading Report: docs/api/authentication.md

Issues Found: 7

Spelling (2 issues)

• Line 34: "authenication" → "authentication"
• Line 89: "recieved" → "received"

Grammar (2 issues)

• Line 12: "The tokens is" → "The tokens are"
• Line 56: Fragment: "Because security."

Punctuation (1 issue)

• Line 23: Missing comma: "After authentication the user..."

Clarity (1 issue)

• Line 45: "It validates this" — unclear what "this" refers to

Consistency (1 issue)

• Lines 15, 67: "authorization" vs "authorisation" — use American spelling throughout

Summary: 2 spelling, 2 grammar, 1 punctuation, 1 clarity, 1 consistency

Tips

• Run proofreader last: After all code changes are done, to avoid re-checking edited sections.
• Batch similar files: Proofread all docs at once for consistency checking.
• Set style guide: Add "We use American English" or "We use Oxford commas" to reduce false positives.
• Check generated text: AI-generated content often has subtle errors — always proofread.

Troubleshooting

Problem: Claude keeps commenting on code quality

Solution: Add stronger guardrails: "NEVER comment on code logic, syntax, or functionality. Language ONLY."

Problem: Too many false positives on technical terms

Solution: Add an allowlist: "Accepted terms: [list of project-specific terms]"

Problem: Missing errors in dense technical content

Solution: Ask Claude to "read aloud mentally" each sentence to catch awkward phrasing.