145 lines
5.0 KiB
Markdown
145 lines
5.0 KiB
Markdown
# Gap Analysis Process
|
||
|
||
## Objective
|
||
Analyze the gap between requirements and existing codebase to inform implementation strategy decisions.
|
||
|
||
## Analysis Framework
|
||
|
||
### 1. Current State Investigation
|
||
|
||
- Scan for domain-related assets:
|
||
- Key files/modules and directory layout
|
||
- Reusable components/services/utilities
|
||
- Dominant architecture patterns and constraints
|
||
|
||
- Extract conventions:
|
||
- Naming, layering, dependency direction
|
||
- Import/export patterns and dependency hotspots
|
||
- Testing placement and approach
|
||
|
||
- Note integration surfaces:
|
||
- Data models/schemas, API clients, auth mechanisms
|
||
|
||
### 2. Requirements Feasibility Analysis
|
||
|
||
- From EARS requirements, list technical needs:
|
||
- Data models, APIs/services, UI/components
|
||
- Business rules/validation
|
||
- Non-functionals: security, performance, scalability, reliability
|
||
|
||
- Identify gaps and constraints:
|
||
- Missing capabilities in current codebase
|
||
- Unknowns to be researched later (mark as "Research Needed")
|
||
- Constraints from existing architecture and patterns
|
||
|
||
- Note complexity signals:
|
||
- Simple CRUD / algorithmic logic / workflows / external integrations
|
||
|
||
### 3. Implementation Approach Options
|
||
|
||
#### Option A: Extend Existing Components
|
||
**When to consider**: Feature fits naturally into existing structure
|
||
|
||
- **Which files/modules to extend**:
|
||
- Identify specific files requiring changes
|
||
- Assess impact on existing functionality
|
||
- Evaluate backward compatibility concerns
|
||
|
||
- **Compatibility assessment**:
|
||
- Check if extension respects existing interfaces
|
||
- Verify no breaking changes to consumers
|
||
- Assess test coverage impact
|
||
|
||
- **Complexity and maintainability**:
|
||
- Evaluate cognitive load of additional functionality
|
||
- Check if single responsibility principle is maintained
|
||
- Assess if file size remains manageable
|
||
|
||
**Trade-offs**:
|
||
- ✅ Minimal new files, faster initial development
|
||
- ✅ Leverages existing patterns and infrastructure
|
||
- ❌ Risk of bloating existing components
|
||
- ❌ May complicate existing logic
|
||
|
||
#### Option B: Create New Components
|
||
**When to consider**: Feature has distinct responsibility or existing components are already complex
|
||
|
||
- **Rationale for new creation**:
|
||
- Clear separation of concerns justifies new file
|
||
- Existing components are already complex
|
||
- Feature has distinct lifecycle or dependencies
|
||
|
||
- **Integration points**:
|
||
- How new components connect to existing system
|
||
- APIs or interfaces exposed
|
||
- Dependencies on existing components
|
||
|
||
- **Responsibility boundaries**:
|
||
- Clear definition of what new component owns
|
||
- Interfaces with existing components
|
||
- Data flow and control flow
|
||
|
||
**Trade-offs**:
|
||
- ✅ Clean separation of concerns
|
||
- ✅ Easier to test in isolation
|
||
- ✅ Reduces complexity in existing components
|
||
- ❌ More files to navigate
|
||
- ❌ Requires careful interface design
|
||
|
||
#### Option C: Hybrid Approach
|
||
**When to consider**: Complex features requiring both extension and new creation
|
||
|
||
- **Combination strategy**:
|
||
- Which parts extend existing components
|
||
- Which parts warrant new components
|
||
- How they interact
|
||
|
||
- **Phased implementation**:
|
||
- Initial phase: minimal viable changes
|
||
- Subsequent phases: refactoring or new components
|
||
- Migration strategy if needed
|
||
|
||
- **Risk mitigation**:
|
||
- Incremental rollout approach
|
||
- Feature flags or configuration
|
||
- Rollback strategy
|
||
|
||
**Trade-offs**:
|
||
- ✅ Balanced approach for complex features
|
||
- ✅ Allows iterative refinement
|
||
- ❌ More complex planning required
|
||
- ❌ Potential for inconsistency if not well-coordinated
|
||
### 4. Out-of-Scope for Gap Analysis
|
||
|
||
- Defer deep research activities to the design phase.
|
||
- Record unknowns as concise "Research Needed" items only.
|
||
|
||
### 5. Implementation Complexity & Risk
|
||
|
||
- Effort:
|
||
- S (1–3 days): existing patterns, minimal deps, straightforward integration
|
||
- M (3–7 days): some new patterns/integrations, moderate complexity
|
||
- L (1–2 weeks): significant functionality, multiple integrations or workflows
|
||
- XL (2+ weeks): architectural changes, unfamiliar tech, broad impact
|
||
- Risk:
|
||
- High: unknown tech, complex integrations, architectural shifts, unclear perf/security path
|
||
- Medium: new patterns with guidance, manageable integrations, known perf solutions
|
||
- Low: extend established patterns, familiar tech, clear scope, minimal integration
|
||
|
||
### Output Checklist
|
||
|
||
- Requirement-to-Asset Map with gaps tagged (Missing / Unknown / Constraint)
|
||
- Options A/B/C with short rationale and trade-offs
|
||
- Effort (S/M/L/XL) and Risk (High/Medium/Low) with one-line justification each
|
||
- Recommendations for design phase:
|
||
- Preferred approach and key decisions
|
||
- Research items to carry forward
|
||
|
||
## Principles
|
||
|
||
- **Information over decisions**: Provide analysis and options, not final choices
|
||
- **Multiple viable options**: Offer credible alternatives when applicable
|
||
- **Explicit gaps and assumptions**: Flag unknowns and constraints clearly
|
||
- **Context-aware**: Align with existing patterns and architecture limits
|
||
- **Transparent effort and risk**: Justify labels succinctly
|