doc-maintenance

Name: doc-maintenance
Author: IncomeStreamSurfer

69stars33forks

How to install doc-maintenance?

incomestreamsurfer/paperclip-surfers/doc-maintenance

$npx -y skills add IncomeStreamSurfer/paperclip-surfers --skill doc-maintenance

Installs into the current project.

Summary

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 accu

Files · 1

View on GitHub

SKILL.md

1	# Doc Maintenance Skill
2
3	Detect documentation drift and fix it via PR — no rewrites, no churn.
4
5	## When to Use
6
7	- Periodic doc review (e.g. weekly or after releases)
8	- After major feature merges
9	- When asked "are our docs up to date?"
10	- When asked to audit README / SPEC / PRODUCT accuracy
11
12	## Target Documents
13
14	\| Document \| Path \| What matters \|
15	\|----------\|------\|-------------\|
16	\| README \| `README.md` \| Features table, roadmap, quickstart, "what is" accuracy, "works with" table \|
17	\| SPEC \| `doc/SPEC.md` \| No false "not supported" claims, major model/schema accuracy \|
18	\| PRODUCT \| `doc/PRODUCT.md` \| Core concepts, feature list, principles accuracy \|
19
20	Out of scope: DEVELOPING.md, DATABASE.md, CLI.md, doc/plans/, skill files,
21	release notes. These are dev-facing or ephemeral — lower risk of user-facing
22	confusion.
23
24	## Workflow
25
26	### Step 1 — Detect what changed
27
28	Find the last review cursor:
29
30	```bash
31	# Read the last-reviewed commit SHA
32	CURSOR_FILE=".doc-review-cursor"
33	if [ -f "$CURSOR_FILE" ]; then
34	LAST_SHA=$(cat "$CURSOR_FILE" \| head -1)
35	else
36	# First run: look back 60 days
37	LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse \| head -1)
38	fi
39	```
40
41	Then gather commits since the cursor:
42
43	```bash
44	git log "$LAST_SHA"..HEAD --oneline --no-merges
45	```
46
47	### Step 2 — Classify changes
48
49	Scan commit messages and changed files. Categorize into:
50
51	- Feature — new capabilities (keywords: `feat`, `add`, `implement`, `support`)
52	- Breaking — removed/renamed things (keywords: `remove`, `breaking`, `drop`, `rename`)
53	- Structural — new directories, config changes, new adapters, new CLI commands
54
55	Ignore: refactors, test-only changes, CI config, dependency bumps, doc-only
56	changes, style/formatting commits. These don't affect doc accuracy.
57
58	For borderline cases, check the actual diff — a commit titled "refactor: X"
59	that adds a new public API is a feature.
60
61	### Step 3 — Build a change summary
62
63	Produce a concise list like:
64
65	```
66	Since last review (<sha>, <date>):
67	- FEATURE: Plugin system merged (runtime, SDK, CLI, slots, event bridge)
68	- FEATURE: Project archiving added
69	- BREAKING: Removed legacy webhook adapter
70	- STRUCTURAL: New .agents/skills/ directory convention
71	```
72
73	If there are no notable changes, skip to Step 7 (update cursor and exit).
74
75	### Step 4 — Audit each target doc
76
77	For each target document, read it fully and cross-reference against the change
78	summary. Check for:
79
80	1. False negatives — major shipped features not mentioned at all
81	2. False positives — features listed as "coming soon" / "roadmap" / "planned"
82	/ "not supported" / "TBD" that already shipped
83	3. Quickstart accuracy — install commands, prereqs, and startup instructions
84	still correct (README only)
85	4. Feature table accuracy — does the features section reflect current
86	capabilities? (README only)
87	5. Works-with accuracy — are supported adapters/integrations listed correctly?
88
89	Use `references/audit-checklist.md` as the structured checklist.
90	Use `references/section-map.md` to know where to look for each feature area.
91
92	### Step 5 — Create branch and apply minimal edits
93
94	```bash
95	# Create a branch for the doc updates
96	BRANCH="docs/maintenance-$(date +%Y%m%d)"
97	git checkout -b "$BRANCH"
98	```
99
100	Apply only the edits needed to fix drift. Rules:
101
102	- Minimal patches only. Fix inaccuracies, don't rewrite sections.
103	- Preserve voice and style. Match the existing tone of each document.
104	- No cosmetic changes. Don't fix typos, reformat tables, or reorganize
105	sections unless they're part of a factual fix.
106	- No new sections. If a feature needs a whole new section, note it in the
107	PR description as a follow-up — don't add it in a maintenance pass.
108	- Roadmap items: Move shipped features out of Roadmap. Add a brief mention
109	in the appropriate existing section if there isn't one already. Don't add
110	long descriptions.
111
112	### Step 6 — Open a PR
113
114	Commit the changes and open a PR:
115
116	```bash
117	git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
118	git commit -m "docs: update documentation for accuracy
119
120	- [list each fix briefly]
121
122	Co-Authored-By: Paperclip <noreply@paperclip.ing>"
123
124	git push -u origin "$BRANCH"
125
126	gh pr create \
127	--title "docs: periodic documentation accuracy update" \
128	--body "$(cat <<'EOF'
129	## Summary
130	Automated doc maintenance pass. Fixes documentation drift detected since
131	last review.
132
133	### Changes
134	- [list each fix]
135
136	### Change summary (since last review)
137	- [list notable code changes that triggered doc updates]
138
139	## Review notes
140	- Only factual accuracy fixes — no style/cosmetic changes
141	- Preserves existing voice and st

People who liked this also viewed

6 picks

Type

doc-maintenance

69stars33forks

View on GitHub

How to install doc-maintenance?

incomestreamsurfer/paperclip-surfers/doc-maintenance

$npx -y skills add IncomeStreamSurfer/paperclip-surfers --skill doc-maintenance

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Doc Maintenance Skill
2
3	Detect documentation drift and fix it via PR — no rewrites, no churn.
4
5	## When to Use
6
7	- Periodic doc review (e.g. weekly or after releases)
8	- After major feature merges
9	- When asked "are our docs up to date?"
10	- When asked to audit README / SPEC / PRODUCT accuracy
11
12	## Target Documents
13
14	\| Document \| Path \| What matters \|
15	\|----------\|------\|-------------\|
16	\| README \| `README.md` \| Features table, roadmap, quickstart, "what is" accuracy, "works with" table \|
17	\| SPEC \| `doc/SPEC.md` \| No false "not supported" claims, major model/schema accuracy \|
18	\| PRODUCT \| `doc/PRODUCT.md` \| Core concepts, feature list, principles accuracy \|
19
20	Out of scope: DEVELOPING.md, DATABASE.md, CLI.md, doc/plans/, skill files,
21	release notes. These are dev-facing or ephemeral — lower risk of user-facing
22	confusion.
23
24	## Workflow
25
26	### Step 1 — Detect what changed
27
28	Find the last review cursor:
29
30	```bash
31	# Read the last-reviewed commit SHA
32	CURSOR_FILE=".doc-review-cursor"
33	if [ -f "$CURSOR_FILE" ]; then
34	LAST_SHA=$(cat "$CURSOR_FILE" \| head -1)
35	else
36	# First run: look back 60 days
37	LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse \| head -1)
38	fi
39	```
40
41	Then gather commits since the cursor:
42
43	```bash
44	git log "$LAST_SHA"..HEAD --oneline --no-merges
45	```
46
47	### Step 2 — Classify changes
48
49	Scan commit messages and changed files. Categorize into:
50
51	- Feature — new capabilities (keywords: `feat`, `add`, `implement`, `support`)
52	- Breaking — removed/renamed things (keywords: `remove`, `breaking`, `drop`, `rename`)
53	- Structural — new directories, config changes, new adapters, new CLI commands
54
55	Ignore: refactors, test-only changes, CI config, dependency bumps, doc-only
56	changes, style/formatting commits. These don't affect doc accuracy.
57
58	For borderline cases, check the actual diff — a commit titled "refactor: X"
59	that adds a new public API is a feature.
60
61	### Step 3 — Build a change summary
62
63	Produce a concise list like:
64
65	```
66	Since last review (<sha>, <date>):
67	- FEATURE: Plugin system merged (runtime, SDK, CLI, slots, event bridge)
68	- FEATURE: Project archiving added
69	- BREAKING: Removed legacy webhook adapter
70	- STRUCTURAL: New .agents/skills/ directory convention
71	```
72
73	If there are no notable changes, skip to Step 7 (update cursor and exit).
74
75	### Step 4 — Audit each target doc
76
77	For each target document, read it fully and cross-reference against the change
78	summary. Check for:
79
80	1. False negatives — major shipped features not mentioned at all
81	2. False positives — features listed as "coming soon" / "roadmap" / "planned"
82	/ "not supported" / "TBD" that already shipped
83	3. Quickstart accuracy — install commands, prereqs, and startup instructions
84	still correct (README only)
85	4. Feature table accuracy — does the features section reflect current
86	capabilities? (README only)
87	5. Works-with accuracy — are supported adapters/integrations listed correctly?
88
89	Use `references/audit-checklist.md` as the structured checklist.
90	Use `references/section-map.md` to know where to look for each feature area.
91
92	### Step 5 — Create branch and apply minimal edits
93
94	```bash
95	# Create a branch for the doc updates
96	BRANCH="docs/maintenance-$(date +%Y%m%d)"
97	git checkout -b "$BRANCH"
98	```
99
100	Apply only the edits needed to fix drift. Rules:
101
102	- Minimal patches only. Fix inaccuracies, don't rewrite sections.
103	- Preserve voice and style. Match the existing tone of each document.
104	- No cosmetic changes. Don't fix typos, reformat tables, or reorganize
105	sections unless they're part of a factual fix.
106	- No new sections. If a feature needs a whole new section, note it in the
107	PR description as a follow-up — don't add it in a maintenance pass.
108	- Roadmap items: Move shipped features out of Roadmap. Add a brief mention
109	in the appropriate existing section if there isn't one already. Don't add
110	long descriptions.
111
112	### Step 6 — Open a PR
113
114	Commit the changes and open a PR:
115
116	```bash
117	git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
118	git commit -m "docs: update documentation for accuracy
119
120	- [list each fix briefly]
121
122	Co-Authored-By: Paperclip <noreply@paperclip.ing>"
123
124	git push -u origin "$BRANCH"
125
126	gh pr create \
127	--title "docs: periodic documentation accuracy update" \
128	--body "$(cat <<'EOF'
129	## Summary
130	Automated doc maintenance pass. Fixes documentation drift detected since
131	last review.
132
133	### Changes
134	- [list each fix]
135
136	### Change summary (since last review)
137	- [list notable code changes that triggered doc updates]
138
139	## Review notes
140	- Only factual accuracy fixes — no style/cosmetic changes
141	- Preserves existing voice and st

People who liked this also viewed

6 picks

Type