---
name: doc-proofread
description: Proofread documentation files through three progressive phases (basic corrections, logical reorganization, code consistency). Use when user asks to proofread docs, fix documentation, improve readme, check docs for accuracy, ensure documentation matches code, reorganize documentation, or update docs to match code.
---

# Doc Proofread

Proofread documentation files through three progressive phases, with user approval for each file.

## Workflow

### 1. Discover Documentation Files

Find all documentation files in the repository:
- Patterns: `*.md`, `*.txt`, `*.rst`, `readme*`, `changelog*`, `contributing*`
- Exclude directories: `node_modules`, `.git`, `venv`, `dist`, `build`

List all discovered files to the user.

### 2. Interactive File Loop

For each discovered file, ask:

> Do you want to proofread **[filename]**? (yes/skip)

- **yes**: proceed through the three phases below
- **skip**: move to the next file

### 3. Phase 1 - Basic Corrections

Surface-level fixes only. Do NOT change meaning or structure.

- Fix typos, grammar, and punctuation
- Fix inconsistent casing
- Fix whitespace issues (trailing spaces, inconsistent blank lines)
- Fix broken markdown syntax (unclosed backticks, malformed links, broken tables)

Present all proposed changes and ask for approval before applying.

### 4. Phase 2 - Logical Reorganization

Restructure for clarity. Preserve all content.

- Group related content under standard sections: Installation, Configuration, Usage, Development, Troubleshooting, Reference
- Create missing section headers where content exists but lacks headings
- Consolidate duplicate or overlapping sections
- Fix heading hierarchy (no skipped levels, consistent depth)

Present the proposed reorganization and ask for approval before applying.

### 5. Phase 3 - Code Consistency

Verify documentation matches the actual codebase.

1. Read `CLAUDE.md` and `AGENTS.md` first for project context
2. Compare documentation against these source-of-truth files (when they exist):
   - `docker-compose.yml`, `Dockerfile`
   - `package.json`, `Makefile`, `pytest.ini`
   - `.env.example`, config files
   - Source code referenced in the docs
3. Apply fixes:
   - Update outdated commands or flags
   - Add missing prerequisites
   - Fix incorrect code examples
   - Document hidden requirements found in code but missing from docs
4. Report any items that need human verification (ambiguous references, unclear intent)

Present all proposed changes and ask for approval before applying.

### 6. Completion Summary

After processing all files, present:
- Files processed (with phases completed)
- Files skipped
- Remaining recommendations that could not be automated

## Rules

- Do NOT apply changes without explicit user approval at each phase
- Do NOT change meaning during Phase 1
- Do NOT remove content during Phase 2, only reorganize
- Do NOT guess at code behavior in Phase 3 — flag uncertainties for human review
- Process one file at a time, completing all three phases before moving to the next