--- name: better-readme description: Audit and rewrite a project README against reader-funnel principles (noffle's "Art of README"). Use when the user asks to review, improve, rewrite, or translate a README, or asks whether their README is good — covers funnel ordering, moving maintainer content out, doc-shape tests pinned in CI, neutral multi-tool framing, idiomatic translations, and link/claim verification. --- # Better README A README is the consumer's first — and maybe only — look at the project. It is also the project's contract: the documentation, not the code, defines what the project does and what it promises to keep stable. No README means no abstraction — readers must read the source to learn the interface, and the interface/implementation boundary disappears. The job is not to sell; it is to let each reader evaluate fit as fast as possible, including bailing out early. Structure every README as a **cognitive funnel**: broadest, most decision-relevant facts first, deeper detail only for readers who already decided to stay. The reference framework is noffle's *Art of README*. An archived copy lives in this skill at [references/art-of-readme.md](references/art-of-readme.md) — the upstream repository link has gone offline, so consult the local copy when you need the original checklist or the reasoning behind a rule. Do not reproduce it in the READMEs you write — apply it. ## The funnel Name → one-liner → (background if the domain is unfamiliar) → **usage, runnable** → install → API (or a link to it) → caveats → contributing → license. - Each layer should let a reader short-circuit: "not for me" in 30 seconds is a success, not a failure. - Install/API order depends on what the thing is. For libraries whose value *is* the API, readers vet the API before they bother installing: usage → API → install (the article's original order). For apps, CLIs, and out-of-the-box tools that expose no external API, install/setup comes right after usage, and the API section may not exist at all. - Non-permissive license (AGPL/SSPL/…): badge or note at the **top**, full text at the bottom. License incompatibility is the fastest disqualifier; do not bury it. - Images that carry critical information must live in the repo, not on an external host — the README outlives the host. ## Audit before rewriting Read the current README top to bottom and score it against the funnel. Failure modes seen in real audits: - **Audience mixing.** Maintainer content (release runbooks, CI secrets tables, repo-structure trees, debug guides) interleaved with consumer content. This is the most common and most damaging pattern. - **Funnel collapse.** Adapter/internals detail in the first 50 lines, before the reader knows whether the tool is for them. - **Duplication.** The same fact (Node version, incremental rebuilds, runtime details) stated two or three times. Keep one statement, at the shallowest layer where a consumer needs it. - **One-tool-centric framing.** A table or section written when the project supported one tool, still leading with that tool's specifics after it supports ten. Verify the truth against the code — the old text may be not just biased but *wrong* (missing entries, superseded semantics). - **Staleness.** Dead relative links, version ranges that drifted ("ADRs 0001–0006" when 0015 exists), references to deleted files. - **Unlinked API docs.** Detailed reference exists in the repo but the README never links it. ## Pre-flight checks (do these before editing anything) 1. **`git status` first.** Never overwrite files in a dirty worktree — the README may carry the owner's uncommitted work. If the tree is dirty, work in a fresh worktree off `origin/main`; that also keeps the PR free of unrelated changes. 2. **Diff the branch against `origin/main`.** READMEs drift between branches. Base the rewrite on what main actually says today, not on the checkout. 3. **Grep tests and CI for `README`/`CONTRIBUTING` strings.** Projects pin doc content in tests: exact headings, file lists, required phrases. Know what is pinned *before* restructuring — otherwise CI fails after the rewrite. 4. **Check for derived documents.** Packaging READMEs, website copies, or generated docs that duplicate the README may need the same treatment or a deliberate out-of-scope note. ## Rewriting rules - Consumer content only, in funnel order. Maintainer procedures **move** to `CONTRIBUTING.md` or `docs/` — moved, not deleted — with a pointer link left behind. - One home per fact. If a detail now lives in a reference doc, link it; do not also summarize it at full length. - Usage section = the actual interaction shape (real commands/prompts/code), copy-pasteable. Show CLI invocations with output when the project is a CLI. - Compress deep detail into tables (consumers pattern-match tables faster than prose); push the prose version to the reference doc and link it. - Every factual claim you carry forward, re-verify against the code. Never copy the old README's claims on faith. - **When tests pin wording:** reshape the test to assert the *requirement* (ordering of two install paths, presence of a link) instead of the document's shape (exact heading strings, a file list). Most contributing guides require justifying changed assertions in the PR description — write that section. Do not silently weaken a test to make the docs pass. - **Author preferences beat checklist purity.** Decorative elements the author likes (star-history charts, badges, wordmarks) stay unless the author explicitly agrees to cut them. Ask before deleting anything purely decorative; the checklist serves the author, not the reverse. ## Translated READMEs - **意译, not 直译.** Rewrite in the target language's tech-writing rhythm; restructure sentences freely. Sentence-by-sentence mapping always produces translationese ("索引进", "服务两类读者", "综合缓存"). - Keep terms in English where the community actually uses English (provider, agent, session, tool call). Translate what has a real native term. - Mirror structure exactly: same sections, same tables, same links, same heading count — parity must be mechanically checkable. - Cross-link at the top of both files (`English · 中文`). - Match the product's voice. If the product's own examples are colloquial, the README may be too ("用人话回答"). - Chinese section anchors change when headings do — update in-file anchor links to match the new headings. ## Verification before delivery - Check every relative link and asset resolves (a quick script over `](…)`, `src=`, `srcset=` targets is enough). - Run every test that reads the README or CONTRIBUTING — not just the suite you expect to matter. - Re-read the final README as a stranger, top to bottom, and note where you would bail. If the bail points come in the wrong order, the funnel is wrong. - Report the change as decisions: what moved where, what was dropped and why, which assertions changed. A README rewrite reviewed as prose diff is hard to approve; reviewed as a decision list it is easy.