docs-revise

name	docs-revise
description	Review and freshen all documentation and notes in the current project — discover and obey the project's own doc conventions, fix drift, flag quality gaps, and fill genuinely missing context. Use when the user asks to update docs, freshen documentation, audit AGENTS.md/rules, or clean up notes.

Docs Revise

You are a documentation auditor. Review the project's docs, fix anything outdated, flag quality gaps, and fill context that is genuinely missing — while obeying whatever doc discipline the project has defined for itself.

0. Discover the project's doc conventions FIRST

Find out what rules this repo imposes on its own docs. Project conventions are authoritative and override every default here on any conflict.

• Glob for a doc-discipline file: **/docs/conventions/*.md, **/docs/**/doc*.md, CONTRIBUTING*.md, **/STYLE*.md — anything that reads like "how we write docs here". Read what you find.
• Read AGENTS.md and the project rules in .cursor/rules/*.mdc. Extract their hard rules that touch docs — no AI attribution, no disallowed emojis, filename casing, confidentiality (no internal IDs in committed files).
• Note structural conventions: a per-package doc contract (e.g. every package ships a README.md to a fixed template), a "Last updated" footer, a size cap, an append-only decision-record directory.

Carry these as binding constraints through every step. If none exist, use the defaults here.

1. Understand recent changes

git log --oneline -50
git log --oneline -50 --name-only --pretty=format:""

2. Inventory every doc surface

Use Glob broadly — discover the doc tree, don't assume a fixed shape:

• AGENTS.md, **/README.md, VISION.md, ARCHITECTURE.md
• The whole **/docs/**/*.md tree (conventions, decision records, runbooks, plans, notes)
• Project rules .cursor/rules/*.mdc and skills .cursor/skills/*/SKILL.md
• **/NOTES.md, **/notes/*.md

Doc layering:

Location	Treatment
root AGENTS.md / root README.md	Concise, link-heavy project map; team-shared
nested packages/*/README.md, subdir docs	Domain/module detail close to the code
local/gitignored notes	Fix in place; do not suggest committing

Keep layers non-redundant — the root is a map, nested files hold detail.

3. Cross-reference docs against current state

For each file:

1. Read it.
2. Check claims against reality — file paths, package names, env vars, commands, package.json scripts, tool names, type signatures, patterns. Verify with Grep/Glob/Read, never memory.
3. Check against recent commits — did anything land that contradicts the doc?
4. Scan for red flags: commands that would fail; references to deleted/moved files; outdated versions; uncustomized template boilerplate; long-done or abandoned TODOs; the same fact duplicated across layers; verbose prose restating the code; broken cross-links; stale "last updated" footers where the content is also wrong.
5. Note genuine gaps — essential context a fresh session would have to rediscover (an undocumented build/test/lint command, a non-obvious gotcha or ordering dependency, a config quirk, a package relationship), and structural gaps (a shipped package missing its expected README.md if the project has that contract). A missing essential is a doc defect, not just an absence.

4. Apply fixes — project conventions win

a. Repair drift

• Remove references to things that no longer exist (deleted files, old tool names, removed features).
• Update references that changed (renamed files, moved paths, new tool names).
• Fresh, not patched — when a section is wrong, rewrite the section. Never layer "Note (date): actually …" amendments on top of stale prose.
• Update notes: drop stale ones, fix descriptions, repair any index.
• Update skill/rule files: fix tool references and descriptions.
• README.md: fix only factual drift (broken paths, renamed commands, removed features, outdated install/usage). Don't rewrite prose, tone, or marketing copy.
• Append-only decision records — if the project keeps decision records, never edit a record's body. If a decision changed, write a new record superseding it and update the old one's Status: line to point at it; change nothing else in the old record.

b. Fill genuine gaps (additive — strict bar, and only if project conventions permit additions)

Add only project-specific context that earns its place; verify each addition against the codebase first. Closing a structural gap (a missing per-package doc the project's contract requires) always qualifies.

ADD: discovered build/test/lint/deploy commands, non-obvious gotchas and ordering dependencies, config/env quirks, non-obvious package relationships, testing approaches the project actually uses.

DO NOT ADD: restatements of what code or filenames already say, generic best practices, one-off fixes unlikely to recur, multi-sentence explanations where one line works.

One line per concept. Domain detail goes in the nearest nested doc, not the root — if the root is bloated, split detail down rather than expand it.

c. Enforce the project's hard rules discovered in step 0 — strip AI attribution, remove disallowed emojis, fix filename casing on any file you create, honor confidentiality rules, and bump the project's last-updated footer on docs you touched and verified accurate (use today's date).

d. Don't auto-split, flag instead — a doc that blows the project's size cap (or is just unwieldy) is a split candidate: report it, don't split unless trivially safe.

e. Self-revision safety — if a doc surface in scope is this skill's own SKILL.md or the file driving the current run, do NOT auto-edit it. Check whether its inventory/conventions still match the repo and report any drift as a flagged finding for manual review. Editing the agent's own running instructions mid-task is unsafe.

5. Honor project-specific post-task instructions

Re-read AGENTS.md and any nested docs in directories you touched. Look for sections describing what to do after finishing a task — activity logs, notes updates, status sync, anything phrased "after finishing" / "when done".

If such instructions exist AND you changed files this run, follow them. Skip if no docs changed or no such instructions exist.

6. Return a summary

• Per root/nested doc, a one-line grade: A (current, complete) / B (minor gaps) / C (missing key context) / D–F (sparse or outdated) — with the single biggest reason
• Files updated (one line each)
• Gaps filled (what was added and why it helps future sessions)
• Files split-flagged or deleted (with rationale)
• Missing per-package docs the project's contract requires
• Convention violations spotted but not auto-fixed (e.g. decision-record body edits) — for follow-up
• Files flagged for manual review (couldn't verify programmatically, or correctness depends on an unwritten decision)
• Counts: X reviewed, Y updated, Z deleted, N flagged

Principles

• Conventions win — the project's own doc rules override every default here on conflict.
• Verify before changing or adding — confirm staleness, or that a gap is real, against code/git.
• Fresh, not patched — rewrite wrong sections; never amend them with dated notes.
• Preserve intent — keep each doc's voice and purpose; fix the facts.
• Small root, detailed leaves — the root doc is a concise map; domain detail lives in nested files.
• Every line earns its place — fix drift, trim filler, add only what a fresh session would otherwise rediscover.
• Ask if uncertain — if a doc's correctness depends on an unwritten design decision, flag it and stop; don't guess.