/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 (`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.
• **Phrase patterns**: "In today's fast-paced world", "cannot be overstated"
• **Structural markers**: Excessive em dashes, bullet overuse, sentence uniformity
• **Marketing language**: "enterprise-ready", "cutting-edge", "seamless"

Remediation

If slop score exceeds 2.0 (moderate), apply `Skill(scribe:doc-generator)` principles:

1. Ground every claim with specifics 2. Remove formulaic openers/closers 3. Use numbers, commands, filenames over adjectives 4. Balance bullets with narrative prose 5. Show authorial perspective (trade-offs, reasoning)

For significant cleanup needs, use:

Agent(scribe:doc-edi