drift-audit

name	drift-audit
description	Run a thorough drift audit to detect standards divergence

Drift Audit Skill

Conduct a comprehensive audit to identify where code practice diverges from documented standards.

Context

Standards drift happens gradually — code patterns diverge from standards, documentation becomes stale, agent context falls out of sync with reality. This skill teaches you to run a formal audit and act on findings.

Domain Context

Drift can occur in three ways:

1. Code drift — Code doesn't follow documented standards
2. Documentation drift — Standards docs are stale compared to actual practice
3. Context drift — Agent files (CLAUDE.md, AGENTS.md) are out of sync with code/standards

The weekly drift audit is a scheduled ceremony that catches these issues between PRs.

Reference: levels/L2-ceremonies/ceremonies/weekly-drift-audit.md

Instructions

1. Run verify-all.sh — Execute all verification scripts

   ./scripts/verify-all.sh
   

   • This runs typecheck, tests, build, lint, and documentation checks
   • Identify any failures and note their types
   • Deliverable: Verification output with pass/fail status

2. Run check-drift.sh — Detect standards infrastructure issues

   ./levels/L2-ceremonies/scripts/check-drift.sh
   

   • Verifies docs/standards/ directory exists and has content
   • Verifies CLAUDE.md references standards
   • Verifies agent files reference valid standard paths
   • Deliverable: Drift detection output

3. Review recent PRs for compliance — Spot-check compliance in merged code

   • Review last 3-5 PRs merged to main
   • For each PR, check: Did code changes follow documented standards?
   • Identify any standards violations that slipped through
   • Deliverable: List of compliance issues found

4. Check for new standards needing wiring — Identify undiscovered standards

   • Look for patterns that appear 3+ times in codebase but have no standard
   • Review recent PRs for new conventions that emerged
   • Identify if any new standards were added but not wired into agent context
   • Deliverable: List of new patterns/standards to document or wire

5. Update agent context if architecture changed — Keep context in sync

   • If directory structure changed, update CLAUDE.md
   • If deployment process changed, update AGENTS.md
   • If new team convention emerged, update .cursor/rules/
   • Deliverable: Updated context files

6. Summarize findings and create issues — Document results for the team

   • Create a summary report showing: Categories of drift found, Severity (critical/high/medium/low)
   • For critical/high severity issues, create GitHub issues with fixes
   • For medium/low severity issues, log as notes for backlog refinement
   • Deliverable: Audit report and action items

Anti-Patterns

1. Ceremony theater — Running audit but not acting on results

   • Wrong: Run scripts, note failures, close the report without fixing anything
   • Right: Run audit, identify issues, create issues/PRs to fix
   • Impact: Standards drift continues undetected
   • Guard: Every audit should result in at least 1-2 action items

2. Rubber-stamping results — Reading output without understanding it

   • Wrong: "check-drift.sh passed, so we're good"
   • Right: "check-drift.sh passed AND I reviewed recent PRs AND found X issues"
   • Impact: Real drift is missed
   • Guard: Always spend 15+ minutes reviewing actual code changes, not just script output

3. False positives from vague standards — Misinterpreting results

   • Happens when: Standards are written so vaguely that violations are ambiguous
   • Example: "Code should be readable" is too vague to audit
   • Guard: When reviewing PRs, only flag violations of specific, measurable standards
   • If you can't cite a specific rule, it's not a real violation

Further Reading

• levels/L2-ceremonies/ceremonies/weekly-drift-audit.md — Full ceremony definition
• levels/L2-ceremonies/scripts/check-drift.sh — Drift detection script
• levels/L1-context/library/quality/governance.md — Standards drift prevention