How compelling
is your README?

Status: ready — not yet trained.

Traits

Concrete Usage Demonstration

Show with examples ↔ Tell with descriptions

Whether the README shows real usage with actual inputs, outputs, or results — versus describing capabilities abstractly or listing features without showing them in action

Copy-Pasteable Setup

Minimal runnable commands ↔ Abstract setup instructions

Whether getting-started instructions consist of minimal, concrete, directly runnable commands the reader can copy and execute — versus abstract prose descriptions of setup

Hook Speed

Front-loaded hook ↔ Buried lede

Whether the README's very first sentence or heading delivers the value-packed punch, or buries the lede under badges, preamble, or boilerplate

Hype-Free Credibility

Evidence-backed claims ↔ Unsubstantiated superlatives

Whether the README establishes credibility through specific evidence, concrete benchmarks, and honest scoping — versus relying on superlatives, unsubstantiated marketing claims, or vague qualifiers

Problem Framing

Problem-first motivation ↔ Feature-first listing

Whether the README articulates a specific problem or pain point before presenting the solution, giving the reader a "why this exists" before "what it does"

Progressive Disclosure

Layered depth ↔ All-or-nothing dump

Whether the README layers information by depth — quick start for skimmers, details for the curious — versus presenting everything at one depth that forces all readers through the same wall

Structural Scannability

Navigable hierarchy ↔ Undifferentiated wall

Whether the README uses clear markdown hierarchy, descriptive headings, short focused paragraphs, and visual separation — versus undifferentiated prose walls or poorly organized blocks

Value Proposition Clarity

Instant clarity ↔ Buried purpose

Whether the README makes unmistakably clear what the project does and why you'd want it — using concrete, specific language rather than vague abstractions