Doc Maintenance

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

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:

Since last review (<sha>, <date>):
- FEATURE: Plugin system merged (runtime, SDK, CLI, slots, event bridge)
- FEATURE: Project archiving added
- BREAKING: Removed legacy webhook adapter
- STRUCTURAL: New .agents/skills/ directory convention

If there are no notable changes, skip to Step 7 (update cursor and exit).

Step 4 — Audit each target doc

For each target document, read it fully and cross-reference against the change summary. Check for:

1. False negatives — major shipped features not mentioned at all 2. False positives — features listed as "coming soon" / "roadmap" / "planned" / "not supported" / "TBD" that already shipped 3. Quickstart accuracy — install commands, prereqs, and startup instructions still correct (README only) 4. Feature table accuracy — does the features section reflect current capabilities? (README only) 5. Works-with accuracy — are supported adapters/integrations listed correctly?

Use references/audit-checklist.md as the structured checklist. Use references/section-map.md to know where to look for each feature area.

Step 5 — Create branch and apply minimal edits

# Create a branch for the doc updates
BRANCH="docs/maintenance-$(date +%Y%m%d)"
git checkout -b "$BRANCH"

Apply only the edits needed to fix drift. Rules:

• Minimal patches only. Fix inaccuracies, don't rewrite sections.
• Preserve voice and style. Match the existing tone of each document.
• No cosmetic changes. Don't fix typos, reformat tables, or reorganize

sections unless they're part of a factual fix.

• No new sections. If a feature needs a whole new section, note it in the

PR description as a follow-up — don't add it in a maintenance pass.

• Roadmap items: Move shipped features out of Roadmap. Add a brief mention

in the appropriate existing section if there isn't one already. Don't add long descriptions.

Step 6 — Open a PR

Commit the changes and open a PR:

git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
git commit -m "docs: update documentation for accuracy

- [list each fix briefly]

Co-Authored-By: Paperclip <noreply@paperclip.ing>"

git push -u origin "$BRANCH"

gh pr create \
  --title "docs: periodic documentation accuracy update" \
  --body "$(cat <<'EOF'
## Summary
Automated doc maintenance pass. Fixes documentation drift detected since
last review.

### Changes
- [list each fix]

### Change summary (since last review)
- [list notable code changes that triggered doc updates]

## Review notes
- Only factual accuracy fixes — no style/cosmetic changes
- Preserves existing voice and structure
- Larger doc additions (new sections, tutorials) noted as follow-ups

🤖 Generated by doc-maintenance skill
EOF
)"

Step 7 — Update the cursor

After a successful audit (whether or not edits were needed), update the cursor:

git rev-parse HEAD > .doc-review-cursor

If edits were made, this is already committed in the PR branch. If no edits were needed, commit the cursor update to the current branch.

Change Classification Rules

Patch Style Guide

• Fix the fact, not the prose
• If removing a roadmap item, don't leave a gap — remove the bullet cleanly
• If adding a feature mention, match the format of surrounding entries

(e.g. if features are in a table, add a table row)

• Keep README changes especially minimal — it shouldn't churn often
• For SPEC/PRODUCT, prefer updating existing statements over adding new ones

(e.g. change "not supported in V1" to "supported via X" rather than adding a new section)

Output

When the skill completes, report:

• How many commits were scanned
• How many notable changes were found
• How many doc edits were made (and to which files)
• PR link (if edits were made)
• Any follow-up items that need larger doc work

Doc Maintenance Audit Checklist

Use this checklist when auditing each target document. For each item, compare against the change summary from git history.

README.md

Features table

• [ ] Each feature card reflects a shipped capability
• [ ] No feature cards for things that don't exist yet
• [ ] No major shipped features missing from the table

Roadmap

• [ ] Nothing listed as "planned" or "coming soon" that already shipped
• [ ] No removed/cancelled items still listed
• [ ] Items reflect current priorities (cross-check with recent PRs)

Quickstart

• [ ] npx paperclipai onboard command is correct
• [ ] Manual install steps are accurate (clone URL, commands)
• [ ] Prerequisites (Node version, pnpm version) are current
• [ ] Server URL and port are correct

"What is Paperclip" section

• [ ] High-level description is accurate
• [ ] Step table (Define goal / Hire team / Approve and run) is correct

"Works with" table

• [ ] All supported adapters/runtimes are listed
• [ ] No removed adapters still listed
• [ ] Logos and labels match current adapter names

"Paperclip is right for you if"

• [ ] Use cases are still accurate
• [ ] No claims about capabilities that don't exist

"Why Paperclip is special"

• [ ] Technical claims are accurate (atomic execution, governance, etc.)
• [ ] No features listed that were removed or significantly changed

FAQ

• [ ] Answers are still correct
• [ ] No references to removed features or outdated behavior

Development section

• [ ] Commands are accurate (pnpm dev, pnpm build, etc.)
• [ ] Link to DEVELOPING.md is correct

doc/SPEC.md

Company Model

• [ ] Fields match current schema
• [ ] Governance model description is accurate

Agent Model

• [ ] Adapter types match what's actually supported
• [ ] Agent configuration description is accurate
• [ ] No features described as "not supported" or "not V1" that shipped

Task Model

• [ ] Task hierarchy description is accurate
• [ ] Status values match current implementation

Extensions / Plugins

• [ ] If plugins are shipped, no "not in V1" or "future" language
• [ ] Plugin model description matches implementation

Open Questions

• [ ] Resolved questions removed or updated
• [ ] No "TBD" items that have been decided

doc/PRODUCT.md

Core Concepts

• [ ] Company, Employees, Task Management descriptions accurate
• [ ] Agent Execution modes described correctly
• [ ] No missing major concepts

Principles

• [ ] Principles haven't been contradicted by shipped features
• [ ] No principles referencing removed capabilities

User Flow

• [ ] Dream scenario still reflects actual onboarding
• [ ] Steps are achievable with current features

Section Map

Maps feature areas to specific document sections so the skill knows where to look when a feature ships or changes.