/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
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 Progress 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.

**A README is a `newcomer` document.** Its reader has never seen this project, so the test for every candidate section is whether that reader needs it before they can install and run one thing. Rationale, alternatives considered, and internals are `expert` material: extract them to `docs/deep-dive/<topic>.md` or the `book/`, linked from the README in one line naming who the page is for. Never delete them to shorten the README. Tier table and cut test: `scribe:slop-detector` module `audience-targeting.md`.

A README that declares a different tier (an internal tool whose only readers already run it) says so in its lead.

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 (`rg -n '^#' README.md`)

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.

• Keep only the sections that earn a place in an index: a

one-line value proposition, one install path, a compact command or unit table, a short "what's inside" summary, a single Documentation link section, and metadata (requirements, contributing, license) last. For every other candidate section ask: **does this belong in the README, or behind a link?**

• Default to linking out. Send deep architecture, FAQ,

roadmap, changelog, alternate install methods, and per-unit detail to their own pages. Per-unit docs live with the unit (hub-and-spoke), never duplicated in the root.

• Order signals priority: title and tagline first, then

install, then the index table, then a short feature summary, then Documentation links, with housekeeping (requirements, contributing, license) last.

• Map internal documents (docs/, book/, specs/, commands/) to

the section that links them, so the README anchors depth without restating it.

**Soft budget**: a marketplace or collection root README runs roughly 150-400 lines of prose plus any index table. A section that grows over time (roadmap, FAQ, changelog) belongs in a linked page, not the README.

Step 4 - Apply Edits (`update-readme:edits-applied`)

• Implement the new structure directly in `README.md`

(or the specified file).

• Follow `Skill(leyline:markdown-formatting)` conventions:

wrap prose at 80 chars (prefer sentence/clause boundaries), blank lines around headings, ATX headings only, blank line before lists, reference-style links for long URLs.

• Maintain concise, evidence-based prose; avoid marketing fluff.
• Prefer deletion and linking over inlining. If a section

duplicates a docs page, cut it and link the page; if it grows over time, move it out of the README entirely.

• Add comparison tables, feature lists, or diagrams only if

they originate from current repository assets (no speculative content).

• When referencing algorithms or performance claims, point to

benchmarks or tests within the repository or documented math reviews.

Step 4.5 - AI Slop Detection (`update-readme:slop-scanned`)

Run `Skill(scribe:slop-detector)` on the updated README to detect AI-generated content markers.

Scribe Integration

The scribe plugin provides AI slop detection:

Skill(scribe:slop-detector) --target README.md

This detects:

• **Tier 1 words**: delve, tapestry, comprehensive, leveraging, etc.
• **Phras