6.8 KiB
Clean up a repository README
Apply this task to one repository at a time. Read its local agent instructions, README, documentation tree, package metadata, and CI configuration before editing. Preserve unrelated work, follow the repository's commit policy, and do not push, trigger CI, or publish assets unless explicitly requested.
Establish the documentation contract
Treat the repository and its executable configuration as the source of truth. Before rewriting prose:
- identify the intended audience and the project's current purpose, support status, canonical owner and project name, default branch, and license;
- run or otherwise verify the shortest supported install, build, and usage path rather than copying stale commands;
- locate authoritative contributor, configuration, deployment, release, troubleshooting, security, and architecture documentation;
- inspect inbound links, relative links, anchors, badges, screenshots, and commands so useful references are not silently broken; and
- note content that is duplicated, obsolete, speculative, or too detailed for first-time readers.
Do not invent features, compatibility promises, commands, support channels, or publication state. Preserve legally or operationally required notices. Keep project-specific terminology where it is meaningful, and explain it before using unexplained abbreviations.
README structure
Make the README a concise entry point. Prefer this order when it fits the project, adapting or omitting sections rather than creating empty headings:
- project title and verified status badges;
- one short explanation of what the project does and who it is for;
- prerequisites and the smallest working installation or setup path;
- a minimal usage example with its expected result;
- links to configuration and task-oriented documentation;
- development and contribution commands; and
- license and support information.
Use descriptive link text and relative links for files within the repository. Keep heading levels ordered, use one term consistently for each concept, label code fences, and keep commands directly runnable from the stated directory. Avoid tables of contents for short READMEs, repeated navigation blocks, marketing filler, exhaustive option references, and prose that merely restates command output.
Preserve existing information until it is proven obsolete or has a clear new home. A shorter README is not successful if maintainers lose necessary operational knowledge.
Advanced documentation
Keep the basic install and first-use path in the README. When advanced material
makes that path hard to scan, move cohesive topics into the repository's
existing documentation structure. If no suitable structure exists and the
material justifies a separate page, create a small docs/ area following the
project's naming conventions and add an Advanced section to the README that
links directly to each new page.
Advanced topics can include architecture, uncommon configuration, production deployment, CI internals, release procedures, performance tuning, and detailed troubleshooting. Do not move essential prerequisites, safety warnings, or the only working example out of the README. Ensure moved pages link back or provide enough context to be usable when opened directly. Update all affected relative links and avoid creating placeholder pages.
Verify CI-backed badges
Determine whether the README is expected to show the current default-branch
version, test, and coverage badges. Resolve <asset-origin>, <owner>,
<project>, and <default-branch> from the canonical repository and CI
configuration, not merely from the checkout directory. Check these exact
public URLs after substitution:
<asset-origin>/coverage/<owner>/<project>/<default-branch>/version.svg
<asset-origin>/coverage/<owner>/<project>/<default-branch>/test.svg
<asset-origin>/coverage/<owner>/<project>/<default-branch>/coverage.svg
Verification must cover the complete path from generation to publication:
- inspect CI and tracked scripts to confirm all three SVGs are generated from authoritative version, test, and coverage results;
- confirm CI validates the files as regular and nonempty, archives exactly the intended badges, and publishes them only from the default branch to the path represented by the public URLs;
- check that the default branch, owner, project, filenames, asset mount, and public origin agree across CI, scripts, server documentation, and README;
- if network access is available, request each public URL, require a successful response with SVG content, and parse it as XML; distinguish a live but stale badge from a missing, invalid, or unpublished badge; and
- verify badge alt text is meaningful and place the three badge images directly below the README title without linking them to a report CI does not retain.
Do not treat the presence of a README image URL, a workspace SVG, or an archive pattern as proof that CI publishes the badge. Do not claim the public badges are live until a successful default-branch build has generated and published all three and their public responses have been checked.
If the project intentionally provides these badges and the existing pipeline
is incomplete, make the smallest in-scope correction when it is straightforward
and verify it. For a missing or materially broken badge pipeline, apply
ci-coverage-badges.task.md as a separate logical
change instead of embedding a large CI redesign in the README cleanup. Until
publication is verified, remove or clearly avoid introducing broken badge
images and report the exact gap.
Verification
Before committing:
- render or preview the README and every new documentation page;
- check local links, anchors, image references, and code-block formatting with the project's Markdown tooling when available;
- run every changed quick-start and development command that is safe and locally reproducible, and state which commands could not be exercised;
- search for stale references to renamed or moved headings and files;
- verify the three badge generation and publication paths as described above, recording whether the public URL check was performed or unavailable;
- inspect the diff for lost information, accidental reflow, project identifiers copied from examples, secrets, and unrelated edits; and
- commit the README, any moved documentation, and directly related fixes as focused, reviewable changes.
Report the final README organization, documentation moved or removed, commands and links checked, the status of each expected badge URL, the commit ID, and any CI or network verification that remained unavailable.