Add doc-maintenance skill for periodic documentation accuracy audits
Skill detects documentation drift by scanning git history since last review, cross-referencing shipped features against README, SPEC, and PRODUCT docs, and opening PRs with minimal fixes. Includes audit checklist and section map references. Co-Authored-By: Paperclip <noreply@paperclip.ing> Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Dotta
201
.agents/skills/doc-maintenance/SKILL.md
Normal file
201
.agents/skills/doc-maintenance/SKILL.md
Normal file
@@ -0,0 +1,201 @@
|
|||||||
|
---
|
||||||
|
name: doc-maintenance
|
||||||
|
description: >
|
||||||
|
Audit top-level documentation (README, SPEC, PRODUCT) against recent git
|
||||||
|
history to find drift — shipped features missing from docs or features
|
||||||
|
listed as upcoming that already landed. Proposes minimal edits, creates
|
||||||
|
a branch, and opens a PR. Use when asked to review docs for accuracy,
|
||||||
|
after major feature merges, or on a periodic schedule.
|
||||||
|
---
|
||||||
|
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
|
||||||
|
| Signal | Category | Doc update needed? |
|
||||||
|
|--------|----------|-------------------|
|
||||||
|
| `feat:`, `add`, `implement`, `support` in message | Feature | Yes if user-facing |
|
||||||
|
| `remove`, `drop`, `breaking`, `!:` in message | Breaking | Yes |
|
||||||
|
| New top-level directory or config file | Structural | Maybe |
|
||||||
|
| `fix:`, `bugfix` | Fix | No (unless it changes behavior described in docs) |
|
||||||
|
| `refactor:`, `chore:`, `ci:`, `test:` | Maintenance | No |
|
||||||
|
| `docs:` | Doc change | No (already handled) |
|
||||||
|
| Dependency bumps only | Maintenance | No |
|
||||||
|
|
||||||
|
## 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
|
||||||
85
.agents/skills/doc-maintenance/references/audit-checklist.md
Normal file
85
.agents/skills/doc-maintenance/references/audit-checklist.md
Normal file
@@ -0,0 +1,85 @@
|
|||||||
|
# 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
|
||||||
22
.agents/skills/doc-maintenance/references/section-map.md
Normal file
22
.agents/skills/doc-maintenance/references/section-map.md
Normal file
@@ -0,0 +1,22 @@
|
|||||||
|
# Section Map
|
||||||
|
|
||||||
|
Maps feature areas to specific document sections so the skill knows where to
|
||||||
|
look when a feature ships or changes.
|
||||||
|
|
||||||
|
| Feature Area | README Section | SPEC Section | PRODUCT Section |
|
||||||
|
|-------------|---------------|-------------|----------------|
|
||||||
|
| Plugins / Extensions | Features table, Roadmap | Extensions, Agent Model | Core Concepts |
|
||||||
|
| Adapters (new runtimes) | "Works with" table, FAQ | Agent Model, Agent Configuration | Employees & Agents, Agent Execution |
|
||||||
|
| Governance / Approvals | Features table, "Why special" | Board Governance, Board Approval Gates | Principles |
|
||||||
|
| Budget / Cost Control | Features table, "Why special" | Budget Delegation | Company (revenue & expenses) |
|
||||||
|
| Task Management | Features table | Task Model | Task Management |
|
||||||
|
| Org Chart / Hierarchy | Features table | Agent Model (reporting) | Employees & Agents |
|
||||||
|
| Multi-Company | Features table, FAQ | Company Model | Company |
|
||||||
|
| Heartbeats | Features table, FAQ | Agent Execution | Agent Execution |
|
||||||
|
| CLI Commands | Development section | — | — |
|
||||||
|
| Onboarding / Quickstart | Quickstart, FAQ | — | User Flow |
|
||||||
|
| Skills / Skill Injection | "Why special" | — | — |
|
||||||
|
| Company Templates | "Why special", Roadmap (ClipMart) | — | — |
|
||||||
|
| Mobile / UI | Features table | — | — |
|
||||||
|
| Project Archiving | — | — | — |
|
||||||
|
| OpenClaw Integration | "Works with" table, FAQ | Agent Model | Agent Execution |
|
||||||
Reference in New Issue
Block a user