Gap Analysis

Systematically identify discrepancies between documented requirements, specifications, and actual implementation through comprehensive comparison, analysis, and gap identification to improve system completeness and accuracy.

When to use me

Use this skill when:

Requirements documentation exists but implementation status is unclear
Specifications have evolved but documentation hasn't been updated
Code changes have been made without corresponding documentation updates
Preparing for audits, compliance checks, or quality assessments
Onboarding new team members who need accurate system understanding
Planning refactoring or modernization efforts
Validating that implementation matches design intentions
Identifying technical debt in undocumented features
Assessing risk from undocumented behavior

What I do

1. Documentation Analysis

Parse various documentation formats (Markdown, YAML, JSON, Confluence, Google Docs exports)
Extract requirements and specifications from structured and unstructured text
Identify documented features, constraints, and behaviors
Categorize requirements by type (functional, non-functional, business, technical)
Assess documentation quality (completeness, clarity, consistency, currency)

2. Implementation Analysis

Analyze source code to identify implemented features and behaviors
Examine API contracts and interfaces for exposed capabilities
Review database schemas and data models for persistent structures
Inspect configuration files for system behavior settings
Analyze deployment artifacts for runtime characteristics

3. Gap Identification

Compare documented vs. implemented features to identify mismatches
Detect undocumented implementations (features without documentation)
Identify unimplemented documentation (documented but not built)
Spot behavioral discrepancies (documented behavior vs. actual behavior)
Find specification drift where implementation diverged from original specs

4. Gap Classification & Prioritization

Categorize gaps by type (missing, incomplete, incorrect, outdated)
Assess gap severity (critical, high, medium, low)
Estimate effort to address each gap
Prioritize gaps based on impact, risk, and effort
Group related gaps for efficient resolution

5. Recommendations & Remediation Planning

Generate gap resolution recommendations for each identified discrepancy
Create remediation plans with actionable steps
Suggest documentation updates to align with implementation
Propose implementation changes to match documentation
Design verification strategies to confirm gap closure

Analysis Techniques

Document Parsing Patterns

document_sources:
  requirements:
    patterns:
      - "As a [role], I want [feature] so that [benefit]"
      - "The system shall [requirement]"
      - "Must support [capability]"
      - "Should be able to [action]"
  
  specifications:
    patterns:
      - "### Feature: [name]"
      - "**Specification:** [details]"
      - "| Parameter | Type | Required | Description |"
      - "API endpoint: [method] [path]"
  
  architecture:
    patterns:
      - "Component: [name]"
      - "Responsibility: [description]"
      - "Interfaces: [list]"
      - "Data flow: [description]"

Code Analysis Approaches

def analyze_implementation(codebase_path):
    """
    Analyze code implementation for features and behaviors.
    """
    features = extract_features_from_code(codebase_path)
    apis = extract_api_endpoints(codebase_path)
    data_models = extract_data_models(codebase_path)
    configs = parse_configuration_files(codebase_path)
    
    return {
        'implemented_features': features,
        'api_endpoints': apis,
        'data_models': data_models,
        'configurations': configs,
        'behavioral_patterns': extract_behavioral_patterns(codebase_path)
    }

Gap Detection Algorithms

class GapAnalyzer:
    def detect_gaps(self, documented, implemented):
        """
        Detect gaps between documented and implemented items.
        """
        gaps = {
            'undocumented_implementations': [],
            'unimplemented_documentation': [],
            'behavioral_mismatches': [],
            'specification_drift': []
        }
        
        # Find undocumented implementations
        for impl_item in implemented:
            if not self.is_documented(impl_item, documented):
                gaps['undocumented_implementations'].append(impl_item)
        
        # Find unimplemented documentation
        for doc_item in documented:
            if not self.is_implemented(doc_item, implemented):
                gaps['unimplemented_documentation'].append(doc_item)
        
        # Find behavioral mismatches
        for doc_item in documented:
            impl_item = self.find_matching_implementation(doc_item, implemented)
            if impl_item and not self.behaviors_match(doc_item, impl_item):
                gaps['behavioral_mismatches'].append({
                    'documented': doc_item,
                    'implemented': impl_item,
                    'differences': self.find_differences(doc_item, impl_item)
                })
        
        return gaps

Gap Types

1. Missing Documentation

Symptoms: Feature exists in code but has no documentation Impact: Knowledge silos, difficult maintenance, increased onboarding time Example: API endpoint implemented but not documented in API docs

2. Missing Implementation

Symptoms: Documented feature not found in code Impact: Unmet expectations, broken promises, customer dissatisfaction Example: "Export to PDF" documented but not implemented

3. Behavioral Mismatch

Symptoms: Documentation describes different behavior than implementation Impact: Bugs, integration issues, unexpected behavior Example: Documentation says "case-insensitive search" but implementation is case-sensitive

4. Outdated Documentation

Symptoms: Documentation references deprecated features or old interfaces Impact: Confusion, incorrect usage, wasted development time Example: Documentation shows old API version 1.0 but implementation is 2.0

5. Incomplete Documentation

Symptoms: Documentation exists but lacks important details Impact: Partial understanding, guesswork, implementation errors Example: API documented but missing error responses or rate limits

6. Over-specified Documentation

Symptoms: Documentation specifies details not reflected in implementation Impact: Implementation flexibility reduced, maintenance burden increased Example: Documentation specifies exact algorithm but implementation uses different approach

Examples

# Analyze gaps between requirements docs and implementation
npm run gap-analysis:analyze -- --requirements requirements.md --code src/ --output gaps.json

# Compare API documentation with actual implementation
npm run gap-analysis:compare -- --api-docs api.md --code src/api/ --output api-gaps.yaml

# Identify undocumented features
npm run gap-analysis:undocumented -- --code src/ --docs docs/ --output undocumented-features.md

# Check for unimplemented requirements
npm run gap-analysis:unimplemented -- --requirements specs/ --code src/ --output missing-features.json

# Generate remediation plan
npm run gap-analysis:remediate -- --gaps gaps.json --output remediation-plan.md

# Continuous gap monitoring
npm run gap-analysis:monitor -- --watch --requirements docs/ --code src/ --alert-on-gap

Output format

Gap Analysis Report:

Gap Analysis Report
───────────────────
System: User Management Service
Analysis Date: 2026-02-26
Documents Analyzed: 3 (requirements.md, api-spec.yaml, architecture.md)
Code Analyzed: 42 files, 8,567 lines

Summary:
✅ Documented & Implemented: 28 features (70%)
⚠️  Documented but Not Implemented: 6 features (15%)
⚠️  Implemented but Not Documented: 4 features (10%)
❌ Behavioral Mismatches: 2 features (5%)

Gap Details:

1. CRITICAL: Missing Implementation
   • Feature: "User password reset via email"
   • Location: requirements.md:45
   • Impact: Security feature missing
   • Effort: Medium (3-5 days)
   • Recommendation: Implement password reset flow

2. HIGH: Missing Documentation
   • Feature: "User session invalidation on role change"
   • Location: src/auth/session.js:123
   • Impact: Undocumented security behavior
   • Effort: Low (2 hours)
   • Recommendation: Document in security.md

3. MEDIUM: Behavioral Mismatch
   • Documented: "Search returns max 100 results"
   • Implemented: "Search returns max 50 results"
   • Location: api.md:89 vs src/search.js:45
   • Impact: Performance vs functionality tradeoff
   • Effort: Low (configuration change)
   • Recommendation: Align implementation with docs or update docs

4. LOW: Outdated Documentation
   • Documented: "API version 1.2"
   • Implemented: "API version 2.0"
   • Location: api.md:1 (header)
   • Impact: Confusion for API consumers
   • Effort: Low (documentation update)
   • Recommendation: Update API documentation

Priority Matrix:
┌─────────────┬─────────┬─────────┬──────────────┐
│ Priority    │ Count   │ Effort  │ Risk         │
├─────────────┼─────────┼─────────┼──────────────┤
│ Critical    │ 1       │ 3-5 days│ Security     │
│ High        │ 2       │ 1 day   │ Compliance   │
│ Medium      │ 3       │ 2 days  │ User Experience│
│ Low         │ 6       │ 3 days  │ Maintenance  │
└─────────────┴─────────┴─────────┴──────────────┘

Remediation Plan:
1. Week 1: Address critical security gap (password reset)
2. Week 2: Document undocumented security features
3. Week 3: Align behavioral mismatches
4. Week 4: Update outdated documentation
5. Ongoing: Implement gap monitoring to prevent recurrence

Gap Analysis JSON Output:

{
  "analysis": {
    "system": "user-management",
    "timestamp": "2026-02-26T19:00:00Z",
    "documents_analyzed": ["requirements.md", "api-spec.yaml"],
    "code_analyzed": ["src/", "lib/"],
    "summary": {
      "total_features": 40,
      "documented_and_implemented": 28,
      "documented_not_implemented": 6,
      "implemented_not_documented": 4,
      "behavioral_mismatches": 2,
      "gap_percentage": 30
    }
  },
  "gaps": [
    {
      "id": "gap-001",
      "type": "missing_implementation",
      "severity": "critical",
      "description": "User password reset via email not implemented",
      "document_reference": "requirements.md:45",
      "code_reference": null,
      "impact": "Security feature missing, violates compliance requirements",
      "effort_estimate": "3-5 days",
      "recommendation": "Implement password reset flow with email verification",
      "owner": "security-team",
      "due_date": "2026-03-05"
    },
    {
      "id": "gap-002",
      "type": "missing_documentation",
      "severity": "high",
      "description": "User session invalidation on role change not documented",
      "document_reference": null,
      "code_reference": "src/auth/session.js:123",
      "impact": "Undocumented security behavior, audit finding risk",
      "effort_estimate": "2 hours",
      "recommendation": "Add to security documentation and API docs",
      "owner": "documentation-team",
      "due_date": "2026-03-01"
    }
  ],
  "remediation_plan": {
    "phases": [
      {
        "phase": 1,
        "name": "Critical Security Gaps",
        "duration": "1 week",
        "gaps": ["gap-001"],
        "deliverables": ["Password reset implementation", "Security review"]
      },
      {
        "phase": 2,
        "name": "Documentation Cleanup",
        "duration": "1 week",
        "gaps": ["gap-002"],
        "deliverables": ["Updated security docs", "API documentation"]
      }
    ],
    "total_effort": "2 weeks",
    "priority_order": ["gap-001", "gap-002"],
    "success_criteria": ["All critical gaps closed", "Documentation coverage > 90%"]
  }
}

Gap Monitoring Dashboard:

Gap Monitoring Dashboard
────────────────────────
Status: ACTIVE
Last Analysis: 2026-02-26 19:00:00
Next Analysis: 2026-02-27 07:00:00

Trends:
┌──────────────────────────────────────┐
│ Gap Trend (Last 30 Days)            │
│                                      │
│ 40 ┤                                │
│    │                                │
│ 30 ┤                █               │
│    │               █ █              │
│ 20 ┤              █   █             │
│    │             █     █            │
│ 10 ┤           █       █           │
│    │          █         █          │
│  0 ┼───────────█─────────█─────────│
│     1   5   10   15   20   25   30 │
│              Days                  │
└──────────────────────────────────────┘

Current Gaps by Type:
• Missing Documentation: 4 (33%)
• Missing Implementation: 3 (25%)
• Behavioral Mismatch: 3 (25%)
• Outdated Documentation: 2 (17%)

Gap Age Distribution:
• < 1 week: 6 gaps
• 1-4 weeks: 4 gaps
• 1-3 months: 2 gaps
• > 3 months: 0 gaps

Alert Status:
✅ No critical gaps
⚠️  2 high-priority gaps aging > 2 weeks
✅ Documentation coverage: 85%
✅ Implementation coverage: 90%

Recommended Actions:
1. Address 2 high-priority gaps aging > 2 weeks
2. Improve documentation for 4 undocumented features
3. Schedule review for 3 behavioral mismatches

Notes

Gap analysis is not a blame exercise - focus on improving the system, not assigning fault
Regular gap analysis prevents accumulation - small, frequent analyses are better than large, infrequent ones
Automate where possible - continuous gap detection catches issues early
Involve stakeholders - developers, product managers, and technical writers should collaborate on gap resolution
Prioritize based on impact - not all gaps are equally important
Track gap closure - measure progress in reducing gaps over time
Use gap analysis proactively - not just for problem detection but for quality improvement
Integrate with development workflow - gap analysis should inform planning and prioritization
Document the analysis process - so it can be repeated and improved
Celebrate gap reduction - recognize improvements in system completeness and accuracy

gap-analysis

Safety Notice

Copy this and send it to your AI assistant to learn