# Doc Drift Audit

Compares README and product docs with recent history and makes minimal fixes.

- Repository: https://github.com/paperclipai/paperclip (109885 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add paperclipai/paperclip --skill doc-maintenance -g -a claude-code -y`
Codex: `npx skills add paperclipai/paperclip --skill doc-maintenance -g -a codex -y`
Cursor: `npx skills add paperclipai/paperclip --skill doc-maintenance -g -a cursor -y`
Gemini CLI: `npx skills add paperclipai/paperclip --skill doc-maintenance -g -a gemini-cli -y`

## Description

Audit README, SPEC, and PRODUCT docs against recent git history for drift and make minimal PR-ready edits. Use when asked to review docs for accuracy, after major feature merges, or on a schedule.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```bash
# 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:

```bash
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:

The rest: https://github.com/paperclipai/paperclip/blob/HEAD/.agents/skills/doc-maintenance/SKILL.md