validating-roadmaps

name	validating-roadmaps
description	Validates roadmap completeness, phase coherence, and alignment with constitution. Use when creating roadmaps, reviewing planning documents, or ensuring strategic consistency.

Validating Roadmap

Core Responsibilities

1. Specification Consistency Review

• Review all specification documents
• Identify contradictions between specs (data storage, API designs, feature requirements)
• Flag inconsistencies in terminology, naming conventions, technical decisions
• Verify implementation details align across all specifications

2. Gap Analysis

• Identify missing requirements that could cause confusion during implementation
• Find areas where specifications are too vague or ambiguous for coding
• Highlight missing technical details (APIs, data structures, error handling)
• Spot missing user experience considerations or edge cases

3. Roadmap Validation

• Ensure roadmap phases are realistic and dependencies clearly identified
• Validate that feature prioritization makes sense
• Check that breaking changes are properly documented
• Verify that implementation priorities align with architectural decisions

4. Roadmap Tidiness

• Identify specifications that are clearly already completed
• Recommend moving completed specs to appropriate archive directories

Review Process

Phase 1: Document Inventory

1. Read and catalog all specification documents
2. Create comprehensive index of features, requirements, technical decisions
3. Map dependencies between different components and features
4. Identify which specs are in-progress vs completed vs planned

Phase 2: Contradiction Detection

Review across all specs for conflicts in:

Storage Strategy

• Compare storage approaches across specs
• Check for inconsistent ID formats (ULID vs auto-incrementing, etc.)
• Validate persistence strategies for different components
• Note conflicting data model decisions

Integration Interfaces

• Communication protocols consistency
• API contract alignment
• Data format agreements
• Integration point definitions

Technical Decisions

• Architecture pattern conflicts
• Technology stack inconsistencies
• Conflicting performance requirements
• Incompatible security approaches

Phase 3: Gap Identification

Implementation Details

• Missing error handling specifications
• Unclear API contracts between components
• Ambiguous configuration requirements
• Incomplete validation rules

User Experience

• Missing user interaction flows
• Unclear progress indication requirements
• Incomplete error message specifications
• Missing accessibility considerations

Technical Architecture

• Missing performance requirements
• Unclear scalability considerations
• Missing security specifications
• Incomplete testing requirements

Output Format

Structure your findings as follows:

Executive Summary

• Number of documents reviewed
• Total contradictions found
• Critical gaps identified
• Overall specification quality assessment

Contradictions Found

For each contradiction:

#### Contradiction #X: [Brief Title]
**Documents**: [List conflicting specs]
**Issue**: [Description of the contradiction]
**Impact**: [How this affects implementation]
**Recommendation**: [Suggested resolution]
**Priority**: High/Medium/Low

Implementation Gaps

For each gap:

#### Gap #X: [Brief Title]
**Affected Areas**: [Components/features affected]
**Issue**: [Description of what's missing]
**Risk**: [Potential implementation problems]
**Recommendation**: [What needs to be added/clarified]
**Priority**: High/Medium/Low

Specification Quality Issues

• Ambiguous language that needs clarification
• Missing technical diagrams or examples
• Inconsistent terminology usage
• Areas needing more detailed examples

Roadmap Recommendations

• Suggested priority adjustments
• Missing dependencies that should be addressed
• Features that should be moved between versions/phases
• New features/requirements that should be added
• Completed specifications that should be archived

Key Focus Areas

Data Architecture

• File-based vs database storage decisions
• ID format consistency
• Concurrent access strategies
• Data migration plans

API Design

• Endpoint naming consistency
• Parameter format standardization
• Error response formats
• Authentication/authorization patterns

Configuration Management

• Configuration file formats and locations
• Environment variable usage
• Default value specifications
• Validation requirements

Success Criteria

A successful review should:

1. Identify all major contradictions that would cause implementation confusion
2. Highlight critical gaps that could block development progress
3. Provide actionable recommendations with clear priorities
4. Maintain specification quality by suggesting improvements to clarity and completeness
5. Validate roadmap coherence ensuring realistic implementation phases

Communication Style

• Be direct and specific about issues found
• Provide concrete examples when citing contradictions
• Offer practical solutions, not just problem identification
• Use clear priority levels (High/Medium/Low) for all findings
• Focus on developer experience and implementation clarity
• Maintain a constructive, solution-oriented tone

Integration with Workflows

Part of Housekeeping

This skill can be integrated into the housekeeping workflow as an optional phase when project has formal specifications and roadmap documents.

Before Sprint Planning

Run this review before planning new development sprints to ensure specifications are consistent and complete.

After Major Changes

When specifications are updated significantly, run validation to catch ripple effects and ensure consistency.

Use Cases

Pre-Implementation Review

User: "Review our specs before we start building" You: Read all specs, find contradictions, identify gaps, provide report with prioritized fixes

Specification Drift Detection

User: "We've updated several specs over time, check for inconsistencies" You: Compare related specs, find conflicting decisions, highlight areas needing reconciliation

Roadmap Health Check

User: "Is our roadmap realistic and consistent?" You: Review roadmap phases, validate dependencies, check for unrealistic expectations, recommend adjustments

Common Issues to Catch

Conflicting Technical Decisions

• Spec A says "use Redis for caching"
• Spec B says "use in-memory caching"
• Impact: Implementation confusion, potential architecture mismatch

Missing Dependencies

• Feature X requires Feature Y
• Feature Y not in roadmap or planned after Feature X
• Impact: Implementation blocked or requires out-of-order work

Ambiguous Requirements

• "System should be fast" without quantification
• "Handle errors properly" without specifics
• Impact: Implementation guesswork, inconsistent behavior

Incomplete Specifications

• Missing error handling approach
• No mention of edge cases
• Unclear acceptance criteria
• Impact: Implementation gaps, missed requirements

Related Skills

• writing-specifications - Create well-formed specs that pass validation
• refining-specifications - Reduce ambiguity in existing specs
• writing-plans - Create implementation plans from validated specs
• housekeeping - Regular project maintenance including spec validation