documentation-drift-audit

Audit documentation claims against actual code and fix only verifiably false statements.

2|Updated Jul 18, 2026
One-click install
npx skills add https://github.com/Arasz/ai-badger --skill documentation-drift-audit-arasz
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: documentation-drift-audit
Source: https://github.com/Arasz/ai-badger/tree/main/features/common/skills/documentation-drift-audit
Command: npx skills add https://github.com/Arasz/ai-badger --skill documentation-drift-audit-arasz

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Documentation drifts out of sync with code as features merge, and naive fixes often rewrite design decisions or historical records that were never wrong. This Skill separates verifiably false claims from design positions, ambiguity, and history before touching anything, so doc fixes are evidence-based and minimal. ## Core Features & Use Cases - Claim inventory and verification: Grep the doc surface for claims (script names, config keys, hook events, counts), then verify each against real files, manifests, scaffolder behavior, and actual scaffolded trees with path:line evidence. - Four-way classification: Classify every finding as verifiably false (fix directly), design position (report only), ambiguous (report only), or historical record (never rewrite), then report A/B/C results to the orchestrator. - Post-merge and compaction audits: Run Phase-5 doc-gap audits after feature merges (worktree setup, fast-forward conflict recovery, grep gates, generated-copy diffs) and README compaction/rewrite passes that extract ground truth from code before rewriting. - Use Case: After a feature merge adds a new CLI backend, audit the README and reference docs against the merged code, fix the one stale wording, and report undocumented auth limitations as decision gaps instead of guessing. ## Quick Start Audit the documentation for drift against the current code and fix only the claims that are verifiably false, reporting the rest.

Frequently Asked Questions about documentation-drift-audit

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit documentation for drift against code?

Inventory every claim with path:line references by grepping the doc surface for the topic's vocabulary, then verify each claim against the actual files: scaffolder copy logic, manifests, hook registration, and real scaffolded trees. Fix only verifiably false claims and report the rest.

What counts as documentation drift versus a design decision?

Drift is a claim provably false against the code with path:line evidence. Statements like 'Claude-only by design' are design positions to report, not fix, and dated changelogs or research records are historical and should never be rewritten.

How do I run a post-merge documentation audit?

Verify the checkout actually contains the merge commit, extract ground truth from the merged code (CLI verbs, config keys, error prefixes), grep for old phrasing with intentional-residue classification, and diff generated instruction copies against their sources before editing.

Should I fix stale ADRs when they disagree with the code?

Split the disagreement first: contract points where the ADR promises behavior mean the code is wrong and needs TDD fixes, while factual points like tool counts mean the doc needs a minimal in-place refresh. Check the ADR immutability policy and git history before editing.

Why not fix every outdated statement found during a doc audit?

Many stale-looking statements are intentional: historical records, frozen ADRs, live test spec files, or design positions. Editing them can break test bindings, rewrite accepted decisions, or duplicate fixes already covered by an open PR, so they are reported as decision gaps instead.