write-clear-readme

Write Clear README

Important — Writing rules

Apply these rules to emitted prose: docs, comments, commit messages, PR bodies, and release notes.

• Match surrounding punctuation, capitalization, and formatting.
• Every sentence changes the reader's understanding. Cut it otherwise.
• Lead with the action or outcome.
• Use concrete language and lists when they improve comparison or sequence.
• Assert positively. Reserve negation for real constraints (NEVER commit secrets).
• No marketing words: powerful, robust, seamlessly, leverage, unlock, comprehensive, delightful.
• No AI tells: delve, tapestry, intricate, pivotal, testament, underscore, crucial, garner, showcase, additionally, moreover, furthermore, indeed.
• For substantive English prose, use /humanize-en if installed with the existing scope and authorization. It adds no approval stage; skip redundant passes over short status text.

Author, audit, or polish a README.md for clarity and scannable structure. Read repository truth first. Explicit author/polish requests authorize local edits; audit/propose stays read-only. Carry this target and mode through a nested prose pass without another approval prompt. Publication is a separate action.

Additional context from the user: $ARGUMENTS

Context

• Repo: !basename $(git rev-parse --show-toplevel 2>/dev/null || echo unknown)
• Existing README: !test -f README.md && wc -l < README.md | awk '{print $1 " lines"}' || echo "none"
• Package manifest: !test -f package.json && jq -r '.name + "@" + .version' package.json 2>/dev/null || echo "none"
• Top-level folders: !ls -d */ 2>/dev/null | head -20 | tr '\n' ' '

Doc type → pattern

Long READMEs cause scroll fatigue. The fix is a structural decision before any prose: pick one collapse pattern for the whole doc and apply it uniformly. Selective collapse driven by per-section judgment — some sections visible, some hidden — creates a minefield. Readers cannot infer the rule, every heading becomes a guess.