drift-detect

Deep repository analysis to realign project plans with actual code reality.

Overview

The drift-detect plugin performs comprehensive analysis of your codebase to identify drift between documented plans and actual implementation. It uses pure JavaScript for data collection (no LLM overhead) and a single Opus call for deep semantic analysis.

Architecture

/drift-detect
        │
        ├─→ collectors.js (pure JavaScript)
        │   ├─ scanGitHubState()     → issues, PRs, milestones
        │   ├─ analyzeDocumentation() → docs, plans, checkboxes
        │   └─ scanCodebase()        → structure, frameworks, health
        │
        └─→ plan-synthesizer (Opus)
            └─ Deep semantic analysis with full context

Data collection: No LLM calls - pure JavaScript Semantic analysis: Single Opus call with complete context Token efficiency: ~77% reduction vs. previous multi-agent architecture

Features

• Efficient data collection: JavaScript collectors for deterministic extraction
• Deep semantic analysis: Single Opus call for cross-referencing and insights
• Drift detection: Identifies where plans have diverged from reality
• Gap analysis: Finds missing tests, documentation, and implementation
• Priority ranking: Context-aware prioritization
• Command-line flags: No persistent settings files needed

Commands

/drift-detect

Run a comprehensive reality check scan.

/drift-detect                              # Full scan (default)
/drift-detect --sources github,docs        # Specific sources
/drift-detect --depth quick                # Quick scan
/drift-detect --output file --file report.md  # Custom output

Flag	Values	Default	Description
--sources	github,docs,code	all three	Which sources to scan
--depth	quick, thorough	thorough	How deep to analyze
--output	file, display, both	both	Where to output results
--file	path	drift-detect-report.md	Output file path

Agent

Agent	Purpose	Model
plan-synthesizer	Deep semantic analysis, drift detection, prioritization	opus

Workflow

/drift-detect
        │
        ├─→ Parse command flags
        │
        ├─→ JavaScript Data Collection (parallel, no LLM)
        │   ├─ scanGitHubState()
        │   ├─ analyzeDocumentation()
        │   └─ scanCodebase()
        │
        └─→ Single Opus Analysis Call
            ├─ Cross-reference docs vs code
            ├─ Identify drift patterns
            ├─ Find gaps
            └─ Generate prioritized plan
                    │
                    ▼
           Reality Check Report

Data Sources

GitHub (--sources github)

• Open issues categorized by labels (bug, feature, security)
• Open pull requests with draft status
• Milestones with due dates and completion
• Stale items (> 90 days inactive)
• Themes extracted from issue titles

Requires: gh CLI installed and authenticated

Documentation (--sources docs)

• README.md, CONTRIBUTING.md, CHANGELOG.md
• PLAN.md, CLAUDE.md
• docs/*.md
• Checkbox completion rates
• Feature lists and planned work

Code (--sources code)

• Directory structure analysis
• Framework detection (React, Express, Vue, etc.)
• Test framework detection (Jest, Mocha, Vitest)
• Health indicators (CI, linting, tests)
• Implemented features

Output

The scan produces:

1. Executive Summary: Overview of project state
2. Drift Analysis: Where plans diverge from reality (with evidence)
3. Gap Analysis: Missing tests, docs, implementation (with severity)
4. Cross-Reference: Documented vs. implemented features
5. Reconstruction Plan: Prioritized action items by timeframe

Example Output

# Reality Check Report

## Executive Summary
Project has moderate drift: 8 stale priority issues and 20% plan completion.
Strong code health (tests + CI) but documentation lags implementation.

## Drift Analysis

### Priority Neglect
**Severity**: high
8 high-priority issues inactive for 60+ days.
**Recommendation**: Triage stale issues - close, reassign, or deprioritize.

## Gap Analysis

### No Automated Tests
**Severity**: critical
**Impact**: High risk of regressions, difficult to refactor safely.
**Recommendation**: Add test framework and critical path coverage.

## Prioritized Plan

### Immediate (This Week)
1. **Close issue #45** - already implemented
2. **Address security vulnerability** in auth module

### Short-Term (This Month)
1. Add test coverage for API endpoints
2. Update README to reflect current features

Skills

drift-analysis

Provides knowledge for:

• Drift detection patterns and signals
• Prioritization framework
• Cross-reference matching logic
• Output templates

Requirements

• GitHub CLI (gh) for GitHub scanning
• Git repository
• Node.js

Breaking Changes from v1

• .claude/drift-detect.local.md settings file no longer used
• Use command flags instead: --sources, --depth, --output, --file
• Three scanner agents replaced with JavaScript collectors

License

MIT