readme-bookstore-test

name	readme-bookstore-test
description	Generates and iterates a README that earns the reader's attention progressively (cover → inner flap → reading the book), then verifies every claim and example against the real artifact. Use when writing or reviewing a README or landing page for a library or tool. Includes an iteration ratchet - corrections made during review are captured as general principles, not one-off edits.

README — The Bookstore Test

Write a README the way a person decides to buy a book: they glance at the cover, read the inner flap, then commit to reading the book. The README must earn the reader's attention at each stage before asking for more of it.

This skill runs in four phases: Draft → Verify → Iterate → Ratchet. The draft is cheap; the verification is the product. A README is a set of claims, and unverified claims rot.

---

Phase 1 — Draft

The Cover

Open with a single sentence that states what problem this library solves — not what the library is, and not the product it belongs to. The reader should recognize their own situation. No taglines, no badges, no logos.

Good: "Coordinate multiple coding agent sessions across a repository and merge their pull requests sequentially." Bad: "Jules Fleet is a powerful orchestration framework built on the Jules platform for enterprise-grade AI agent management."

The Inner Flap

Immediately show the library in use. Code speaks louder than descriptions. Show the primary workflow in a single, copy-pasteable example, then one or two secondary workflows that reveal depth.

• No setup first. Don't open with installation, auth, or configuration. The reader hasn't decided to use the library yet.
• Anchor in the reader's existing habit. If the library mirrors, replaces, or extends something the reader already knows, the first example should read like the thing they already write — with the delta made explicit ("the one line that differs is…"). The fastest route to "I get it" is recognition plus one visible change, not novelty.
• Straightforward language. Describe what the code does, not how impressive it is. Never "powerful", "seamless", "robust", "enterprise-grade", "cutting-edge".
• Working examples. Valid, runnable code — no pseudocode, no // ... elisions.
• Progressive complexity. Simplest useful invocation first, then one advanced case that reveals a second capability.

Reading the Book

Now the reader is committed. Document the full top-level API — every command, function, or option a user would reach for. Comprehensive in scope, concise in explanation. Structure as reference, not tutorial: what it does (one line), minimal usage, options as a table or list. Setup, auth, and configuration go here — after the reader has decided.

Tone

Write like a colleague explaining their work to another engineer. Direct and specific. Don't sell — inform. If a feature has limitations, state them as facts with pointers to where they're tracked, not as hedges. Trust earns more adoption than marketing.

Vocabulary

• One name per concept, used consistently from the first mention. If the project has internal codenames or a domain glossary, either define a term on first use or don't use it.
• Freeze the vocabulary before you publish it. If a rename is already planned, write the new name or delay the section — never document a name scheduled to die.
• Give the reader the parent term before the precise ones. Readers need one broad word for the whole apparatus before they can absorb the taxonomy beneath it.

---

Phase 2 — Verify (the phase that isn't optional)

Every README is a set of claims. Before publishing, verify each class:

1. Execute every command. Run each shell command in the README exactly as written, in a fresh directory. A command transcribed from a source file's comment or your memory is a guess, not a fact — tooling entries go missing, flags drift, scripts get renamed.
2. Run every example against the installed artifact. Examples must be validated against what the reader will actually have — the packed tarball or published package installed into a clean consumer project — not against the source tree. Source trees resolve imports and carry state that installed packages don't.
3. Match every claim to its evidence tier. State only what the project's tests or documentation system actually back. "Compatible with X" is a different claim from "mirrors X's behavior, verified against captures of X" — write the one that's true, and link to the proof rather than substituting adjectives for it. Receipts beat superlatives.
4. Treat hand-maintained lists as drift debt. Any README table that mirrors machine truth — exported subpaths, commands, option lists — WILL drift from the source of truth. Either generate it from that source, add a mechanical check that diffs it, or replace it with a link to generated reference docs. If none of those, consciously accept the debt and note where the truth lives.
5. State the stability contract explicitly. Version, maturity (alpha / beta / stable), what is promised and what may change — in plain words, near the top of Reading the Book. An experimental product loses nothing by saying so and loses everything by being discovered to be.

---

Phase 3 — Iterate

Generate the draft, then hand it to the human owner for nuance. Expect corrections — the owner holds context the generator doesn't (positioning, audience, history). Apply corrections faithfully. Do not defend the draft.

---

Phase 4 — Ratchet (how this skill improves)

After each iteration session, for every correction the human made, ask: "What is the general principle behind this correction — stated so it applies to any library, not this one?" Append the answer to the Learned Principles section below, dated. Corrections that are genuinely one-off (taste, positioning specific to this product) are applied but not recorded.

This is the ratchet: the skill accumulates judgment; the next first draft starts where the last iteration ended.

Learned Principles

• 2026-07-08 — Commands rot silently. A documented command referenced a tool whose runner entry was never wired up; nothing failed until the command was executed during fact-checking. Principle: executing every documented command is the cheapest bug-finder a docs pass has — Phase 2.1 exists because transcription is not verification.
• 2026-07-08 — Surface tables drift. Hand-maintained API/subpath tables in shipped READMEs were missing a meaningful fraction of real exports, unnoticed for months, because nothing checked them. Principle: Phase 2.4 — generate, check, link, or consciously accept.
• 2026-07-08 — Recognition beats explanation. The strongest first example for a mirror-style product was the upstream product's own canonical snippet with exactly one changed line, and the gap that broke that snippet was the product's highest-priority bug. Principle: the inner flap's first example should be the reader's existing muscle memory plus a visible delta (Phase 1, "anchor in the reader's existing habit").
• 2026-07-08 — Claims need a tier, not an adjective. "Verified against production behavior" and "believed correct from documentation" are different claims that both hide behind "compatible". Principle: Phase 2.3 — write the claim at the strength the evidence supports and link the evidence.
• 2026-07-08 — Narrative before inventory. A structurally correct, fully verified draft was rejected because it read like a manual: it documented the codebase instead of telling the reader what their life looks like with the product. The reader's test is "oh, I could use this for…" — every section must serve self-interest woven into a story (the problem's real cost, the one-command relief, what the reader keeps). A README is not a repo autobiography; put the story ahead of the API and let the reference material live in linked docs.
• 2026-07-08 — For invisible-by-design products, the product's API is the wrong hero. When a product's ideal usage hides it (a dev-time layer, a wrapper, a runner), most users never import it — so the primary example must show the user's UNCHANGED world plus the one command that adds the product, and the product's own API belongs in a "when you want explicit control" section near the end. Recognition-plus-delta (an earlier principle) was necessary but insufficient: the delta for these products is a command, not a changed import.
• 2026-07-08 — Position as AND, not VS. If the product complements an incumbent rather than replacing it, say so explicitly and early ("X during development, incumbent in production") — otherwise the reader manufactures a migration decision the product never asks them to make, and declines it.
• 2026-07-08 — Show uniqueness, never declare it. "Nothing else does this" is pretentious and unfalsifiable; a concrete list of capabilities the reader has never had (with what each one is FOR) makes the same point and survives skepticism. Related: capabilities are supporting cast — name the protagonist (the core primitive that makes them possible) and attach every capability to it, rather than presenting a flat feature list.

---

Anti-patterns

Anti-pattern	Why it fails
Leading with badges, logos, or status shields	Visual noise before the reader knows what the library does
"Getting Started" as the first section	Forces setup before demonstrating value
Feature bullet lists without code	Tells instead of shows — the reader can't evaluate the API
"Easy to use", "simple", "just works"	Self-congratulatory claims that invite skepticism
Long install/config blocks before any usage	Asks for investment before demonstrating return
Collapsible sections hiding core API docs	Buries the content committed readers came for
Unexecuted commands and untested examples	The README becomes the first place the product breaks
Adjectives where evidence should be	"Robust" is a claim with no falsifier; a linked test count is one
Documenting names scheduled for renaming	Ships vocabulary that contradicts the next release

Checklist

Before publishing, verify:

• Can a reader understand what the library does in under 10 seconds?
• Is there a runnable code example within the first scroll?
• Does the first example anchor in something the reader already knows, with the delta explicit?
• Does setup/config appear after the first code example?
• Has every shell command been executed as written, in a fresh directory?
• Has every code example been run against the installed package (not the source tree)?
• Is every factual claim written at the strength its evidence supports, with a link to the evidence?
• Are all hand-maintained lists generated, mechanically checked, or consciously accepted as drift debt?
• Is the stability contract (version, maturity, what may change) stated plainly?
• Is the language descriptive rather than promotional?
• Does the reference section cover every top-level API entry?
• Were this iteration's corrections generalized into Learned Principles?