Compare `.claude/docs/codebase-schema.yaml` against actual filesystem to detect drift.
Detects drift between your documented codebase structure and actual filesystem. Use this to verify documentation accuracy and identify outdated schema entries that need updating.
/plugin marketplace add olioapps/claude-code-plugins/plugin install codebase-documentation@olio-pluginsCompare .claude/docs/codebase-schema.yaml against actual filesystem to detect drift.
Arguments: /codebase-documentation:audit-docs [FLAGS]
Read .claude/docs/codebase-schema.yaml to establish expected state.
If schema not found:
.claude/docs/codebase-schema.yaml"/codebase-documentation:document-codebase to generate documentation first"If --domain <name> provided:
For each domain in the schema (or single domain if --domain flag):
File Count Verification:
domain.location pathabs(found - expected) / expected * 100Structure Verification:
key_files still exist{location}/**/)Pattern Verification:
For each file_patterns entry:
For each domain, classify deviation using BOTH absolute and percentage thresholds (use whichever is MORE permissive):
TRIVIAL (Auto-fixable with --auto-fix):
MINOR (Review recommended):
SIGNIFICANT (Investigation required):
Present report in this format:
# Documentation Audit Report
Generated: {ISO 8601 timestamp}
Schema Last Updated: {from metadata.documentation.generated_at if exists}
## Summary
- ✅ {X} domains up-to-date (no drift)
- ⚠️ {X} domains with trivial drift (auto-fixable)
- 🔍 {X} domains with minor drift (review recommended)
- ❌ {X} domains with significant drift (investigation required)
## Drift Details
### ✅ Up-to-Date Domains
| Domain | Location | Status |
|--------|----------|--------|
| {name} | `{path}` | No drift detected |
### ⚠️ Trivial Drift (Auto-fixable)
#### {domain_name}
- **Location**: `{path}`
- **Expected**: {X} files
- **Found**: {Y} files ({+/- Z} difference, {N}%)
- **Classification**: File count drift within tolerance
- **Auto-fix Action**: Update count to {Y}, update timestamp
---
### 🔍 Minor Drift (Review Recommended)
#### {domain_name}
- **Location**: `{path}`
- **Drift Type**: {New subdirectory detected | File count increase | Pattern variation}
- **Details**:
- {Specific details about what changed}
- **Recommendation**:
- Review if change warrants documentation update
- Run: `/codebase-documentation:map-domain {domain_name}` for detailed analysis
---
### ❌ Significant Drift (Investigation Required)
#### {domain_name}
- **Location**: `{path}`
- **Drift Type**: {Major structural change | Domain missing | Key files missing}
- **Details**:
- Expected: {X} files, Found: {Y} files ({+/- Z} difference, {N}%)
- Missing key files: `{file1}`, `{file2}` (if applicable)
- New undocumented directory: `{path}` (if applicable)
- **Impact**: High - {explanation}
- **Recommended Actions**:
1. Run: `/codebase-documentation:map-domain {domain_name} --compare` for detailed analysis
2. Consider re-running `/codebase-documentation:update-docs` to refresh documentation
---
## File Pattern Drift
| Pattern | Expected | Found | Drift | Status |
|---------|----------|-------|-------|--------|
| {name} | {X} | {Y} | {+/- Z} ({N}%) | {TRIVIAL|MINOR|SIGNIFICANT} |
---
## Recommended Actions
### Immediate (Auto-fixable)
{List TRIVIAL items that can be auto-fixed}
### Review Needed
{List MINOR items requiring manual review}
### Investigation Required
{List SIGNIFICANT items needing investigation}
---
{If --auto-fix was used:}
## Auto-Fix Summary
**Changes Applied:**
- Updated {X} domain file counts
- Updated {Y} pattern counts
- Updated schema timestamp to {date}
**Changes NOT Applied (require manual review):**
- {List of MINOR/SIGNIFICANT drift items}
--interactive flag)For each MINOR or SIGNIFICANT drift item, use AskUserQuestion:
Question: "Drift detected in '{domain_name}': {brief description}. How should we proceed?" Options:
/codebase-documentation:map-domain {domain_name})After all prompts, generate final report with applied changes.
--auto-fix flag)Without --interactive:
With --interactive:
Auto-fix Actions:
metadata.documentation.generated_at timestamp (if field exists)--threshold <level> provided)Only include drift items at or above the specified level:
--threshold trivial - Show all drift (default)--threshold minor - Hide TRIVIAL, show MINOR and SIGNIFICANT--threshold significant - Only show SIGNIFICANT drift--verbose flag)Include additional details:
.claude/docs/codebase-schema.yaml"/codebase-documentation:document-codebase to generate documentation first"--domain flag){path} no longer exists"/codebase-documentation:update-docs to regenerate documentation".claude/docs/codebase-schema.yaml for syntax errors"drift_percentage = abs(found - expected) / expected * 100
If expected is 0 and found > 0, classify as SIGNIFICANT (new undocumented content).
| Classification | Absolute Threshold | Percentage Threshold |
|---|---|---|
| TRIVIAL | ≤5 files | ≤10% |
| MINOR | 6-20 files | 10-25% |
| SIGNIFICANT | >20 files | >25% |
Use whichever threshold is MORE permissive (benefits the doubt).
# Basic audit - check all domains
/codebase-documentation:audit-docs
# Verbose output with file details
/codebase-documentation:audit-docs --verbose
# Auto-fix trivial drift
/codebase-documentation:audit-docs --auto-fix
# Interactive mode - prompt for each item
/codebase-documentation:audit-docs --interactive
# Audit specific domain
/codebase-documentation:audit-docs --domain components
# Only show significant issues
/codebase-documentation:audit-docs --threshold significant
# Combined: verbose audit with auto-fix
/codebase-documentation:audit-docs --verbose --auto-fix
# Interactive audit of specific domain
/codebase-documentation:audit-docs --domain services --interactive
A successful audit should: