Detect and fix drift between documentation and source code
Detects and resolves documentation drift by comparing docs against actual code implementation.
/plugin marketplace add mwguerra/claude-code-plugins/plugin install code@mwguerra-marketplace<check | fix> [--docs path] [--code path] [--report]Detect and fix drift between documentation and source code.
/docs-specialist:sync <action> [options]
check - Compare documentation against code to find discrepanciesfix - Resolve identified drift issuesCompare documentation claims against actual code implementation.
| Argument | Required | Description |
|---|---|---|
[target] | No | Specific area: api, models, components, config, all (default: all) |
--since=<ref> | No | Check changes since date, tag, or commit (e.g., v1.0.0, 2024-01-01, abc123) |
--ignore=<patterns> | No | Comma-separated patterns to ignore (e.g., tests/*,*.draft.md) |
--severity=<level> | No | Minimum severity to report: info, warning, error (default: warning) |
The sync check classifies every documented item into one of four categories:
| Status | Symbol | Meaning | Action Needed |
|---|---|---|---|
| Implemented | ✅ | Code matches documentation exactly | None |
| Partial | ⚠️ | Code exists but differs from docs | Review and update |
| Not Implemented | ❌ | Documented but missing in code | Remove or mark as planned |
| Undocumented | 📝 | In code but not documented | Add documentation |
1. PARSE DOCUMENTATION
├── Scan all documentation files
├── Extract documented items:
│ ├── API Endpoints
│ │ ├── Route path
│ │ ├── HTTP method
│ │ ├── Request parameters
│ │ ├── Request body schema
│ │ ├── Response schema
│ │ └── Authentication requirements
│ │
│ ├── Models/Entities
│ │ ├── Properties and types
│ │ ├── Relationships
│ │ ├── Validations
│ │ └── Methods
│ │
│ ├── Components
│ │ ├── Props and types
│ │ ├── Events/callbacks
│ │ ├── Slots/children
│ │ └── Methods
│ │
│ ├── Functions/Services
│ │ ├── Signature
│ │ ├── Parameters
│ │ ├── Return type
│ │ └── Side effects
│ │
│ └── Configuration
│ ├── Environment variables
│ ├── Config options
│ └── Feature flags
│
└── Build DOCUMENTATION INVENTORY
2. SCAN CODEBASE
├── Identify source files by type
├── Extract actual implementations:
│ ├── Route definitions
│ │ ├── Path patterns
│ │ ├── Methods
│ │ ├── Middleware
│ │ └── Handler signatures
│ │
│ ├── Model definitions
│ │ ├── Properties
│ │ ├── Relationships
│ │ ├── Accessors/mutators
│ │ └── Scopes
│ │
│ ├── Component definitions
│ │ ├── Props
│ │ ├── Emits
│ │ ├── Expose
│ │ └── Slots
│ │
│ ├── Function exports
│ │ ├── Signatures
│ │ ├── Types
│ │ └── JSDoc
│ │
│ └── Config references
│ ├── env() calls
│ ├── config() calls
│ └── Feature checks
│
└── Build CODE INVENTORY
3. COMPARE INVENTORIES
├── Match documentation items to code items
│
├── For each DOCUMENTED item:
│ ├── Search for matching code item
│ ├── If EXACT MATCH found:
│ │ └── ✅ Implemented
│ ├── If PARTIAL MATCH found:
│ │ ├── ⚠️ Partial
│ │ └── Record differences
│ └── If NOT FOUND:
│ └── ❌ Not Implemented
│
├── For each CODE item without documentation:
│ └── 📝 Undocumented
│
└── Generate comparison results
4. DETAILED ANALYSIS (for partial matches)
├── Parameter differences
│ ├── Missing parameters
│ ├── Extra parameters
│ ├── Type mismatches
│ └── Default value changes
│
├── Schema differences
│ ├── Missing fields
│ ├── Extra fields
│ ├── Type changes
│ └── Required/optional changes
│
├── Behavior differences
│ ├── Return type changes
│ ├── Error handling changes
│ └── Side effect changes
│
└── Version/deprecation info
5. OUTPUT REPORT
Sync Check Report
=================
Target: all | Since: HEAD~10
Analyzed: 45 documented items | 52 code items
SUMMARY
───────
✅ Implemented: 32 (71%)
⚠️ Partial: 5 (11%)
❌ Not Implemented: 8 (18%)
📝 Undocumented: 7
═══════════════════════════════════════════════════════════════
⚠️ PARTIAL IMPLEMENTATIONS (5)
Code exists but differs from documentation
───────────────────────────────────────────────────────────────
1. POST /api/users
├── Doc: docs/api/users.md:34
├── Code: app/Http/Controllers/UserController.php:45
└── Issues:
• Parameter mismatch:
- Doc says: "role" is required
- Code has: "role" is optional (default: "user")
• Missing in docs:
- "email_verified" (required, boolean)
• Response difference:
- Doc shows: { user: {...} }
- Code returns: { data: { user: {...} }, meta: {...} }
2. User Model
├── Doc: docs/models/user.md:12
├── Code: app/Models/User.php:1
└── Issues:
• Missing property in docs:
- preferences (json, nullable)
• Documented but not in code:
- hasMany(Post) relationship
• Type mismatch:
- Doc: email_verified (boolean)
- Code: email_verified_at (timestamp, nullable)
═══════════════════════════════════════════════════════════════
❌ NOT IMPLEMENTED (8)
Documented features not found in code
───────────────────────────────────────────────────────────────
1. DELETE /api/users/:id/avatar
├── Doc: docs/api/users.md:78
└── Status: Route not defined in any route file
└── Action: Remove from docs OR implement feature
2. User.softDeletes
├── Doc: docs/models/user.md:45
└── Status: SoftDeletes trait not used in model
└── Action: Remove from docs OR add trait to model
3. GET /api/reports/export
├── Doc: docs/api/reports.md:23
└── Status: ReportsController has no export method
└── Action: Remove from docs OR implement method
[... more items ...]
═══════════════════════════════════════════════════════════════
📝 UNDOCUMENTED (7)
Code features without documentation
───────────────────────────────────────────────────────────────
1. GET /api/users/export
├── Code: routes/api.php:45
├── Handler: UserController@export
└── Suggested doc: docs/api/users.md
2. User::getPreferencesAttribute()
├── Code: app/Models/User.php:89
└── Suggested doc: docs/models/user.md
3. CACHE_DRIVER environment variable
├── Code: config/cache.php:15
└── Suggested doc: docs/configuration.md
[... more items ...]
═══════════════════════════════════════════════════════════════
RECOMMENDATIONS
───────────────
Priority 1 (Errors - misleading docs):
• Update POST /api/users documentation with correct parameters
• Remove DELETE /api/users/:id/avatar or implement it
Priority 2 (Warnings - incomplete docs):
• Document GET /api/users/export endpoint
• Update User model documentation
Priority 3 (Info - minor gaps):
• Add CACHE_DRIVER to configuration docs
═══════════════════════════════════════════════════════════════
Next Steps:
/docs-specialist:sync fix # Fix interactively
/docs-specialist:sync fix --auto # Auto-fix all
/docs-specialist:docs generate api # Regenerate API docs
# Full sync check
/docs-specialist:sync check
# Check only API documentation
/docs-specialist:sync check api
# Check only models
/docs-specialist:sync check models
# Check changes since last release
/docs-specialist:sync check --since=v1.0.0
# Check changes in last week
/docs-specialist:sync check --since=2024-01-01
# Ignore test files
/docs-specialist:sync check --ignore="tests/*,*.test.ts,*.spec.ts"
# Only show errors (hide warnings and info)
/docs-specialist:sync check --severity=error
# Full check with all details
/docs-specialist:sync check all --severity=info
Resolve identified drift issues between docs and code.
| Argument | Required | Description |
|---|---|---|
--severity=<level> | No | Fix issues of this severity and above: info, warning, error (default: warning) |
--interactive | No | Confirm each fix before applying (default: true) |
--auto | No | Apply all fixes without confirmation |
--dry-run | No | Show what would be fixed without making changes |
| Category | Default Fix Strategy | Alternative Actions |
|---|---|---|
| ⚠️ Partial | Update docs to match code | Mark as intentional, Flag code issue |
| ❌ Not Implemented | Remove from docs | Mark as "planned", Flag for implementation |
| 📝 Undocumented | Generate documentation | Mark as internal/private, Skip |
1. LOAD SYNC RESULTS
├── Run sync check if not recent
└── Load issues by category
2. FOR EACH ISSUE (interactive mode)
├── Display issue details
├── Show current doc content
├── Show current code content
├── Present options:
│ │
│ ├── [U] Update docs to match code
│ │ └── Generate updated documentation
│ │
│ ├── [R] Remove from docs
│ │ └── Delete the documented item
│ │
│ ├── [P] Mark as planned
│ │ └── Add "Planned" or "Coming Soon" marker
│ │
│ ├── [G] Generate new docs
│ │ └── Create documentation for code item
│ │
│ ├── [I] Mark as intentional
│ │ └── Add comment noting intentional difference
│ │
│ ├── [F] Flag for code change
│ │ └── Create TODO in code or issue tracker
│ │
│ ├── [S] Skip
│ │ └── Leave as-is for now
│ │
│ └── [Q] Quit
│ └── Stop processing
│
└── Apply selected action
3. APPLY FIXES
├── Make documentation changes
├── Track what was modified
└── Verify changes
4. REPORT RESULTS
├── Summary of fixes applied
├── Remaining issues
└── Files modified
Sync Fix - Issue 1 of 15
════════════════════════
⚠️ PARTIAL: POST /api/users
Documentation (docs/api/users.md:34):
┌─────────────────────────────────────────────
│ ### Create User
│ POST /api/users
│
│ Parameters:
│ - name (string, required)
│ - email (string, required)
│ - role (string, required)
│
│ Response: { user: {...} }
└─────────────────────────────────────────────
Code (UserController.php:45):
┌─────────────────────────────────────────────
│ public function store(Request $request)
│ {
│ $validated = $request->validate([
│ 'name' => 'required|string',
│ 'email' => 'required|email',
│ 'role' => 'string', // optional!
│ 'email_verified' => 'required|boolean',
│ ]);
│ ...
│ return response()->json([
│ 'data' => ['user' => $user],
│ 'meta' => ['created_at' => now()]
│ ]);
│ }
└─────────────────────────────────────────────
Differences:
• role: required → optional (default: "user")
• email_verified: missing in docs (required)
• Response wrapper: { user } → { data: { user }, meta }
Actions:
[U] Update docs to match code
[I] Mark as intentional difference
[F] Flag for code review
[S] Skip for now
[Q] Quit
Choice [U/I/F/S/Q]: U
✓ Updated docs/api/users.md
- Changed role to optional
- Added email_verified parameter
- Updated response format
Press Enter to continue...
# Interactive fix (recommended)
/docs-specialist:sync fix
# Preview what would be fixed
/docs-specialist:sync fix --dry-run
# Auto-fix all issues (update docs to match code)
/docs-specialist:sync fix --auto
# Fix only errors (skip warnings)
/docs-specialist:sync fix --severity=error
# Fix everything including minor issues
/docs-specialist:sync fix --severity=info
/docs-specialist:sync check # See what's out of sync
/docs-specialist:sync fix # Fix the issues
/docs-specialist:sync check --severity=error # Check for critical issues
/docs-specialist:docs validate # Full quality check
/docs-specialist:sync check --since=v1.0.0 # Check since last release
/docs-specialist:sync fix --severity=warning # Fix important issues
# Fail build if critical sync issues exist
/docs-specialist:sync check --severity=error --report=json
# Exit code non-zero if errors found
sync check before sync fix to see the full picture--dry-run first when using --auto--since to focus on recent changes during active development