update-readme

name	update-readme
description	Refreshes README structure favoring concision (an index, not a manual). Use when the README needs a structural update after significant project changes.
alwaysApply	false
category	artifact-generation
tags	["readme","documentation","exemplars","research","structure"]
tools	[]
complexity	high
model_hint	deep
estimated_tokens	1200
modules	["modules/language-audit.md","modules/exemplar-research.md"]
progressive_loading	true
dependencies	["sanctum:git-workspace-review","imbue:proof-of-work","scribe:slop-detector","scribe:doc-generator"]

README Update Workflow

When To Use

Use this skill whenever the README requires a structural refresh. Run Skill(sanctum:git-workspace-review) first to capture repo context and diffs.

When NOT To Use

• Updating inline docs: use doc-updates
• Consolidating ephemeral reports: use doc-consolidation

Required TodoWrite Items

1. update-readme:language-audit
2. update-readme:exemplar-research
3. update-readme:outline-aligned
4. update-readme:edits-applied
5. update-readme:slop-scanned - AI marker detection via scribe
6. update-readme:verification-reporting

Step 1 - Language Audit (update-readme:language-audit)

• Confirm pwd, git status -sb, and the baseline branch for reference.
• Detect dominant languages using repository heuristics (manifest files, file counts).
• Note secondary languages that influence documentation (e.g., a TypeScript frontend and a Rust backend) so the README can surface both.
• Record the method and findings.

See modules/language-audit.md for detailed detection patterns and commands.

Step 2 - Exemplar Research (update-readme:exemplar-research)

• For each primary and secondary language, use web search to locate high-quality READMEs (star count, recency, maintainer activity).
• Capture 2-3 exemplar repositories per language and summarize why each is relevant (section order, visuals, quickstart clarity, governance messaging, math exposition, etc.).
• Store citations for every exemplar so the final summary references them explicitly.

See modules/exemplar-research.md for search query patterns and evaluation criteria.

Step 3 - Outline Alignment (update-readme:outline-aligned)

The README is an index, not a manual. Lead with what the project is, how to install it, and a scannable table of its units (plugins, commands, packages); link out for everything else. When this repo's root README was simplified in 2026, it dropped from 435 to 200 lines (65% fewer words) by deleting inlined depth and linking to book/ instead. Aim for that shape, not a section-by-section coverage sweep.

• Compare current README headings () against the exemplars from Step 2. Lean marketplace and CLI-tool READMEs (asdf-vm/asdf-plugins, ohmyzsh/ohmyzsh, ryoppippi/ccusage) are index-shaped: prose intro under ~500 words, a unit table doing the work, depth behind links.