doc-maintenance

1---2name: doc-maintenance3description: >4  Audit README, SPEC, and PRODUCT docs against recent git history for drift and5  make minimal PR-ready edits. Use when asked to review docs for accuracy, after6  major feature merges, or on a schedule.7---8 9# Doc Maintenance Skill10 11Detect documentation drift and fix it via PR — no rewrites, no churn.12 13## When to Use14 15- Periodic doc review (e.g. weekly or after releases)16- After major feature merges17- When asked "are our docs up to date?"18- When asked to audit README / SPEC / PRODUCT accuracy19 20## Target Documents21 22| Document | Path | What matters |23|----------|------|-------------|24| README | `README.md` | Features table, roadmap, quickstart, "what is" accuracy, "works with" table |25| SPEC | `doc/SPEC.md` | No false "not supported" claims, major model/schema accuracy |26| PRODUCT | `doc/PRODUCT.md` | Core concepts, feature list, principles accuracy |27 28Out of scope: DEVELOPING.md, DATABASE.md, CLI.md, doc/plans/, skill files,29release notes. These are dev-facing or ephemeral — lower risk of user-facing30confusion.31 32## Workflow33 34### Step 1 — Detect what changed35 36Find the last review cursor:37 38```bash39# Read the last-reviewed commit SHA40CURSOR_FILE=".doc-review-cursor"41if [ -f "$CURSOR_FILE" ]; then42  LAST_SHA=$(cat "$CURSOR_FILE" | head -1)43else44  # First run: look back 60 days45  LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse | head -1)46fi47```48 49Then gather commits since the cursor:50 51```bash52git log "$LAST_SHA"..HEAD --oneline --no-merges53```54 55### Step 2 — Classify changes56 57Scan commit messages and changed files. Categorize into:58 59- **Feature** — new capabilities (keywords: `feat`, `add`, `implement`, `support`)60- **Breaking** — removed/renamed things (keywords: `remove`, `breaking`, `drop`, `rename`)61- **Structural** — new directories, config changes, new adapters, new CLI commands62 63**Ignore:** refactors, test-only changes, CI config, dependency bumps, doc-only64changes, style/formatting commits. These don't affect doc accuracy.65 66For borderline cases, check the actual diff — a commit titled "refactor: X"67that adds a new public API is a feature.68 69### Step 3 — Build a change summary70 71Produce a concise list like:72 73```74Since last review (<sha>, <date>):75- FEATURE: Plugin system merged (runtime, SDK, CLI, slots, event bridge)76- FEATURE: Project archiving added77- BREAKING: Removed legacy webhook adapter78- STRUCTURAL: New .agents/skills/ directory convention79```80 81If there are no notable changes, skip to Step 7 (update cursor and exit).82 83### Step 4 — Audit each target doc84 85For each target document, read it fully and cross-reference against the change86summary. Check for:87 881. **False negatives** — major shipped features not mentioned at all892. **False positives** — features listed as "coming soon" / "roadmap" / "planned"90   / "not supported" / "TBD" that already shipped913. **Quickstart accuracy** — install commands, prereqs, and startup instructions92   still correct (README only)934. **Feature table accuracy** — does the features section reflect current94   capabilities? (README only)955. **Works-with accuracy** — are supported adapters/integrations listed correctly?96 97Use `references/audit-checklist.md` as the structured checklist.98Use `references/section-map.md` to know where to look for each feature area.99 100### Step 5 — Create branch and apply minimal edits101 102```bash103# Create a branch for the doc updates104BRANCH="docs/maintenance-$(date +%Y%m%d)"105git checkout -b "$BRANCH"106```107 108Apply **only** the edits needed to fix drift. Rules:109 110- **Minimal patches only.** Fix inaccuracies, don't rewrite sections.111- **Preserve voice and style.** Match the existing tone of each document.112- **No cosmetic changes.** Don't fix typos, reformat tables, or reorganize113  sections unless they're part of a factual fix.114- **No new sections.** If a feature needs a whole new section, note it in the115  PR description as a follow-up — don't add it in a maintenance pass.116- **Roadmap items:** Move shipped features out of Roadmap. Add a brief mention117  in the appropriate existing section if there isn't one already. Don't add118  long descriptions.119 120### Step 6 — Open a PR121 122Commit the changes and open a PR:123 124```bash125git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor126git commit -m "docs: update documentation for accuracy127 128- [list each fix briefly]129 130Co-Authored-By: Paperclip <noreply@paperclip.ing>"131 132git push -u origin "$BRANCH"133 134gh pr create \135  --title "docs: periodic documentation accuracy update" \136  --body "$(cat <<'EOF'137## Summary138Automated doc maintenance pass. Fixes documentation drift detected since139last review.140 141### Changes142- [list each fix]143 144### Change summary (since last review)145- [list notable code changes that triggered doc updates]146 147## Review notes148- Only factual accuracy fixes — no style/cosmetic changes149- Preserves existing voice and structure150- Larger doc additions (new sections, tutorials) noted as follow-ups151 152🤖 Generated by doc-maintenance skill153EOF154)"155```156 157### Step 7 — Update the cursor158 159After a successful audit (whether or not edits were needed), update the cursor:160 161```bash162git rev-parse HEAD > .doc-review-cursor163```164 165If edits were made, this is already committed in the PR branch. If no edits166were needed, commit the cursor update to the current branch.167 168## Change Classification Rules169 170| Signal | Category | Doc update needed? |171|--------|----------|-------------------|172| `feat:`, `add`, `implement`, `support` in message | Feature | Yes if user-facing |173| `remove`, `drop`, `breaking`, `!:` in message | Breaking | Yes |174| New top-level directory or config file | Structural | Maybe |175| `fix:`, `bugfix` | Fix | No (unless it changes behavior described in docs) |176| `refactor:`, `chore:`, `ci:`, `test:` | Maintenance | No |177| `docs:` | Doc change | No (already handled) |178| Dependency bumps only | Maintenance | No |179 180## Patch Style Guide181 182- Fix the fact, not the prose183- If removing a roadmap item, don't leave a gap — remove the bullet cleanly184- If adding a feature mention, match the format of surrounding entries185  (e.g. if features are in a table, add a table row)186- Keep README changes especially minimal — it shouldn't churn often187- For SPEC/PRODUCT, prefer updating existing statements over adding new ones188  (e.g. change "not supported in V1" to "supported via X" rather than adding189  a new section)190 191## Output192 193When the skill completes, report:194 195- How many commits were scanned196- How many notable changes were found197- How many doc edits were made (and to which files)198- PR link (if edits were made)199- Any follow-up items that need larger doc work200