| name | self-assess-docs-drift |
| description | Parses falsifiable claims out of CLAUDE.md, ADRs, DECISIONS.md, ARCHITECTURE.md, and README, then checks each against the actual code and reports contradictions with file:line evidence on both sides. Use this when the user asks whether the docs are still accurate, to check CLAUDE.md against the code, find stale documentation, audit documentation drift, or verify our ADRs/architecture docs still match reality — general doc-vs-code claims on any topic. For CI/CD-specific doc claims only (git remotes, pipeline config, mirror scripts), use self-assess-ci-topology instead. |
Check whether this repository's own documentation still matches its code.
This is claim verification, not artifact-freshness — a doc file can be
untouched for a year and still be accurate, or edited yesterday and
already wrong; only reading the code settles it.
Step 0 — Load settings, find the docs, load house rules
Read .claude/self-assess.local.md if it exists (see
${CLAUDE_PLUGIN_ROOT}/references/settings.md). If enabled: false, stop and say so. Note
output_dir (default analysis/self-assess) and skip_verification
(default false).
Resolve or build the shared symbol-index snapshot now (per
references/parallel-safe-research-protocol.md) — Step 1 needs it anyway
for the code-verification dispatch, so doing it here avoids a second
filesystem walk. Read analysis/self-assess/current.json; if missing or
its source_fingerprint no longer matches, run python3 "${CLAUDE_PLUGIN_ROOT}/scripts/build_symbol_index.py" --repo-path . --plugin-name self-assess
(single-flight lock makes concurrent callers safe). For a repo well under
~50 tracked files the build overhead may not be worth it — skip the build
and pass symbolIndexPath: null, using the Glob tool below instead.
If a snapshot is available, query its file_catalog.json for role: "doc" entries plus exact-name matches (CLAUDE.md, README.md,
DECISIONS.md, ARCHITECTURE.md, ADR-*.md, docs/adr/*, adr/*) to
build docFiles — no new filesystem scan needed. Otherwise (no snapshot
built), use the Glob tool (never a Bash find/ls chain — a missing
directory fails an &&-joined shell chain partway through and silently
drops whatever comes after it) for the same patterns at the repo root and
shallow subdirectories. Either way, build the docFiles list from what
actually exists — do not assume all of these are present.
Read .claude/house-rules.md (or the path named by house_rules_path in
the settings file) if it exists (pass null if absent).
Step 1 — Run the scan
Preferred — Workflow orchestration. If the Workflow tool is
available in this session (this skill invocation is your authorization),
reuse the snapshot resolved in Step 0 (symbolIndexPath) — do not
resolve or build it again here:
Workflow({
scriptPath: "${CLAUDE_PLUGIN_ROOT}/workflows/docs-drift-scan.js",
args: { repoPath: "<repo root, usually '.'>", docFiles: [<doc files found>], houseRules: <content or null>, symbolIndexPath: <resolved snapshot dir, or null>, skipVerification: <from settings, default false> }
})
It runs one claim-extractor per doc file (each extracts claims AND does
its own first-pass code check), then — unless skip_verification is set
— an independent referee re-checks every candidate contradiction before
it's reported, so a false positive (the pattern is true in a different
module than the extractor happened to check) dies before it reaches the
artifact. With skip_verification, extractor candidates are reported
directly and labeled unverified; leave it off unless the user explicitly
wants a fast pass. Tell the user the doc count before launching. The
extractors/referees are read-only by design; you write the artifact
below from the structured result.
Fallback (no Workflow tool) — spawn one docs-drift-auditor subagent
per doc file in parallel: "Read <doc> and extract every falsifiable
claim about the current state of the codebase — skip aspirational/roadmap
language ('we plan to...', 'eventually...'), only claims about the CURRENT
state of the code count. Classify each claim's category as one of Pattern,
Deprecation, Policy, Architecture, or Behavior (matching Step 2's report
grouping). For each, cite where it appears (file:line) and check it
against the actual code you read, citing file:line there too. Report
contradicted:true only if the code genuinely does not match." Collect
results, then for each candidate contradiction, re-check it yourself by
reading both locations before including it — don't report a contradiction
on a single agent's word.
Step 2 — Write the report
Create <output_dir>/DOCS_DRIFT.md:
Also write <output_dir>/docs_drift_summary.json — a small machine-
readable sidecar self-assess-portfolio reads for its dashboard:
{"docFilesChecked": N, "totalClaimsChecked": N, "confirmedContradictions": N, "byCategory": {...}, "findings": [...]} (the middle two copied
straight from the workflow's confirmedClaims.length and
stats.byCategory).
findings is the workflow's own confirmedClaims array (already
computed — do not re-derive it), reshaped to the shared per-finding
contract every domain sidecar now uses: {severity, title, evidence, category} — title from claimText, evidence from codeEvidence,
category copied as-is, severity from confidence (High/Medium/Low).
Note this is a confidence-in-the-contradiction reading, not a
severity-of-impact one like the other domains — say so in the report if
it matters, but the field is still called severity for the dashboard's
sake. Feeds findings-dashboard.html's findings table and
self-assess-transform-brief.
Present
Report: claims checked, contradictions found, refuted count. If any
confirmed contradiction is High confidence, call it out by name — that's
the one most worth fixing first. Suggest:
glow -p <output_dir>/DOCS_DRIFT.md
