AGENT SKILL

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

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>.json from the analyze skill, 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-env entry.
  • 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 uncertain when 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

ozzycodes2
ozzycodes2/claudellum

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

★ 1
ozzycodes2
ozzycodes2/claudellum

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.

★ 1
ozzycodes2
ozzycodes2/claudellum

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.

★ 1
ozzycodes2
ozzycodes2/claudellum

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.

★ 1
ozzycodes2
ozzycodes2/claudellum

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.

★ 1
ozzycodes2
ozzycodes2/claudellum

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.

★ 1