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

Required TodoWrite Items

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 )

Compare current README headings (rg -n '^#' README.md ) against patterns observed in exemplars.
Draft a target outline covering: value proposition, installation, quickstart, deeper usage/configuration, architecture/feature highlights, performance or math guarantees, documentation links, contribution/governance, roadmap/status, and licensing/security notes.
validate internal documents (docs/, specs/, wiki, commands/) are mapped to the relevant sections so the README anchors them with context-sensitive links.

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

(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.
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:

Remediation

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

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 reflects a modern, language-aware structure, referencing both internal docs and external inspiration 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

Source Transparency