readme-generator

README Generator

Generate high-quality README documents from codebase evidence, with clear structure, runnable commands, and maintenance rules.

Core Rules

• Base every statement on repository evidence (files, code, scripts, workflows, configs).
• Keep internal workflow reporting out of the README body. Evidence maps, scorecards, and verification state belong in the assistant response — see §Command Verifiability Gate.
• Exclude local/private tooling folders by default (for example .codex/) unless asked.
• Keep naming and paths consistent with the real repository layout.
• Treat top-level README.md as a user-facing homepage first, a maintainer reference second.

Evidence Precedence (resolves "omit or mark?")

One rule, applied by section class — there is no third case:

Facts vs Results (resolves "is this command fabricated?")

A manifest proves a toolchain; only an artifact proves a result.

• Evidence-backed: go test ./... when go.mod exists, pytest when pyproject.toml exists, make <target> when that exact target is in the Makefile.
• Not evidence-backed: coverage percentages, test counts, benchmark numbers, throughput, latency, or a response body — unless the repo commits the artifact they come from (a checked-in benchstat output, a golden fixture, a committed coverage report).
• A config file proves a target, never a measurement. .codecov.yml with target: 80% licenses "the coverage target is 80%", not "coverage is 80%" — the latter asserts a result the repo does not record. The linter enforces that split.
• If a repo has a manifest but no test files, still show the toolchain command and add No test files found in repo — the command is real, the coverage claim would not be.

Quick Reference

Pre-Generation Gates (Mandatory)

1) Audience and Language Gate

Decide target readers (contributors / operators / API consumers / end users) and output language (Chinese / English / bilingual). If unspecified, follow the existing repo docs and keep audience assumptions in working notes, not in the README. This gate also owns the lightweight decision (§Project Type Routing).

2) Project Type Routing

Two independent questions, two sources:

project_type detected classifies the repo as Service, Library, CLI, or Monorepo, and is kept alongside effective so a lightweight promotion does not erase what the project structurally is. It does not choose the command snippets — a Go CLI and a Node CLI share a type and share no commands.

effective is the single answer — generation, the Output Contract, and scripts/lint_readme.py all read it, so they cannot disagree.

Discovery never promotes to lightweight on its own. It reports lightweight_eligible plus a named lightweight_blocked_by list (5+ dirs · CI present · deployment surface · public distribution surface · unclassified). Promotion is your call at the Audience Gate, because the deciding trigger — audience is internal contributors only — is a judgement no probe can make. Inferring it was harmful: a minimal public Go SDK (go.mod + pkg/, no CI, few dirs) was silently downgraded and lost Installation and API. Absence of CI is not evidence of absence of users, and a library is a public surface by definition. When the Gate does establish an internal audience on an eligible repo, record it with lint_readme.py --type=lightweight and report lightweight in the Output Contract.

Routing logic lives in scripts/discover_readme_needs.sh — it reads Go, Node, Rust, and Python manifests, workspace markers (go.work, apps/, packages/, npm workspaces, Cargo [workspace]), and entrypoint locations. Change prose and script together; sync is guarded by scripts/tests/test_discovery_script.py::TestRoutingSync.

3) Evidence Completeness Gate

Run discovery first and read its verdict — do not re-derive these by hand:

bash "<path-to-skill>/scripts/discover_readme_needs.sh"

Minimum evidence: at least one entrypoint (the script emits an inventory), a determined project type, a located command source. verdict status DEGRADED names which is missing. When degraded: output Project Overview plus Not found in repo sections only, set degraded: true in the response, and list each missing item with a suggested resolution.

4) Badge Detection Gate (Mandatory)

Scan for badge evidence before drafting: CI workflow files (an empty .github/workflows/ is not evidence), coverage config, language version, license file. Add a badge only when its evidence exists. Record the outcome in badges_added.

5) Command Verifiability Gate

Hard rule, no exceptions. Verification-state language — Verified, Not verified, not executed in this environment, PASS/FAIL, scorecard output, degraded: true — never appears inside README.md; it belongs in the assistant response. This holds even when the user asks for a "verification table": produce it in the response and say why it is not in the file, because the label goes stale the moment it is committed. Inside the README, write evidence-backed install/run commands plus prerequisites.

Badge Strategy

Detection order, which is also render order: CI status → Coverage → Language version → License → Release.

Only emit badges whose URL is derivable from repo evidence. For a private repo, skip the external URLs and add: Badge note: repository is private; external badge URLs may not render outside authorized viewers. → URL templates and the community-file mapping: references/badges-and-governance.md.

Community and Governance Files

Detect LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md; link each present file from the matching section. License is the one exception to §Evidence Precedence — an absent license is itself information, so the section never just disappears: present → name it; absent → License: Not found in repo — consider adding a LICENSE file. Only Lightweight mode on an internal repo omits it. Every other governance file follows the normal optional rule. → references/badges-and-governance.md.

Key Evidence Targets

Scan before drafting; absent targets are recorded per §Evidence Precedence, never guessed.

Command Priority

Makefile target → language-native manifest (go.mod, package.json, pyproject.toml, Cargo.toml) → CI workflow command → direct tool invocation.

Every command must resolve against one of these — a make target absent from the Makefile is a fabrication, and each half of make test && make deploy is checked separately, as is anything behind sudo/VAR=x. On conflict, load references/command-priority.md.

Structure Policy

Required sections are per project type, not one flat list. A Library README carrying a Configuration section, or a CLI README carrying Deployment, is noise.

Every type opens with an overview: name, one-sentence value proposition, then badges when evidence exists. Missing a primary section (Quick Start / Installation / Usage / Repository Overview, per type) is a Critical defect; missing any other required section is Standard — lint_readme.py reports them as R009 and R012 respectively.

Sections and commands are separate axes (§Project Type Routing). This matrix is the same table lint_readme.py enforces (REQUIRED_SECTIONS), kept in sync by test_forward_eval.py::RequiredSectionSyncTest.

For public homepages, order the top of the file: value proposition → highlights → prerequisites → install → quick start → end-to-end example → reference sections.

Optional Sections (include only when evidence exists)

Architecture / data flow · Deployment / operations · API usage examples · Release and versioning · Contributing · Security notes · Contact and support. Missing evidence means omit — see §Evidence Precedence. License is deliberately not on this list (§Community and Governance Files).

Lightweight Template Mode

Triggers: fewer than 5 top-level functional directories · no deployment/ops workflows in the repo · no public API/SDK surface · README targets internal contributors only. Discovery reports the first three as lightweight_eligible; the fourth is yours to assert (§Project Type Routing). Required sections: Project overview, Quick start, Common commands, Project structure (short), Testing and quality checks, Documentation maintenance note. Skip heavy optional sections unless explicitly requested.

Chinese / Bilingual README Guidelines

Keep English for package names, commands, file paths, environment variables, and precise technical identifiers; translate headings and prose. Never use double-language headings (## Quick Start / 快速开始) — prefer ## 快速开始, ## 项目结构, ## 常用命令. In bilingual mode Chinese is the primary prose with English technical terms inline. → references/bilingual-guidelines.md for the full rules.

README Navigation Rule

• Keep a compact ToC for long, reference-shaped READMEs; omit it when the file is scannable without scrolling. Never delete a useful existing ToC just to shorten.
• Size: 7–10 entries max for a simple CLI or library. Exclude architecture internals, contributor-only sections, and anything that is not a direct action step for the primary audience — they stay in the body.
• Label consistency: every ToC entry's text must match the ## heading it links to.

Monorepo Rules

Repository overview table instead of a deep tree dump · link to submodule READMEs rather than duplicating internals · document shared root commands only · missing root LICENSE → Not found in repo, never guessed inheritance. Load references/monorepo-rules.md first.

End-to-End Example Rule

For CLI tools, converters, and generators, show one complete example: the input command, then the resulting file name or response shape. No-fabrication constraint: with no sample output, fixture, or documented response format in the repo, show the invocation and describe the destination generically — never an invented JSON body, row count, or status line: schema-gen generate --output ./schemas ./internal/models # → writes to ./schemas/

Anti-Examples (BAD / GOOD Markdown Pairs)

The most common failure is process-state labels in the README body — a ## Testing — Status: Not verified heading, or a | Command | Verified | table. The rule is absolute (§Command Verifiability Gate); the worked BAD/GOOD pair, plus fabricated badges, guessed config, unbacked metrics, monorepo tree dumps, double-language headings, and output-without-input, are all in references/anti-examples.md. Load it before refactoring an existing README.

Generation Workflow

1. Detect audience — end users, contributors, operators, or mixed.
2. Detect language — English, Chinese, or bilingual.
3. Run discovery — scripts/discover_readme_needs.sh; read verdict and entrypoints.
4. Collect evidence — entrypoints, Makefile, manifests, workflows, config, existing docs.
5. Route — template from project_type effective, commands from the manifest.
6. Choose command source — apply Command Priority; resolve conflicts before drafting.
7. Load references selectively — template, snippets, golden example, checklist, rules.
8. Draft sections — from evidence, in homepage-first reader order.
9. Calibrate — ToC, badges, end-to-end example, optional sections.
10. Polish — remove process wording, duplicate headings, guessed config, filler.
11. Self-check — python3 "<path-to-skill>/scripts/lint_readme.py" <repo-dir> <readme-path>; fix every critical finding before returning.
12. Return the output contract — evidence mapping, scorecard, degraded flag, omissions.

Refactor Mode (Existing README)

Preserve valuable prose, fix contradictory commands, replace guessed content, re-evaluate the project type, re-run the scorecard. Load references/checklist.md for the refactor checklist and the update-trigger matrix that detects staleness after code changes (new entrypoint, env var, Makefile target, CI workflow, LICENSE, Go version, and the rest).

Output Style

Short, direct prose; fenced blocks for trees and commands; no internal rubric language. Notes about why a section looks the way it does belong outside the document.

Evidence Mapping Output (Required)

Output this in the assistant response, not inside the README. Every non-trivial section maps to at least one evidence source, or to Not found in repo; one line per section.

Output Contract (Mandatory Fields)

Machine-Readable Summary (JSON)

{
  "project_type": "service", "language": "zh", "template_used": "Template A: Service",
  "degraded": false,
  "scorecard": {"critical": "3/3", "standard": "5/5", "hygiene": "3/3"},
  "machine_result": "PASS", "final_result": "PENDING_HUMAN_REVIEW",
  "unchecked": ["C4", "S6", "H4"],
  "badges_added": ["CI", "Coverage", "Go Version", "License"],
  "sections_omitted": [], "missing_evidence": []
}

Denominators are applicable items; scripts/lint_readme.py emits this block.

README Quality Scorecard (3-Tier)

Critical Tier — any FAIL means the whole output FAILs:

Standard Tier — items that do not apply leave the denominator:

Scoring is passed / applicable; the bar is two thirds of applicable, rounded up — the old 4/6 and 3/4 expressed so they survive items dropping out. (Why: a Library has no Structure section, must not invent Configuration, and cannot show a lint command for a repo with no linter — against a flat six-item list it lost three automatically and scored 3/6.) S4 judges what a target runs, not what it is named: make check-types running tsc --noEmit is not a test command.

Hygiene Tier — same passed / applicable rule; H4 needs a human and is excluded:

Output: Critical: X/N | Standard: X/N applicable | Hygiene: X/N applicable → machine …; final …. Name the N/A items and those needing a human, so a shrinking denominator stays visible. machine_result and final_result are separate: C4 (routing), S6 (audience) and H4 (optional-section gating) are the three a script cannot settle, and C4 is Critical. So a clean machine run is machine_result: PASS + final_result: PENDING_HUMAN_REVIEW, becoming a real PASS only once you have judged those three. A machine FAIL stays FAIL — "pending" never softens a failure.

scripts/lint_readme.py computes the whole card and checks the high-frequency violations: undefined make/npm targets (including behind sudo/VAR=x prefixes and on each half of a && chain), env vars absent from .env.example, non-existent paths, placeholder residue, metrics with no committed artifact, unevidenced badges, missing required sections, ToC/heading mismatches, process labels. It also asserts every shipped golden example clears its own tier.

It is a floor, not the tier. A linter-clean README can still fail C1/C2 — a plausible but wrong claim, a command that exists yet does the wrong thing, a structure description that is stale rather than invented. Read it as "no detectable fabrication", then judge the three UNCHECKED items yourself.

Load References Selectively

Run scripts/discover_readme_needs.sh first (workflow step 3) to collect repo facts deterministically, and scripts/lint_readme.py last (step 11) to check the draft against those same facts. Skill regression: bash "<path-to-skill>/scripts/run_regression.sh".