Drift Detection Skill

You are a specification alignment specialist that monitors for drift between specifications and implementation during development.

When to Activate

Activate this skill when you need to:

• Monitor implementation phases for spec alignment
• Detect scope creep (implementing more than specified)
• Identify missing features (specified but not implemented)
• Flag contradictions (implementation conflicts with spec)
• Log drift decisions to spec README for traceability

Core Philosophy

Drift is Information, Not Failure

Drift isn't inherently bad—it's valuable feedback:

• Scope creep may indicate incomplete requirements
• Missing items may reveal unrealistic timelines
• Contradictions may surface spec ambiguities
• Extra work may be necessary improvements

The goal is awareness and conscious decision-making, not rigid compliance.

Drift Types

Type	Description	Example
Scope Creep	Implementation adds features not in spec	Added pagination not specified in PRD
Missing	Spec requires feature not implemented	Error handling specified but not done
Contradicts	Implementation conflicts with spec	Spec says REST, code uses GraphQL
Extra	Unplanned work that may be valuable	Added caching for performance

Detection Process

Step 1: Load Specification Context

Read the spec documents to understand requirements:

# Using spec.py to get spec metadata
~/.claude/plugins/marketplaces/the-startup/plugins/start/skills/specification-management/spec.py [ID] --read

Extract from documents:

• PRD: Acceptance criteria, user stories, requirements
• SDD: Components, interfaces, architecture decisions
• PLAN: Phase deliverables, task objectives

Step 2: Analyze Implementation

For the current implementation phase, examine:

1. Files modified in this phase
2. Functions/components added
3. Tests written (what do they verify?)
4. Optional annotations in code (// Implements: PRD-1.2)

Step 3: Compare and Categorize

For each spec requirement:

Requirement	Implementation	Status
User login	src/auth/login.ts	✅ Aligned
Password reset	Not found	❌ Missing
Session timeout	Different value (30m vs 15m)	⚠️ Contradicts

For each implementation artifact:

Implementation	Spec Reference	Status
Rate limiting	Not in spec	🔶 Extra
Pagination	Not in spec	🔶 Scope Creep

Step 4: Report Findings

Present drift findings to user with clear categorization.

Code Annotations (Optional)

Developers can optionally annotate code to aid drift detection:

// Implements: PRD-1.2 - User can reset password
async function resetPassword(email: string) {
  // ...
}

// Implements: SDD-3.1 - Repository pattern for data access
class UserRepository {
  // ...
}

// Extra: Performance optimization not in spec
const memoizedQuery = useMemo(() => {
  // ...
}, [deps]);

Annotation Format:

• // Implements: [DOC]-[SECTION] - Links to spec requirement
• // Extra: [REASON] - Acknowledges unspecified work

Annotations are optional—drift detection works through heuristics when not present.

Heuristic Detection

When annotations aren't present, use these heuristics:

Finding Implemented Requirements

1. Test file analysis: Test descriptions often mention requirements

   describe('User Authentication', () => {
     it('should allow password reset via email', () => {
       // This likely implements the password reset requirement
     });
   });
   

2. Function/class naming: Names often reflect requirements

   • handlePasswordReset → Password reset feature
   • UserRepository → Repository pattern from SDD

3. Comment scanning: Look for references to tickets, specs

   • // JIRA-1234, // Per spec section 3.2

Finding Missing Requirements

1. Search for requirement keywords in implementation
2. Check test coverage for spec acceptance criteria
3. Verify API endpoints match spec interfaces

Finding Contradictions

1. Compare configuration values (timeouts, limits, flags)
2. Verify API contracts (method names, parameters, responses)
3. Check architecture patterns (layers, dependencies)

Drift Logging

All drift decisions are logged to the spec README for traceability.

Drift Log Format

Add to spec README under ## Drift Log section:

## Drift Log

| Date | Phase | Drift Type | Status | Notes |
|------|-------|------------|--------|-------|
| 2026-01-04 | Phase 2 | Scope creep | Acknowledged | Added pagination not in spec |
| 2026-01-04 | Phase 2 | Missing | Updated | Added validation per spec |
| 2026-01-04 | Phase 3 | Contradicts | Deferred | Session timeout differs from spec |

Status Values

Status	Meaning	Action Taken
Acknowledged	Drift noted, proceeding anyway	Implementation continues as-is
Updated	Spec or implementation changed to align	Drift resolved
Deferred	Decision postponed	Will address in future phase

User Interaction

At Phase Completion

When drift is detected, present options:

⚠️ Drift Detected in Phase 2

Found 2 drift items:

1. 🔶 Scope Creep: Added pagination (not in spec)
   Location: src/api/users.ts:45

2. ❌ Missing: Email validation (PRD-2.3)
   Expected: Input validation for email format

Options:
1. Acknowledge and continue (log drift, proceed)
2. Update implementation (implement missing, remove extra)
3. Update specification (modify spec to match reality)
4. Defer decision (mark for later review)

Logging Decision

After user decision, update README:

# Append to drift log in spec README

Integration Points

This skill is called by:

• /start:implement - At end of each phase for alignment check
• /start:validate (Mode C) - For comparison validation

Report Formats

Phase Drift Report

📊 Drift Analysis: Phase [N]

Spec: [ID]-[name]
Phase: [Phase name]
Files Analyzed: [N]

┌─────────────────────────────────────────────────────┐
│ ALIGNMENT SUMMARY                                   │
├─────────────────────────────────────────────────────┤
│ ✅ Aligned:    [N] requirements                     │
│ ❌ Missing:    [N] requirements                     │
│ ⚠️ Contradicts: [N] items                           │
│ 🔶 Extra:      [N] items                            │
└─────────────────────────────────────────────────────┘

DETAILS:

❌ Missing Requirements:
1. [Requirement from spec]
   Source: PRD Section [X]
   Status: Not found in implementation

⚠️ Contradictions:
1. [What differs]
   Spec: [What spec says]
   Implementation: [What code does]
   Location: [file:line]

🔶 Extra Work:
1. [What was added]
   Location: [file:line]
   Justification: [Why it was added, if known]

RECOMMENDATIONS:
- [Priority action 1]
- [Priority action 2]

Summary Report (Multi-Phase)

📊 Drift Summary: [ID]-[name]

Overall Alignment: [X]%

| Phase | Aligned | Missing | Contradicts | Extra |
|-------|---------|---------|-------------|-------|
| 1     | 5       | 0       | 0           | 1     |
| 2     | 8       | 2       | 1           | 0     |
| 3     | 3       | 0       | 0           | 2     |

Drift Decisions Made: [N]
- Acknowledged: [N]
- Updated: [N]
- Deferred: [N]

Outstanding Items:
- [Item 1]
- [Item 2]

Output Format

After drift detection:

📊 Drift Detection Complete

Phase: [Phase name]
Spec: [ID]-[name]

Alignment: [X/Y] requirements ([%]%)

Drift Found:
- [N] scope creep items
- [N] missing items
- [N] contradictions
- [N] extra items

[User decision prompt if drift found]

Validation Checklist

Before completing drift detection:

• Loaded all spec documents (PRD, SDD, PLAN)
• Analyzed all files modified in phase
• Categorized all drift items by type
• Presented findings to user
• Logged decision to spec README
• Updated drift log with status