Update Readme

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-editor) --target README.md

Step 5 - Verification & Reporting (update-readme:verification-reporting)

• Re-read the updated README for clarity, accessibility (section lengths, bullet balance), and accurate links.
• Run git diff README.md (or the edited file) and capture snippets for the final report.
• Summarize detected languages, exemplar sources (with citations), key structural decisions, and follow-up TODOs (e.g., add badges, upload diagrams).

Exit Criteria

• [ ] All TodoWrite items are complete.
• [ ] The README is index-shaped: prose intro within the soft

budget (roughly 150-400 lines plus any unit table), one install path, and a scannable unit/command table.

• [ ] No README section duplicates a book/ or docs/ page;

depth is linked, not inlined (rg -n '^#' README.md headings each map to a section that earns a place in an index).

• [ ] The README references internal docs and external

exemplars with citations.

• [ ] Research notes and command references are captured so

future reviewers can reproduce the process.

Troubleshooting

Common Issues

Documentation out of sync Run make docs-update to regenerate from code

Build failures Check that all required dependencies are installed

Links broken Verify relative paths in documentation files

Exemplar Research Patterns

Detailed patterns for finding, evaluating, and documenting high-quality README exemplars.

Web Search Query Patterns

Language-Specific Queries

"GitHub [language] README best practices"
"[language] framework README examples"
"[language] project README badges"
"[language] library documentation structure"
"awesome [language] README"

Framework/Domain-Specific Queries

"[framework] README structure"
"[domain] project README examples" (e.g., "CLI tool README examples")
"[language] [project-type] documentation" (e.g., "Rust async library documentation")

Quality Indicators

"high star count [language] README"
"well-maintained [language] project README"
"[language] project documentation best practices 2024"

Exemplar Evaluation Criteria

Assess each candidate README using these dimensions:

Structure & Organization

• Section order: Does it follow a logical progression (value → quickstart → details)?
• Progressive disclosure: Are complex topics deferred until after basics?
• Table of contents: Is it present and well-structured?
• Visual hierarchy: Clear heading levels, spacing, readability?

Content Quality

• Value proposition: Clear statement of what the project does and why it matters?
• Quickstart clarity: Can a new user get started in <5 minutes?
• Code examples: Are they runnable, realistic, well-commented?
• Installation steps: Clear, tested, platform-aware?

Technical Communication

• Accuracy: Does it match the actual codebase capabilities?
• Completeness: Coverage of installation, usage, configuration, troubleshooting?
• Governance messaging: Clear contribution guidelines, roadmap, support channels?
• Math/algorithm exposition: For technical projects, is the theory well-explained?

Maintenance Signals

• Recency: Last commit within 6 months?
• Star count: Indicator of community validation (>500 stars preferred)
• Maintainer activity: Active issue responses, recent releases?
• CI/CD badges: Evidence of automated quality checks?

Citation Format

Record each exemplar with full attribution:

### Exemplar: [Project Name]
- **URL**: https://github.com/[org]/[repo]
- **Language**: [Primary language]
- **Stars**: [count] (as of [date])
- **Last Updated**: [date]
- **Relevant Patterns**:
  - [Pattern 1]: [Description and why it's relevant]
  - [Pattern 2]: [Description and why it's relevant]
  - [Pattern 3]: [Description and why it's relevant]
- **Specific Elements to Adapt**:
  - [Element]: [How it applies to this project]

Storage Recommendations

Temporary Research Notes

Store research findings in a temporary file during the session:

# Create research notes file
cat > /tmp/readme-research.md << 'EOF'
# README Exemplar Research

## [Language 1] Exemplars
[Citations...]

## [Language 2] Exemplars
[Citations...]
EOF

Final Report Integration

Include exemplar citations in the final verification report so future maintainers can:

• Understand the design decisions
• Revisit the sources for updates
• Validate the approach against current best practices

Example Multi-Language Research

For a project with Rust backend and TypeScript frontend:

1. Rust Exemplars (2-3 projects)

• Focus on: CLI tool patterns, installation via cargo, feature flags, performance claims

2. TypeScript Exemplars (2-3 projects)

• Focus on: npm installation, dev environment setup, API documentation, framework integration

3. Full-Stack Exemplars (1-2 projects)

• Focus on: How to structure README for multiple runtimes, quickstart for both components, architecture diagrams

Quality Threshold

Minimum criteria for an exemplar to be useful:

• Must have >100 stars OR be from a recognized organization
• README must be >200 lines (substantial content)
• Must have been updated in the last year
• Must demonstrate at least 3 structural patterns relevant to the target project

Language Audit Patterns

Detailed patterns and commands for detecting project languages and their documentation implications.

Manifest File Detection

Check for language-specific manifest files to identify the primary language(s):

# Rust
ls -1 Cargo.toml 2>/dev/null

# Node.js/TypeScript
ls -1 package.json 2>/dev/null

# Go
ls -1 go.mod 2>/dev/null

# Python
ls -1 pyproject.toml setup.py requirements.txt 2>/dev/null

# Java/Kotlin
ls -1 pom.xml build.gradle build.gradle.kts 2>/dev/null

# Ruby
ls -1 Gemfile 2>/dev/null

# PHP
ls -1 composer.json 2>/dev/null

File Count Analysis

Count source files by extension to determine language distribution:

# Rust
git ls-files | rg '\.rs$' | wc -l
# or for preview
rg --files -g '*.rs' | head -10

# Python
git ls-files | rg '\.py$' | wc -l
rg --files -g '*.py' | head -10

# Go
git ls-files | rg '\.go$' | wc -l
rg --files -g '*.go' | head -10

# TypeScript/JavaScript
git ls-files | rg '\.(ts|tsx|js|jsx)$' | wc -l
rg --files -g '*.ts' -g '*.tsx' | head -10

# Java
git ls-files | rg '\.java$' | wc -l
rg --files -g '*.java' | head -10

Language Priority Heuristics

Determine primary language using these priority rules:

1. Manifest presence: If a language-specific manifest exists, it's a strong signal 2. File count dominance: Language with >60% of source files is primary 3. Directory structure: Check for language-specific directories (src/, lib/, pkg/) 4. Build configuration: Presence of Makefile, CMakeLists.txt, or build scripts

Secondary Language Handling

Document secondary languages when they:

• Represent >20% of codebase
• Serve distinct architectural roles (e.g., Rust backend + TypeScript frontend)
• Have their own build/test infrastructure
• Require separate installation or runtime considerations

Example Multi-Language Documentation Strategy

## Installation

### Backend (Rust)
[Rust-specific instructions]

### Frontend (TypeScript)
[Node/npm-specific instructions]

Recording Findings

Capture the audit results in a structured format:

Language Audit Results:
- Primary: [Language] ([count] files, [manifest])
- Secondary: [Language] ([count] files, [manifest])
- Method: [manifest detection | file count | directory structure]
- Documentation implications: [single-language | multi-language sections needed]