Readme craft

README Craft

Create a public README that is factual, visually deliberate, easy to scan, and complete enough for a new reader to act.

Core workflow

1. Inspect before writing

Inspect the repository, current README files, license, releases, workflows, package metadata, entry points, examples, and recent history.

• Derive facts from files and commands before asking the user.
• Ask only for a choice that cannot be discovered and would materially change the result.
• Treat the current owner, repository name, product name, supported platforms, versions, and installation commands as facts that require evidence.
• Separate verified facts, uncertain claims, and excluded claims in working notes.
• Preserve user changes already present in the worktree.

2. Establish scope

Choose the README sections from the project type and available evidence.

Always consider:

1. centered hero
2. two balanced badge rows
3. three concrete pain points
4. one value statement and one short flow line
5. section navigation
6. language navigation when localization is in scope
7. project-specific evidence, usage, boundaries, and structure

Use the project’s real vocabulary. Avoid generic feature lists when the repository exposes stronger artifacts such as research results, generated files, safety guarantees, or a reproducible workflow.

Read references/visual-system.md before designing the hero, badges, tables, icons, or Mermaid diagrams.

3. Write the default-language README

Start from templates/README.md.example and remove sections that lack evidence.

• Lead with the project outcome and audience.
• Keep the hero compact enough to fit the title, tagline, badges, pain box, value statement, navigation, and languages without excessive whitespace.
• Make every badge factual and link it to evidence or a useful destination.
• Include a meaningful red badge for a real boundary, risk, unsupported mode, or safety behavior.
• Put executable installation and usage paths before detailed explanations.
• State limitations with the same specificity as strengths.
• Keep tables to four columns or fewer whenever possible.
• Avoid prose about the README’s inspiration, alignment target, writing process, or visual reference.

4. Design compact Mermaid diagrams

Use Mermaid only when a relationship or sequence becomes clearer visually.

• Prefer flowchart LR for README workflows.
• Target three to four horizontal lanes and five to six columns for multi-track flows.
• Convert large fan-outs into meaningful horizontal stages when the stages have a defensible order.
• Group related outcomes into one node when grouping preserves meaning.
• Preserve separate nodes when each one represents a decision, guardrail, or independently useful artifact.
• Use explicit light fills, strokes, and color:#000 for dark-mode legibility.
• Keep one red node when the flow contains a real cost, failure, conflict, or guardrail.
• Use font-size:12px when a wide diagram needs visual parity with nearby README diagrams.
• Render the result; source inspection alone cannot prove the final size.

5. Localize completely

Preserve the repository's established localization paths. For a new repository, use this layout when the user requests the complete language set:

README.md
docs/lang/README_ZH.md
docs/lang/README_ES.md
docs/lang/README_DE.md
docs/lang/README_JA.md
docs/lang/README_RU.md
docs/lang/README_PT.md
docs/lang/README_KO.md

Keep every page structurally equivalent:

• identical badge count and destinations
• equivalent sections, tables, code blocks, and Mermaid topology
• complete eight-language navigation including the current page
• root-relative links adjusted for docs/lang/
• natural translations of prose and diagram labels
• unchanged commands, filenames, package names, and code identifiers

6. Protect accuracy and privacy

Before publication:

• verify every version, release, CI, license, support, safety, and performance claim
• scan the current tree for old repository names, old account names, personal emails, local user paths, temp paths, tokens, and copied private examples
• replace private paths with neutral placeholders only when the path is incidental to the example
• preserve research caveats, model limitations, failed experiments, and measurement boundaries
• leave Git history unchanged unless the user separately authorizes history rewriting

7. Validate and visually inspect

Read references/verification.md before final validation.

Run the bundled validator:

python scripts/validate_readme.py .

Then complete the checks that require real rendering:

1. render every README through GitHub Markdown or an equivalent GFM renderer
2. render Mermaid diagrams with Mermaid CLI when geometry matters
3. inspect the README at a consistent desktop viewport, normally 1200 × 900
4. compare diagram height, badge balance, language wrapping, icon compatibility, and control overlap
5. rerun link, anchor, privacy, and worktree checks after the final edit

8. Publish within scope

Respect the user’s requested workflow and the repository’s established branch strategy.

• Stage only the README and support files changed for this task.
• Commit and push when publication is explicitly requested or already established for the active repository task.
• Report the commit, remote verification, and checks that prove completion.
• Leave a clean worktree when the task owns all pending changes.

Decision rules

• Prefer repository evidence over existing README claims.
• Prefer a small complete diagram over a large exhaustive diagram.
• Prefer verified caveats over promotional adjectives.
• Prefer independent language files over a very long bilingual root README.
• Prefer stable icons such as 📣 and 📌; avoid title icons that render inconsistently on GitHub.
• Preserve naming consistency exactly, including lowercase and hyphenation.
• Keep source facts and presentation changes in the same review pass so visual polish does not hide factual drift.

Resources

• templates/README.md.example: adaptable README skeleton
• references/visual-system.md: hero, badge, table, icon, multilingual, and Mermaid rules
• references/verification.md: evidence, privacy, link, rendering, and publication checks
• scripts/validate_readme.py: deterministic local validator

Output contract

Deliver:

1. the updated README set
2. any support resources required by those READMEs
3. a concise statement of verified facts and known limitations
4. validation evidence, including visual QA when layout changed
5. publication status and commit identifier when changes were pushed