---
description: Analyze implementation gap between requirements and existing codebase
allowed-tools: Bash, Glob, Grep, Read, Write, Edit, MultiEdit, WebSearch, WebFetch
argument-hint: <feature-name>
---

# Implementation Gap Validation

<background_information>
- **Role**: Bridge the space between what the requirements demand and what the codebase already provides, giving the design phase a clear picture of existing assets, missing capabilities, and viable implementation strategies.
- **Success Criteria**:
  - Existing codebase components and conventions are thoroughly understood
  - Missing capabilities and integration challenges are explicitly named
  - Multiple credible implementation approaches are evaluated with trade-offs
  - Areas requiring further investigation during design are flagged rather than assumed
</background_information>

<instructions>
## Core Task
Analyze the implementation gap for feature **$1** by comparing approved requirements against the existing codebase.

## Execution Steps

1. **Load Spec and Steering Context**:
   - Read `{{SDD_DIR}}/specs/$1/spec.json` to obtain language and metadata
   - Read `{{SDD_DIR}}/specs/$1/requirements.md` for the requirement set
   - Read the entire `{{SDD_DIR}}/steering/` directory (core + all custom files) for full project context — this ensures analysis is grounded in known patterns, architecture decisions, and conventions

2. **Load the Analysis Framework**:
   - Read `{{SDD_DIR}}/settings/rules/gap-analysis.md` for the structured investigation approach

3. **Execute the Gap Analysis**:
   - Apply the full `gap-analysis.md` framework — do not skip sections
   - Use Grep and Read to deeply investigate the existing codebase
   - Use WebSearch/WebFetch if external dependency research is needed
   - Assess each implementation approach (extend existing / create new / hybrid)
   - Produce all output in the language specified in `spec.json`

4. **Deliver the Analysis**:
   - Follow the output checklist defined in `gap-analysis.md`
   - Present multiple viable approaches with honest trade-offs
   - Explicitly mark areas where deeper research is deferred to the design phase

## Important Constraints
- **Inform, do not decide**: Provide analysis and options — leave the final implementation choice to the human reviewer
- **Multiple options required**: Always present at least two credible approaches when they exist
- **Thorough codebase investigation**: Use tooling to confirm findings rather than assuming
- **Flag unknowns explicitly**: Unresolved areas must be labeled "Research Needed" — do not paper over them
</instructions>

## Tool Guidance
- **Read first**: Load spec, steering, and analysis rules before touching the codebase
- **Grep extensively**: Search for domain patterns, naming conventions, existing services, and data models
- **WebSearch/WebFetch**: Research external dependencies or best practices when the codebase alone is insufficient
- **Write last**: Deliver the analysis only after complete investigation

## Output Description

Report in the language specified in `spec.json`:

1. **Analysis Summary**: 3–5 bullet points covering scope, key challenges, and headline recommendations
2. **Approach**: Confirm which analysis framework and tools were applied
3. **Next Steps**: Guide the user toward the design phase

**Formatting Rules**:
- Use Markdown headings for each analysis section
- Keep the summary under 300 words
- Detailed findings follow the output guidelines in `gap-analysis.md`

## Safety & Fallback

### Error Scenarios
- **Missing Requirements**: If `requirements.md` does not exist, halt with: "Run `/sdd:spec-requirements $1` to generate requirements before gap analysis"
- **Requirements Not Yet Approved**: Warn the user but proceed — gap analysis findings may actually inform requirement adjustments
- **Empty Steering Directory**: Warn that project context is missing and analysis quality may be reduced
- **Integration Complexity Unclear**: Flag the area for comprehensive research during design rather than blocking gap analysis
- **Language Not Set**: Default to English (`en`) if `spec.json` omits a language value

### Next Phase: Design Generation

**When Analysis Is Complete**:
- Review the gap analysis findings
- Run `/sdd:spec-design $1` to begin the technical design phase
- Or run `/sdd:spec-design $1 -y` to auto-approve requirements and proceed directly to design

**Note**: Gap analysis is optional but strongly recommended for brownfield projects. The findings feed directly into the design discovery phase and reduce surprises during implementation.
