docs-drift
Detect documentation drift in a repo's docs/ folder — ADRs, glossaries, API specs (OpenAPI), rendered artifacts, READMEs, code comments, runbooks, and caller-migration notes — that has fallen out of sync with the code a PR changes, and flag documentation-completeness gaps (missing CHANGELOG/README/ docstring updates). Use when reviewing a PR to verify docs still describe the CURRENT model: stale comments describing a removed mechanism, docs asserting a superseded design, a rendered file lagging its source, ADR index rows that don't reflect an amendment or supersede, env/config docs that name the wrong app or variable, missing runbooks for ops-facing changes, or missing caller migration notes for breaking APIs. Use even when the PR doesn't obviously touch docs — code changes silently invalidate docs elsewhere in the tree.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- docs-drift
- metadata
- { "author": "Osniel Quintana-Salgado", "facet-of": "review" }
- description
- Detect documentation drift in a repo's docs/ folder — ADRs, glossaries, API specs (OpenAPI), rendered artifacts, READMEs, code comments, runbooks, and caller-migration notes — that has fallen out of sync with the code a PR changes, and flag documentation-completeness gaps (missing CHANGELOG/README/ docstring updates). Use when reviewing a PR to verify docs still describe the CURRENT model: stale comments describing a removed mechanism, docs asserting a superseded design, a rendered file lagging its source, ADR index rows that don't reflect an amendment or supersede, env/config docs that name the wrong app or variable, missing runbooks for ops-facing changes, or missing caller migration notes for breaking APIs. Use even when the PR doesn't obviously touch docs — code changes silently invalidate docs elsewhere in the tree.
- allowed-tools
- Bash Read Grep Glob
02 资源文件 5
- 资产文件assets/docs-drift.output.json1.2 KB
- 参考文档evals/evals.json1.9 KB
- 参考文档references/drift-patterns.md3.6 KB
- 参考文档references/mac-ui-docs.md1.6 KB
- 脚本scripts/docs_inventory.py5.9 KB
03 SKILL.md 正文
Documentation Drift & Completeness Check
Two facets, one skill:
- Drift — docs that now contradict the code (or each other) after the PR's changes. The hard part: the drift lives in a file the PR did not touch, so a diff-only reviewer never sees it.
- Completeness — expected doc updates the PR should have made but didn't (CHANGELOG entry, README/API doc for a new surface, docstrings on new public items, light DX: ADR/runbook/caller migration).
The generative insight (from real multi-round PR reviews): most doc findings
surface one commit at a time because each is a cross-file claim — a sentence
in docs/ asserting a code fact that a later commit quietly falsified. Catch
them by extracting every doc claim that references a code fact, then verifying
each claim against the post-change code in ONE pass.
Inputs
- PR URL — full GitHub/Enterprise URL.
- OUTPUT_DIR (optional) — defaults to a private
mktemp -d. - Analysis JSON —
<OUTPUT_DIR>/pr-analysis-<PR_NUMBER>.jsonfrom theanalyzeskill, if present (gives changed files + languages).
Output
Write findings to <OUTPUT_DIR>/docs-drift-<PR_NUMBER>.json. Use the template
in assets/docs-drift.output.json verbatim as the shape. Findings that map to
a specific doc line carry path + line so the orchestrator posts them
inline; cross-file/architectural findings omit both and go in the section body.
A stale line you can rewrite outright also carries suggested_change — the
corrected text for lines start_line..line, which posts as a committable
GitHub suggestion. doc_says already quotes the line verbatim, so a
stale-comment, env-mismatch or adr-index finding usually qualifies. A
rendered-lag finding never does: the fix is regenerating the artifact, not
patching the rendered line.
Build the JSON with jq -n and --arg/--argjson so doc text is escaped —
never heredoc untrusted strings.
Workflow
Progress:
- [ ] Step 1 — Inventory the docs surface (
scripts/docs_inventory.py) - [ ] Step 2 — Extract code-referencing claims from docs
- [ ] Step 3 — Verify each claim against the changed code (plan → validate)
- [ ] Step 4 — ADR-specific cross-checks (index ↔ files ↔ status)
- [ ] Step 5 — Rendered-artifact staleness (source ↔ generated)
- [ ] Step 6 — Completeness gaps (+ light DX fold)
- [ ] Step 7 — Score + emit JSON
- [ ] Step 8 — Validate every finding, drop the confirmations, then write it out
Step 0: Parse arguments
PR_URL="$1"
OUTPUT_DIR="${2:-$(mktemp -d -t pr-review-XXXXXX)}"
PR_NUMBER=$(echo "$PR_URL" | grep -oE 'pull/[0-9]+' | grep -oE '[0-9]+')
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo .)"
Step 1: Inventory the docs surface
python3 scripts/docs_inventory.py --repo-root "$REPO_ROOT" > "$OUTPUT_DIR/docs-inventory.json"
if [ ! -s "$OUTPUT_DIR/pr.diff" ]; then # standalone; /review:review captures these
gh pr diff "$PR_URL" > "$OUTPUT_DIR/pr.diff"
gh pr diff "$PR_URL" --name-only > "$OUTPUT_DIR/pr.files"
fi
pr.diff and pr.files are shared with the passes running beside this one.
Read them; never write to them.
Step 2: Extract claims
Read references/drift-patterns.md — authoritative catalog of drift
classes. Work through it; do not improvise categories.
A claim is any doc sentence, table row, code comment, or config comment asserting a checkable code fact. Collect claims from every doc the inventory found — not only docs in the PR diff.
Step 3: Verify each claim against the changed code
For every claim, locate the code fact in the post-change tree and decide
intact | drifted | uncertain. Prefer grepping the repo at HEAD over memory.
A claim is drifted when the asserted fact is absent, renamed, or replaced.
Record doc line AND contradicting code location in the finding body.
Step 4: ADR cross-checks
If docs/adrs/ exists, verify ADR bookkeeping the inventory extracted (status
reflected in index, supersede links bidirectional, model changes retire old docs).
Step 5: Rendered-artifact staleness
For each source→rendered pair: if source changed but rendered did not (or still contains old strings), flag it. Prefer "regenerate" when CI/hooks own the artifact.
Step 6: Completeness gaps
- New public surface (endpoint, exported type, CLI flag, env var) with no
matching README/API-doc/
dot-enventry. - Behavior change with no CHANGELOG entry (only if the repo keeps one).
- New public items missing docstrings (only to the repo's existing bar).
DX docs fold (light touch)
When the PR changes behavior that operators or callers must know about, also check:
- ADRs — behavior/architecture shift without ADR add/amend/supersede when the repo keeps ADRs
- Runbooks / ops notes — deploy, rollback, feature-flag, or on-call steps when ops behavior changes
- Caller migration — breaking internal/public APIs without examples, codemods, or deprecation notes for callers
Keep this light: only flag when the gap would mislead a teammate or on-call. Do not invent a docs policy the repo does not hold.
Step 7: Score & emit
Severity: high = a doc actively misleads; medium = stale but not dangerous; low = cosmetic/index bookkeeping. Emit JSON per the asset template.
Step 8: Validation loop
For each finding: (1) quotes the doc line, (2) names contradicting code or missing artifact, (3) severity matches rubric. Drop unverifiable claims.
Then drop every finding whose remedy is a confirmation. fix works this
list to completion, so a finding with nothing to edit becomes a deferral that
costs a routing decision and a report line and changes no file. Drop it when:
- the remedy's verb is confirm, verify, check, ensure, consider, be aware, or no action needed;
- it restates that the doc and the code agree;
- it reports an absence the repo has no policy about (no CHANGELOG in a repo that keeps none, no ADR for a change the ADR index does not cover);
- it is cosmetic drift in a generated artifact that the next regeneration fixes.
Keep the finding when a reader of the current doc would act wrongly.
Then write docs-drift-<PR_NUMBER>.json.
mac-ui repos (Web Components)
When analyze set uses_mac_ui: true, resolve docs live. Read
references/mac-ui-docs.md for the fetch recipe.
Gotchas
- Drift usually lives OUTSIDE the diff. Inventory the whole
docs/tree. - Rendered artifacts: fix is regeneration, not hand-edit.
- Code comments count as docs.
- Don't flag drift from memory — mark
uncertainwhen greps are inconclusive.
Files
references/drift-patterns.md— drift-class catalog (read in Step 2).references/mac-ui-docs.md— how to fetch mac-ui's live docs.assets/docs-drift.output.json— output JSON template.scripts/docs_inventory.py— docs/ADR/rendered inventory (--help).evals/evals.json— trigger + output evals.
04 同仓库更多 Skills
writing-design-docs
Use when the user wants to write a problem-statement design doc, says "let's plan a feature properly" / "write a design doc" / "I'm thinking about how to do X" for a non-trivial X, or before committing to a non-obvious technical direction
write-doc
Use when the user asks to write or draft a README, ADR, runbook, tutorial, how-to, explanation, or reference doc, or a caller passes "type ADR" or "type README". Picks the type, fills a template, adds diagrams. RFCs and design docs belong to writing-design-docs.
review-doc
Use when the user asks to review, critique, score, grade, or "how good is this doc" for a Markdown doc or pasted text. Read-only. Scores it on the 20 Practical Prose dimensions and emits a findings table. Does not edit; fix-doc applies the findings next.
fix-doc
Use when the user asks to fix, edit for prose quality, polish, tighten, humanize, or de-slop a Markdown doc or pasted text, or says "make this read less AI". Applies review-doc findings, generates flagged diagrams, lists substantive issues for the author, then runs the AI-tell pass last. Modifies the target.
create-slides
Use when the user asks for a slide deck, presentation, talk, or slides from a document, report, PR, notes, or topic. Builds one self-contained Machinify-branded HTML deck in a minimalist style, with headline-plus-visual slides, speaker notes, and every diagram drawn by architecture-design:create-diagram.
start-session
Open a Claude Code working session in a fresh, isolated git worktree, so the user can start a task with a single /start-session <name>. Use at the START of a session when the user says "start session", "start a worktree", "spin up a worktree for ABC-123", "begin work on <ticket>", or passes a name/ticket to work under. Creates and ENTERS a worktree via the EnterWorktree tool (never `git worktree add`) under .claude/worktrees/, named exactly after the argument, on a local branch `worktree-<argument>`. Reports what the worktree inherited (`.worktreeinclude` copies, symlinked node_modules) and whether its `.env` still points at the main checkout's stack. If the argument is a JIRA key (e.g. ABC-123, PROJ-1505), also loads that story with the Atlassian CLI (`acli`) when available and summarizes the implementation ask. Also renames the session to the argument (the same effect as `/rename <NAME>`) so it's easy to find in `/resume`. Then stops and waits — it sets up the workspace and context, it does not implement.