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
update-readme:language-audit
update-readme:exemplar-research
update-readme:outline-aligned
update-readme:edits-applied
update-readme:slop-scanned - AI marker detection via scribe
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)
- 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)
- 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.
- 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:
- Ground every claim with specifics
- Remove formulaic openers/closers
- Use numbers, commands, filenames over adjectives
- Balance bullets with narrative prose
- 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 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
1---2name: update-readme3description: 'Run git-workspace-review first to capture repo context. Use when README4 requires structural refresh, adding features to documentation, aligning readme with5 exemplar standards, improving project presentation. Do not use when updating inline6 docs - use doc-updates. DO NOT use when: consolidating ephemeral reports - use doc-consolidation.'7category: artifact-generation8tags:9- readme10- documentation11- exemplars12- research13- structure14tools:15- Read16- Write17- Edit18- Bash19- WebSearch20- TodoWrite21complexity: high22estimated_tokens: 120023modules:24- language-audit25- exemplar-research26progressive_loading: true27dependencies:28- sanctum:shared29- sanctum:git-workspace-review30- imbue:proof-of-work31- scribe:slop-detector32- scribe:doc-generator33metadata:34 source: https://skillmd.com/skills/micsapp/update-readme35---3637# README Update Workflow3839## When To Use40Use this skill whenever the README requires a structural refresh.41Run `Skill(sanctum:git-workspace-review)` first to capture repo context and diffs.4243## When NOT To Use4445- Updating inline docs: use doc-updates46- Consolidating ephemeral reports: use doc-consolidation4748## Required TodoWrite Items491. `update-readme:language-audit`502. `update-readme:exemplar-research`513. `update-readme:outline-aligned`524. `update-readme:edits-applied`535. `update-readme:slop-scanned` - AI marker detection via scribe546. `update-readme:verification-reporting`5556## Step 1 - Language Audit (`update-readme:language-audit`)57- Confirm `pwd`, `git status -sb`, and the baseline branch for reference.58- Detect dominant languages using repository heuristics (manifest files, file counts).59- Note secondary languages that influence documentation (e.g., a TypeScript frontend and a Rust backend) so the README can surface both.60- Record the method and findings.6162See `modules/language-audit.md` for detailed detection patterns and commands.6364## Step 2 - Exemplar Research (`update-readme:exemplar-research`)65- For each primary and secondary language, use web search to locate high-quality READMEs (star count, recency, maintainer activity).66- Capture 2-3 exemplar repositories per language and summarize why each is relevant (section order, visuals, quickstart clarity, governance messaging, math exposition, etc.).67- Store citations for every exemplar so the final summary references them explicitly.6869See `modules/exemplar-research.md` for search query patterns and evaluation criteria.7071## Step 3 - Outline Alignment (`update-readme:outline-aligned`)72- Compare current README headings (`rg -n '^#' README.md`) against patterns observed in exemplars.73- 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.74- validate internal documents (docs/, specs/, wiki, commands/) are mapped to the relevant sections so the README anchors them with context-sensitive links.7576## Step 4 - Apply Edits (`update-readme:edits-applied`)77- Implement the new structure directly in `README.md`78 (or the specified file).79- Follow `Skill(leyline:markdown-formatting)` conventions:80 wrap prose at 80 chars (prefer sentence/clause boundaries),81 blank lines around headings, ATX headings only, blank line82 before lists, reference-style links for long URLs.83- Maintain concise, evidence-based prose; avoid marketing fluff.84- Add comparison tables, feature lists, or diagrams only if85 they originate from current repository assets (no speculative86 content).87- When referencing algorithms or performance claims, point to88 benchmarks or tests within the repository or documented math89 reviews.9091## Step 4.5 - AI Slop Detection (`update-readme:slop-scanned`)9293Run `Skill(scribe:slop-detector)` on the updated README to detect AI-generated content markers.9495### Scribe Integration9697The scribe plugin provides AI slop detection:9899```100Skill(scribe:slop-detector) --target README.md101```102103This detects:104- **Tier 1 words**: delve, tapestry, comprehensive, leveraging, etc.105- **Phrase patterns**: "In today's fast-paced world", "cannot be overstated"106- **Structural markers**: Excessive em dashes, bullet overuse, sentence uniformity107- **Marketing language**: "enterprise-ready", "cutting-edge", "seamless"108109### Remediation110111If slop score exceeds 2.0 (moderate), apply `Skill(scribe:doc-generator)` principles:1121131. Ground every claim with specifics1142. Remove formulaic openers/closers1153. Use numbers, commands, filenames over adjectives1164. Balance bullets with narrative prose1175. Show authorial perspective (trade-offs, reasoning)118119For significant cleanup needs, use:120121```122Agent(scribe:doc-editor) --target README.md123```124125## Step 5 - Verification & Reporting (`update-readme:verification-reporting`)126- Re-read the updated README for clarity, accessibility (section lengths, bullet balance), and accurate links.127- Run `git diff README.md` (or the edited file) and capture snippets for the final report.128- Summarize detected languages, exemplar sources (with citations), key structural decisions, and follow-up TODOs (e.g., add badges, upload diagrams).129130## Exit Criteria131- All `TodoWrite` items are complete.132- The README reflects a modern, language-aware structure, referencing both internal docs and external inspiration with citations.133- Research notes and command references are captured so future reviewers can reproduce the process.134## Troubleshooting135136### Common Issues137138**Documentation out of sync**139Run `make docs-update` to regenerate from code140141**Build failures**142Check that all required dependencies are installed143144**Links broken**145Verify relative paths in documentation files