---
name: feature-gap-analysis
description: Compare a vision or spec against the actual codebase. Extracts a feature map from the vision, scans the codebase for each feature, and produces a prioritized gap list. Use at the start of milestone planning when you have a vision document but are unsure what's already built.
---

# Feature Gap Analysis: Vision → Feature Map → Codebase Diff

When you have a vision, spec, or existing `PROJECT.md` / `CONTEXT.md`, run this skill before planning milestones. It prevents building what's already there and surfaces the real gaps.

---

## Step 1: Extract the Feature Map

Read the vision inputs (in priority order, use all that exist):
- `.sf/PROJECT.md` — high-level project description
- `.sf/milestones/*/CONTEXT.md` — milestone intent
- `README.md` / `VISION.md` — top-level product description
- User-provided spec document

For each input, extract a flat list of **capabilities** the vision describes. A capability is a user-visible behavior or system property, not an implementation detail.

Format as a table:

| # | Capability | Source | Category |
|---|-----------|--------|----------|
| 1 | Users can log in with email+password | README.md | Auth |
| 2 | DR agent runs as a Windows service | VISION.md | Agent |
| 3 | Portal shows restore job status | PROJECT.md | UI |

Categories help with grouping: Auth, API, UI, Agent, Storage, Observability, Testing, Ops.

Keep entries atomic — one testable behavior per row. If a sentence describes 3 things, make 3 rows.

---

## Step 2: Scan the Codebase

For each capability, find evidence of implementation. Use `rg`, `find`, and file reads.

Scan strategy per category:
- **Auth**: look for login handlers, session/token code, middleware
- **API**: look for route definitions, handler files
- **UI**: look for page components, templates, routes
- **Agent**: look for service registration, main loop, config parsing
- **Storage**: look for DB schema, migration files, model structs
- **Observability**: look for metrics, structured logging, health endpoints
- **Testing**: look for test files, coverage data

Classify each capability:

| Status | Meaning |
|--------|---------|
| **Implemented** | Code exists, tests exist, it works |
| **Partial** | Code skeleton exists but incomplete — missing tests, edge cases, or integration |
| **Missing** | No evidence in codebase |
| **Unclear** | Code exists but purpose is ambiguous — needs investigation |

Quick scan commands:
```bash
# Find by keyword
rg -l "<feature keyword>" --type go

# Find test files for a component
find . -name "*_test.go" | xargs grep -l "<component>"

# Check migration coverage
ls migrations/

# Find handler registrations
rg "router\.|mux\.|r\.GET\|r\.POST" --type go | head -30
```

---

## Step 3: Produce the Gap List

Build the combined table:

| # | Capability | Status | Evidence | Gap Notes |
|---|-----------|--------|----------|-----------|
| 1 | Email+password login | Implemented | portal/auth/login.go | — |
| 2 | DR agent Windows service | Partial | dr-agent/main.go | No service installer, no graceful stop |
| 3 | Portal restore job status | Missing | — | No UI component, no API endpoint |

Then produce a prioritized gap list — **only Missing and Partial** entries, scored by impact:

```
HIGH (blocks core value prop):
  - [capability] — [what's missing]

MEDIUM (degrades experience but workaround exists):
  - [capability] — [what's missing]

LOW (polish, nice-to-have):
  - [capability] — [what's missing]
```

Score impact by: does blocking this prevent the product from being usable at all (HIGH), does it create a poor but functional experience (MEDIUM), or is it an enhancement (LOW)?

---

## Step 4: Update PM Memory

Append findings to `.sf/PM-STRATEGY.md` under an "## Feature Gap Analysis" section:

```markdown
## Feature Gap Analysis

_Date: YYYY-MM-DD_

### Feature Map Summary
- Total capabilities identified: N
- Implemented: N
- Partial: N  
- Missing: N

### High-Priority Gaps
- [capability]: [gap description]

### Recommendation
[1-2 sentences: which gaps should become the next milestone(s)]
```

---

## Rules

- **One capability per row** — never bundle multiple behaviors into one entry
- **Evidence required for Implemented** — "code exists" is not enough without a test
- **Partial ≠ Done** — if tests are missing or integration is broken, it's Partial
- **Don't scan every file** — target likely locations by category, not a full crawl
- **Gap list feeds milestone planning** — HIGH gaps are cannonball candidates for the next milestone

---

## Sources

- Teresa Torres, *Continuous Discovery Habits* — opportunity mapping, feature inventory
- Bob Moesta — struggling moments as requirements encoded in code
- Ryan Singer — appetite-based scoping, scope cutting discipline
