---
name: readme-clarity-review
description: Reviews a README for clarity and completeness — flags missing sections, jargon, and unclear quickstart steps. Use when the user asks to review, audit, or improve a README file.
---

# README Clarity Review

When the user asks you to review a README:

1. Read the full file first, start to finish, before commenting on any of it.
2. Check that these sections exist, in substance if not by exact heading:
   - What the project is (one or two sentences, plain language)
   - Why it matters / what problem it solves
   - How to install or run it (quickstart)
   - How to configure it, if it needs configuration
   Flag any that are missing.
3. Flag jargon, acronyms, or internal tool names used without a first
   definition. A new reader should never hit an unexplained term in the
   first two paragraphs.
4. Walk the quickstart literally, step by step, as written — do not fill in
   gaps from assumed knowledge. If a step depends on something the reader
   hasn't been told yet (an env var, a prior command, an account signup),
   flag exactly where it breaks.
5. Check that code blocks are runnable as written: correct fences, no
   placeholder text left in a command that looks like a real one.
6. Report findings as a short list — section, issue, one-line suggested fix.
   Do not rewrite the whole README unless the user asks for that; report
   first.

Keep the tone direct and specific. "Quickstart step 3 assumes `API_KEY` is
already set but it's never introduced" is useful; "could be clearer" is not.