drift-detect

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 Sonnet call for deep semantic analysis.

Architecture

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

Data collection: No LLM calls - pure JavaScript Semantic analysis: Single Sonnet 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 Sonnet 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	sonnet

Workflow

/drift-detect
        │
        ├─→ Parse command flags
        │
        ├─→ JavaScript Data Collection (parallel, no LLM)
        │   ├─ scanGitHubState()
        │   ├─ analyzeDocumentation()
        │   └─ scanCodebase()
        │
        └─→ Single Sonnet 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

Repo-Intel (optional, auto-detected)

• Doc files with low code coupling - likely stale documentation
• Directory-level health: owners, hotspot score, bug-fix rate
• At-risk and needs-attention areas for focused drift analysis

Requires: agent-analyzer binary and a cached repo-intel.json map. If no map exists, the scan prompts to generate one (~5 seconds).

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