Doc Maintenance Skill

Detect documentation drift and fix it via PR, no rewrites, no churn.

When to Use

• Periodic doc review (e.g. weekly or after releases)
• After major feature merges
• When asked "are our docs up to date?"
• When asked to audit README / SPEC / PRODUCT accuracy

Target Documents

Document	Path	What matters
README	README.md	Features table, roadmap, quickstart, "what is" accuracy, "works with" table
SPEC	doc/SPEC.md	No false "not supported" claims, major model/schema accuracy
PRODUCT	doc/PRODUCT.md	Core concepts, feature list, principles accuracy

Out of scope: DEVELOPING.md, DATABASE.md, CLI.md, doc/plans/, skill files, release notes. These are dev-facing or ephemeral, lower risk of user-facing confusion.

Workflow

Step 1, Detect what changed

Find the last review cursor:

# Read the last-reviewed commit SHA
CURSOR_FILE=".doc-review-cursor"
if [ -f "$CURSOR_FILE" ]; then
  LAST_SHA=$(cat "$CURSOR_FILE" | head -1)
else
  # First run: look back 60 days
  LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse | head -1)
fi

Then gather commits since the cursor:

git log "$LAST_SHA"..HEAD --oneline --no-merges

Step 2, Classify changes

Scan commit messages and changed files. Categorize into:

• Feature, new capabilities (keywords: feat, add, implement, support)
• Breaking, removed/renamed things (keywords: remove, breaking, drop, rename)
• Structural, new directories, config changes, new adapters, new CLI commands

Ignore: refactors, test-only changes, CI config, dependency bumps, doc-only changes, style/formatting commits. These don't affect doc accuracy.

For borderline cases, check the actual diff, a commit titled "refactor: X" that adds a new public API is a feature.

Step 3, Build a change summary

Produce a concise list like: