docs-drift

Docs Drift

Verify that documentation tells the truth about either the changes about to ship or the latest version already shipped.

Keep the audit read-only. Do not edit, commit, tag, push, publish, or release until the user explicitly approves specific findings. Even after approval, never commit or publish from this skill.

Invocation

• $docs-drift or $docs-drift unreleased — audit every plugin with a non-empty [Unreleased] section.
• $docs-drift <plugin-slug> — audit that plugin's unreleased changes.
• $docs-drift latest — audit the latest reachable release of every tagged plugin.
• $docs-drift latest <plugin-slug> — audit only that plugin's latest release.

Use unreleased mode by default. Treat "latest version", "latest release", or equivalent wording as latest-release mode.

Typical release order, when the sibling skills are installed:

$release-status → $pre-release-review → $docs-drift → $release

Step 1 — Scope plugins and snapshots

Never mix released and unreleased windows in one claim set.

Unreleased mode

Identify plugins whose [Unreleased] section contains non-blank content:

for p in plugins/*/CHANGELOG.md; do
  slug=$(basename "$(dirname "$p")")
  awk '/^## \[Unreleased\]/{f=1; next} /^## \[/{f=0} f && NF' "$p" | rg -q '.' \
    && echo "$slug"
done

If the user named a plugin, limit scope to that slug after verifying it exists and has unreleased content. If nothing is in scope, stop with:

No unreleased changes in any plugin — nothing to drift-check.

Use the working tree as the documentation snapshot. Keep incidentally noticed older drift separate as pre-existing debt.

Latest-release mode

Start from all plugins/*/CHANGELOG.md slugs, or only the user-named slug. Resolve each plugin's refs independently:

EMPTY_TREE=$(git hash-object -t tree /dev/null)

for p in plugins/*/CHANGELOG.md; do
  slug=$(basename "$(dirname "$p")")
  latest=$(git describe --tags --abbrev=0 --match "${slug}--v*" HEAD 2>/dev/null || true)

  if [ -z "$latest" ]; then
    printf '%s\n' "$slug: skipped (no reachable release tag)"
    continue
  fi

  previous=$(git describe --tags --abbrev=0 --match "${slug}--v*" "${latest}^" 2>/dev/null || true)
  printf '%s\n' "$slug latest=$latest previous=${previous:-<empty-tree>}"
done