public-readme-polisher

name	public-readme-polisher
description	Use when improving a public README, repository homepage, docs landing page, or developer-facing first impression.

Public README Polisher

Polish the README as the repo's public front door: credible, scannable, actionable, and claim-safe.

Use When

• a README feels plain
• a repo needs a public first impression
• a docs landing page needs clearer value, install path, or proof
• a visual asset could make the repo easier to understand

Process

1. Audit repo truth: purpose, install path, tests, license, security, CI, docs, examples, and public claim boundaries.
2. Define the public promise in one paragraph: who it helps, what it gives them, and what it does not guarantee.
3. Improve the first viewport: title, optional hero, badges, concise opening, quick action, and a scannable "what you get" table.
4. Add scanning structure: quick start, workflow diagram when useful, proof or sources near the claim, and links to deeper docs.
5. Validate links, images, alt text, docs scan, tests, and the scorecard below.

Visual Asset Rules

• Use one purposeful hero only when it clarifies the repo.
• For generated images: no embedded text, no logos, no watermarks.
• Inspect the image before committing; reject generated image with readable fake text, broken UI, mascot drift, or misleading claims.
• Save README assets under assets/readme.
• Add alt text that explains the image function.

Claim Safety

• Cite official sources for factual pricing, cache, legal, API, or security claims.
• Say "patterns that worked for us" for experience-based recommendations.
• Avoid guaranteed savings, official endorsement, universal safety claims, or "works for every workflow" language.
• Keep related tools optional unless the repo truly depends on them.

Scorecard

Score each category 0-2. Pass at 13/16 or higher.

Category	2 means
First-viewport signal	repo purpose, visual tone, badges, and install path are clear without scrolling
Audience/value clarity	reader knows who it is for and what problem it solves
Scannability	tables, bullets, headings, and diagrams make scanning easy
Actionability	quick start and next links are concrete and current
Trust/proof	sources, CI, license, tests, and safety boundaries support the claims
Visual polish	assets feel intentional, domain-fit, and not generic stock decoration
Accessibility/asset hygiene	alt text, local paths, file size, and image rendering are sane
Claim safety	claims are bounded, sourced where needed, and public-safe

Automatic blockers: private paths, secrets, broken local links, missing install path, false or guaranteed claims, generated image with readable fake text, missing alt text, failing docs scan.

Common Mistakes

• Making a marketing page that hides the actual install/use path.
• Adding a pretty image that does not explain the repo.
• Moving official citations away from the claims they support.
• Replacing precise safety boundaries with vague hype.
• Claiming completion without running the scorecard.