# Gap Analysis Process

## Objective
Map the distance between what the approved requirements demand and what the existing codebase already provides, producing a clear picture of implementation options, missing capabilities, and complexity that the design phase can act on.

---

## Analysis Framework

### 1. Current State Investigation

**Inventory domain-related assets**:
- Locate key files, modules, and directory layouts relevant to the feature domain
- Identify reusable services, utilities, and shared components that could be leveraged
- Characterize the dominant architectural patterns and any known constraints

**Extract existing conventions**:
- Naming patterns at the file, class/module, and variable levels
- Layering strategy and enforced dependency direction
- Import and export conventions
- Test file placement and test organization approach

**Map integration surfaces**:
- Existing data models and database schemas the feature must interact with
- API clients and service connectors already in the codebase
- Authentication and authorization mechanisms in use

### 2. Requirements Feasibility Analysis

**Enumerate technical needs from EARS requirements**:
- Data models and schema changes required
- New or modified APIs and service interfaces
- UI components or CLI interactions
- Business logic and validation rules
- Non-functional requirements: security controls, latency budgets, scalability targets, reliability guarantees

**Identify gaps and constraints**:
- Capabilities the current codebase lacks entirely
- Patterns that partially satisfy a requirement but need extension
- Architectural constraints that will limit the implementation approach
- Unknowns that cannot be resolved during gap analysis — label these "Research Needed" for the design phase

**Note complexity signals**:
- Straightforward CRUD operations
- Algorithmic or computational logic
- Multi-step workflows with branching paths
- External service integrations with unknown contracts

### 3. Implementation Approach Options

Present at least two viable options. Use the following option structures:

---

#### Option A: Extend Existing Components
**Consider when**: The feature fits naturally into existing modules and the modification scope is bounded.

- **Specific files and modules to extend**: Named candidates with a rationale for each
- **Compatibility assessment**: Does the extension preserve existing consumer contracts? Does it risk breaking changes?
- **Complexity and cohesion check**: Does adding this functionality keep the module's single responsibility intact? Is the file size still manageable?

**Trade-offs**:
- Fewer new files; faster initial delivery
- Reuses proven infrastructure and patterns
- Risk of bloating existing components beyond their intended scope
- May complicate existing logic if the feature is not a clean fit

---

#### Option B: Create New Components
**Consider when**: The feature has a distinct responsibility, or existing components are already complex or large.

- **Rationale for new creation**: Why a new boundary is justified
- **Integration approach**: How the new component connects to the existing system
- **Boundary definition**: What this component owns exclusively; what it delegates

**Trade-offs**:
- Clean separation of concerns; easier to test in isolation
- Reduces complexity burden on existing components
- More files to navigate and maintain
- Requires careful interface design to avoid tight coupling

---

#### Option C: Hybrid Approach
**Consider when**: The feature is too complex for a pure extension but does not warrant a complete new subsystem.

- **Division of responsibility**: Which portions extend existing components; which require new ones
- **Phasing strategy**: Minimum viable change first, followed by refactoring or new components
- **Risk mitigation**: Incremental rollout, feature flags, or configuration-driven activation where appropriate

**Trade-offs**:
- Balanced approach for complex features
- Allows iterative refinement without a big-bang rewrite
- Requires more upfront planning to avoid inconsistency

---

### 4. Out of Scope for Gap Analysis

Gap analysis is an orientation exercise, not a design exercise. The following activities belong in the design phase:

- Deep research into external APIs, library internals, or technology decisions
- Architectural pattern selection and evaluation
- Detailed interface contract definition
- Performance modeling or capacity planning

Record unknowns as concise "Research Needed" items pointing the design phase toward what must be investigated — do not attempt to resolve them here.

---

### 5. Implementation Complexity and Risk Estimate

**Effort sizing**:
- **S** (1–3 days): Follows established patterns with minimal new dependencies and a clear integration path
- **M** (3–7 days): Introduces some new patterns or moderate integration complexity
- **L** (1–2 weeks): Significant new functionality, multiple integrations, or complex workflows
- **XL** (2+ weeks): Architectural changes, unfamiliar technology, or broad system-wide impact

**Risk classification**:
- **High**: Unknown technology, complex external dependencies, architectural changes, or unclear performance and security path
- **Medium**: New patterns with prior guidance, manageable integrations, known solutions to identified challenges
- **Low**: Extension of established patterns, familiar technology, clear and bounded scope

---

## Output Checklist

A complete gap analysis delivers:

- [ ] **Requirement-to-Asset Map**: Each requirement paired with existing assets (if any) and gap classification — Missing, Partial, or Constrained
- [ ] **Implementation Options**: At minimum Options A and B with rationale and trade-offs; Option C when complexity warrants it
- [ ] **Effort Estimate**: S / M / L / XL with a one-sentence justification
- [ ] **Risk Level**: High / Medium / Low with a one-sentence justification
- [ ] **Design Phase Recommendations**: Preferred approach and the top three decisions the design phase must make
- [ ] **Research Needed Items**: Explicit list of unknowns deferred to the design phase

---

## Principles

- **Inform, do not decide**: Surface options and trade-offs — leave final implementation choices to the design phase and human review
- **Multiple credible options**: Always present genuine alternatives, not a predetermined answer with a strawman
- **Name gaps explicitly**: Vague language like "needs further investigation" is not sufficient — name the specific capability or question
- **Stay grounded in evidence**: Claims about the codebase must be supported by Grep or Read findings, not assumptions
- **Be honest about complexity**: Underestimating effort or risk here creates problems during implementation
