--- name: write-readme description: Write or review a project README.md in plain technical-writer prose — problem it solves and doesn't, honest assessment of tested vs untested, trade-offs, prior art, organization, and usage. Use when the user says "write a README", "improve/review the README", "document this project", or a new project/repo lacks a README. argument-hint: [path to project or existing README] --- # write-readme — project READMEs in technical-writer prose Every project and repository gets a README.md written for the *user* of the project, not its author. The measure of success: a reader of any background can decide **whether this project is appropriate for them** and, if so, **how to use it effectively** — without reading the code or asking anyone. ## Voice and language (non-negotiable) - Write as a technical writer, not a marketer and not the proud author. - **Complete sentences.** No fragments, no note-style bullets that assume context. - **No jargon.** Every unfamiliar term is defined at first use or replaced with a plain phrase ("a YAML header that holds the item's state", not "frontmatter"). Expand every acronym once before using it. - **No marketing language.** Ban superlatives ("blazingly fast", "powerful", "simple yet flexible") and unfalsifiable claims. State measurable facts; let the reader judge. - Active voice, present tense. Say who does what: "the script rebuilds the index", not "the index is rebuilt". - Consistent terminology: pick one name per interface and never alternate synonyms. ## Required content Cover each of these. Order below is the recommended reading order — motivation before mechanics, honesty before installation. 1. **What it is** — one or two sentences a stranger understands with zero context. Name the audience ("for developers who…"). 2. **What problem it solves** — the concrete failure or pain that exists without it. A reader who does not have this problem should realize it here and stop reading, satisfied. 3. **What problem it does NOT solve** — explicit non-goals and out-of-scope needs. This prevents misuse and disappointed adopters, and it is the section most READMEs are missing. 4. **Show the thing early** — a small, real example (input and output, a short session, or a screenshot for visual tools) before any long prose. Readers evaluate artifacts, not descriptions. 5. **How to use it** — prerequisites stated exactly (language versions, OS, accounts), installation commands that have actually been run, and the shortest path to a first success. Include a way to verify the install worked. 6. **Trade-offs** — what was deliberately given up and why (e.g. "no dependencies, so the parser is naive and the schema must stay flat"). Every design buys something by paying something; say both sides. 7. **Known and tested vs. untested** — separate what is demonstrated (with dates, versions, or test evidence) from what is intended, hoped, or unproven. Use absolute dates ("extracted 2026-07-18"), never "currently" or "as of this writing" — those rot silently. 8. **Similar and related prior work** — name the closest existing tools, state honestly how this differs, and keep originality claims narrow. Not inventing the category is normal; pretending to is a credibility hole. Caveat comparisons that may go stale. 9. **How the project is organized** — a short map of the directories or files that matter (a table works well: path, purpose), so a reader can navigate without spelunking. 10. **Who it is for / who it is not for (yet)** — the reader should find themselves in one of these lists. 11. **License**, and where to get help or report problems if applicable. ## Additional principles - **The README is a front door, not a manual.** Link to deeper docs rather than inlining design essays, full API references, or change history. Aim for a document readable in five to ten minutes. - **Every claim must be verifiable against the project today.** Before finishing: run the install and usage commands (or trace them against the code), check version requirements against the actual source (e.g. syntax features imply a minimum language version), and confirm paths and filenames exist. A README that lies once is distrusted everywhere. - **Write for the skeptical evaluator.** The most valuable reader is deciding whether to adopt. Honest weaknesses ("built for a single writer; two branches filing concurrently will collide") build more adoption than hidden ones, because evaluators always find out. - **State maturity plainly.** Experimental, personal-use, production, abandoned — say which, and date it. If the project is two days old, say it is two days old. - **Prefer one concrete number to three adjectives.** "About 250 lines, no dependencies" beats "lightweight and minimal". - **Anti-patterns to remove on sight:** badge walls; feature lists with no problem framing; "simply"/"just" before nontrivial steps; install steps that skip prerequisites; screenshots or examples that no longer match the current behavior; TODO sections; empty boilerplate headings ("Contributing: TBD"). - **Maintenance rule:** the README changes in the same commit as any behavior it describes. A stale README is worse than a short one. ## Procedure 1. Read the project first: entry points, real commands, actual dependencies and minimum versions, directory layout, tests. Never write from the author's description alone — the code is the source of truth for every factual claim. 2. Ask (or infer from context) anything material you cannot determine: intended audience, maturity, license. Do not invent these. 3. Draft in the section order above. Cut any section that would be empty rather than padding it — but treat missing "does not solve", "untested", or "prior art" sections as gaps to research, not sections to skip. 4. Verify every command, path, version, and filename against the project. 5. Reread once as the target reader: could someone with no context decide, in five minutes, whether and how to use this? Fix whatever blocks that.