review-changes

name	review-changes
description	Review uncommitted or recently committed documentation changes for correctness, coherence, and style compliance. Use before creating a PR to catch issues. "review my changes", "review the diff", "check the fix before submitting", "does this look right".
context	fork
model	opus

Review Changes

Evaluate whether the changes correctly and completely solve the stated problem, without introducing new issues. Start with no assumptions — the change may contain mistakes. Your job is to catch what the writer missed, not to rubber-stamp the diff.

1. Identify what changed

Determine the scope of changes to review:

# Uncommitted changes
git diff --name-only

# Last commit
git diff --name-only HEAD~1

# Entire branch vs main
git diff --name-only main...HEAD

Pick the right comparison for what's being reviewed. If reviewing a branch, use main...HEAD to see all changes since the branch diverged.

2. Read each changed file in full

Do not just read the diff. For every changed file, read the entire file to understand the full context the change lives in. A diff can look correct in isolation but contradict something earlier on the same page.

Then read the diff for the detailed changes:

# Adjust the comparison to match step 1
git diff --unified=10              # uncommitted
git diff --unified=10 HEAD~1       # last commit
git diff --unified=10 main...HEAD  # branch

3. Follow cross-references

For each changed file, check what links to it and what it links to:

• Search for other pages that reference the changed content (grep for the filename, heading anchors, or key phrases)
• Read linked pages to verify the change doesn't create contradictions across pages
• Check that anchor links in cross-references still match heading IDs

A change that's correct on its own page can break the story told by a related page.

4. Verify factual accuracy

Don't assume the change is factually correct just because it reads well.

• If the change describes how a feature behaves, verify against upstream docs or source code
• If the change includes a URL, check that it resolves
• If the change references a CLI flag, option, or API field, confirm it exists

5. Evaluate as a reader

Consider someone landing on this page from a search result, with no prior context:

• Does the page make sense on its own?
• Is the changed section clear without having read the issue or diff?
• Would a reader be confused by anything the change introduces or leaves out?

6. Review code and template changes

For non-Markdown changes (JS, HTML, CSS, Hugo templates):

• Trace through the common execution path
• Trace through at least one edge case (no stored preference, Alpine fails to load, first visit vs returning visitor)
• Ask whether the change could produce unexpected browser or runtime behavior that no automated tool would catch

7. Decision

Approve if the change is correct, coherent, complete, and factually accurate.

Request changes if:

• The change does not correctly solve the stated problem
• There is a factual error or contradiction (on-page or cross-page)
• A cross-reference is broken or misleading
• A reader would be confused

When requesting changes, be specific: quote the exact text that is wrong, explain why, and suggest the correct fix.