gh-jschulte-claude-plugins-stackshift/skills/gap-analysis/SKILL.md

name, description

name	description
gap-analysis	Route-aware gap analysis. For Brownfield - uses /speckit.analyze to compare specs against implementation. For Greenfield - validates spec completeness and asks about target tech stack for new implementation. This is Step 4 of 6 in the reverse engineering process.

Gap Analysis (Route-Aware)

Step 4 of 6 in the Reverse Engineering to Spec-Driven Development process.

Estimated Time: 15 minutes Prerequisites: Step 3 completed (.specify/ directory exists with specifications) Output: Route-specific analysis and implementation roadmap

---

Configuration Check (FIRST STEP!)

CRITICAL: Check detection type and route:

# Load state file
DETECTION_TYPE=$(cat .stackshift-state.json | jq -r '.detection_type // .path')
ROUTE=$(cat .stackshift-state.json | jq -r '.route // .path')

echo "Detection: $DETECTION_TYPE (what kind of app)"
echo "Route: $ROUTE (how to spec it)"

Routes:

• greenfield → Building NEW app (tech-agnostic specs)
• brownfield → Managing EXISTING app (tech-prescriptive specs)

Detection Types:

• generic → Standard application
• monorepo-service → Service in a monorepo
• nx-app → Nx workspace application
• turborepo-package → Turborepo package
• lerna-package → Lerna package

Based on route, this skill behaves differently!

Examples:

• Monorepo Service + Greenfield → Analyze spec completeness for platform migration
• Monorepo Service + Brownfield → Compare specs vs current implementation
• Nx App + Greenfield → Validate specs for rebuild (framework-agnostic)
• Nx App + Brownfield → Find gaps in current Nx/Angular implementation

---

Greenfield Route: Spec Completeness Analysis

Goal: Validate specs are complete enough to build NEW application

NOT analyzing: Old codebase (we're not fixing it, we're building new) YES analyzing: Spec quality, completeness, readiness

Step 1: Review Spec Completeness

For each specification:

# Check each spec
for spec in .specify/memory/specifications/*.md; do
  echo "Analyzing: $(basename $spec)"

  # Look for ambiguities
  grep "\[NEEDS CLARIFICATION\]" "$spec" || echo "No clarifications needed"

  # Check for acceptance criteria
  grep -A 10 "Acceptance Criteria" "$spec" || echo "⚠️ No acceptance criteria"

  # Check for user stories
  grep -A 5 "User Stories" "$spec" || echo "⚠️ No user stories"
done

Step 2: Identify Clarification Needs

Common ambiguities in Greenfield specs:

• UI/UX details missing (what should it look like?)
• Business rules unclear (what happens when...?)
• Data relationships ambiguous (how do entities relate?)
• Non-functional requirements vague (how fast? how secure?)

Mark with [NEEDS CLARIFICATION]:

### Photo Upload Feature
- Users can upload photos [NEEDS CLARIFICATION: drag-drop or click-browse?]
- Photos stored in cloud [NEEDS CLARIFICATION: S3, Cloudinary, or Vercel Blob?]
- Max 10 photos [NEEDS CLARIFICATION: per fish or per tank?]

Step 3: Ask About Target Tech Stack

For Greenfield, you're building NEW - need to choose stack!

I've extracted the business logic into tech-agnostic specifications.
Now we need to decide what to build the NEW application in.

What tech stack would you like to use for the new implementation?

Examples:
A) Next.js 15 + React 19 + Prisma + PostgreSQL + Vercel
B) Python FastAPI + SQLAlchemy + PostgreSQL + AWS ECS
C) Ruby on Rails 7 + PostgreSQL + Heroku
D) Your choice: [describe your preferred stack]

Document choice in Constitution for consistency.

Step 4: Create Implementation Roadmap

Greenfield roadmap focuses on BUILD ORDER:

# Greenfield Implementation Roadmap

## Tech Stack Selected
- Frontend: Next.js 15 + React 19
- Backend: Next.js API Routes
- Database: PostgreSQL + Prisma
- Auth: NextAuth.js
- Hosting: Vercel

## Build Phases

### Phase 1: Foundation (Week 1)
- Set up Next.js project
- Database schema with Prisma
- Authentication system
- Base UI components

### Phase 2: Core Features (Week 2-3)
- User management
- Fish tracking
- Tank management
- Water quality logging

### Phase 3: Advanced Features (Week 4)
- Photo upload
- Analytics dashboard
- Notifications
- Social features

## All Features are ❌ MISSING
(Greenfield = building from scratch)

Ready to proceed to:
- Step 5: Resolve clarifications
- Step 6: Implement features in new stack

---

Brownfield Route: Implementation Gap Analysis

Goal: Identify gaps in EXISTING codebase implementation

YES analyzing: Old codebase vs specs Using: /speckit.analyze to find gaps

Step 1: Run /speckit.analyze

GitHub Spec Kit's built-in validation:

> /speckit.analyze

What it checks:

• Specifications marked ✅ COMPLETE but implementation missing
• Implementation exists but not documented in specs
• Inconsistencies between related specifications
• Conflicting requirements across specs
• Outdated implementation status

---

Process Overview

Step 1: Run /speckit.analyze

GitHub Spec Kit's built-in validation:

> /speckit.analyze

What it checks:

• Specifications marked ✅ COMPLETE but implementation missing
• Implementation exists but not documented in specs
• Inconsistencies between related specifications
• Conflicting requirements across specs
• Outdated implementation status

Output example:

Analyzing specifications vs implementation...

Issues Found:

1. user-authentication.md marked PARTIAL
   - Spec says: Frontend login UI required
   - Reality: No login components found in codebase

2. analytics-dashboard.md marked MISSING
   - Spec exists but no implementation

3. Inconsistency detected:
   - fish-management.md requires photo-upload feature
   - photo-upload.md marked PARTIAL (upload API missing)

4. Orphaned implementation:
   - src/api/notifications.ts exists
   - No specification found for notifications feature

Summary:
- 3 COMPLETE features
- 4 PARTIAL features
- 5 MISSING features
- 2 inconsistencies
- 1 orphaned implementation

See operations/run-speckit-analyze.md

Step 2: Detailed Gap Analysis

Expand on /speckit.analyze findings with deeper analysis:

A. Review PARTIAL Features

For each ⚠️ PARTIAL feature:

• What exists? (backend, frontend, tests, docs)
• What's missing? (specific components, endpoints, UI)
• Why incomplete? (was it deprioritized? ran out of time?)
• Effort to complete? (hours estimate)
• Blockers? (dependencies, unclear requirements)

B. Review MISSING Features

For each ❌ MISSING feature:

• Is it actually needed? (or can it be deprioritized?)
• User impact if missing? (critical, important, nice-to-have)
• Implementation complexity? (simple, moderate, complex)
• Dependencies? (what must be done first)

C. Technical Debt Assessment

From docs/reverse-engineering/technical-debt-analysis.md:

• Code quality issues
• Missing tests (unit, integration, E2E)
• Documentation gaps
• Security vulnerabilities
• Performance bottlenecks

D. Identify Clarification Needs

Mark ambiguous areas with [NEEDS CLARIFICATION]:

• Unclear requirements
• Missing UX/UI details
• Undefined behavior
• Unspecified constraints

See operations/detailed-gap-analysis.md

Step 3: Prioritize Implementation

Classify gaps by priority:

P0 - Critical

• Blocking major use cases
• Security vulnerabilities
• Data integrity issues
• Broken core functionality

P1 - High Priority

• Important for core user value
• High user impact
• Competitive differentiation
• Technical debt causing problems

P2 - Medium Priority

• Nice-to-have features
• Improvements to existing features
• Minor technical debt
• Edge cases

P3 - Low Priority

• Future enhancements
• Polish and refinements
• Non-critical optimizations

See operations/prioritization.md

Step 4: Create Implementation Roadmap

Phase the work into manageable chunks:

Phase 1: P0 Items (~X hours)

• Complete critical features
• Fix security issues
• Unblock major workflows

Phase 2: P1 Features (~X hours)

• Build high-value features
• Address important technical debt
• Improve test coverage

Phase 3: P2/P3 Enhancements (~X hours or defer)

• Nice-to-have features
• Polish and refinements
• Optional improvements

---

Output Format

Create docs/gap-analysis-report.md (supplementing Spec Kit's output):

# Gap Analysis Report

**Date:** [Current Date]
**Based on:** /speckit.analyze + manual review

---

## Executive Summary

- **Overall Completion:** ~66%
- **Complete Features:** 3 (25%)
- **Partial Features:** 4 (33%)
- **Missing Features:** 5 (42%)
- **Critical Issues:** 2
- **Clarifications Needed:** 8

---

## Spec Kit Analysis Results

### Inconsistencies Detected by /speckit.analyze

1. **user-authentication.md** (PARTIAL)
   - Spec: Frontend login UI required
   - Reality: No login components exist
   - Impact: Users cannot authenticate

2. **photo-upload.md → fish-management.md**
   - fish-management depends on photo-upload
   - photo-upload.md is PARTIAL (API incomplete)
   - Impact: Fish photos cannot be uploaded

3. **Orphaned Code: notifications.ts**
   - Implementation exists without specification
   - Action: Create specification or remove code

---

## Gap Details

### Missing Features (❌ 5 features)

#### F003: Analytics Dashboard [P1]
**Specification:** `specs/analytics-dashboard.md`
**Status:** ❌ MISSING (not started)
**Impact:** Users cannot track metrics over time
**Effort:** ~8 hours
**Dependencies:** None

**Needs Clarification:**
- [NEEDS CLARIFICATION] What metrics to display?
- [NEEDS CLARIFICATION] Chart types (line, bar, pie)?
- [NEEDS CLARIFICATION] Real-time or daily aggregates?

#### F005: Social Features [P2]
...

### Partial Features (⚠️ 4 features)

#### F002: Fish Management [P0]
**Specification:** `specs/fish-management.md`
**Status:** ⚠️ PARTIAL

**Implemented:**
- ✅ Backend API (all CRUD endpoints)
- ✅ Fish list page
- ✅ Fish detail view

**Missing:**
- ❌ Fish profile edit page
- ❌ Photo upload UI (blocked by photo-upload.md)
- ❌ Bulk import feature

**Effort to Complete:** ~4 hours
**Blockers:** Photo upload API must be completed first

**Needs Clarification:**
- [NEEDS CLARIFICATION] Photo upload: drag-drop or click-browse?
- [NEEDS CLARIFICATION] Max photos per fish?

---

## Technical Debt

### High Priority (Blocking)
- Missing integration tests (0 tests, blocks deployment)
- No error handling in 8 API endpoints (causes crashes)
- Hardcoded AWS region (prevents multi-region)

### Medium Priority
- Frontend components lack TypeScript types
- No loading states in UI (poor UX)
- Missing rate limiting on API (security risk)

### Low Priority
- Inconsistent code formatting
- No dark mode support
- Missing accessibility labels

---

## Prioritized Roadmap

### Phase 1: P0 Critical (~12 hours)

**Goals:**
- Unblock core user workflows
- Fix security issues
- Complete essential features

**Tasks:**
1. Complete F002: Fish Management UI (~4h)
   - Implement photo upload API
   - Build fish edit page
   - Connect to backend

2. Add error handling to all APIs (~3h)

3. Implement integration tests (~5h)

### Phase 2: P1 High Value (~20 hours)

**Goals:**
- Build analytics dashboard
- Implement notifications
- Improve test coverage

**Tasks:**
1. F003: Analytics Dashboard (~8h)
2. F006: Notification System (~6h)
3. Add rate limiting (~2h)
4. Improve TypeScript coverage (~4h)

### Phase 3: P2/P3 Enhancements (~TBD)

**Goals:**
- Add nice-to-have features
- Polish and refinements

**Tasks:**
1. F005: Social Features (~12h)
2. F007: Dark Mode (~6h)
3. F008: Admin Panel (~10h)

---

## Clarifications Needed (8 total)

### Critical (P0) - 2 items
1. **F002 - Photo Upload:** Drag-drop, click-browse, or both?
2. **F004 - Offline Sync:** Full data or metadata only?

### Important (P1) - 4 items
3. **F003 - Analytics:** Which chart types and metrics?
4. **F006 - Notifications:** Email, push, or both?
5. **F003 - Data Refresh:** Real-time or daily aggregates?
6. **F006 - Alert Frequency:** Per event or digest?

### Nice-to-Have (P2) - 2 items
7. **F007 - Dark Mode:** Full theme or toggle only?
8. **F005 - Social:** Which social features (share, comment, like)?

---

## Recommendations

1. **Resolve P0 clarifications first** (Step 5: complete-spec)
2. **Focus on Phase 1** before expanding scope
3. **Use /speckit.implement** for systematic implementation
4. **Update specs as you go** to keep them accurate
5. **Run /speckit.analyze regularly** to catch drift

---

## Next Steps

1. Run complete-spec skill to resolve clarifications
2. Begin Phase 1 implementation
3. Use `/speckit.implement` for each feature
4. Update implementation status in specs
5. Re-run `/speckit.analyze` to validate progress

---

GitHub Spec Kit Integration

After gap analysis, leverage Spec Kit commands:

Validate Continuously

# Re-run after making changes
> /speckit.analyze

# Should show fewer issues as you implement

Implement Systematically

# Generate tasks for a feature
> /speckit.tasks user-authentication

# Implement step-by-step
> /speckit.implement user-authentication

# Updates spec status automatically

Clarify Ambiguities

# Before implementing unclear features
> /speckit.clarify analytics-dashboard

# Interactive Q&A to fill gaps

---

Success Criteria

After running this skill, you should have:

• ✅ /speckit.analyze results reviewed
• ✅ All inconsistencies documented
• ✅ PARTIAL features analyzed (what exists vs missing)
• ✅ MISSING features categorized
• ✅ Technical debt cataloged
• ✅ [NEEDS CLARIFICATION] markers added
• ✅ Priorities assigned (P0/P1/P2/P3)
• ✅ Phased implementation roadmap
• ✅ docs/gap-analysis-report.md created
• ✅ Ready to proceed to Step 5 (Complete Specification)

---

Next Step

Once gap analysis is complete, proceed to:

Step 5: Complete Specification - Use the complete-spec skill to resolve all [NEEDS CLARIFICATION] markers interactively.

---

Technical Notes

• /speckit.analyze is run first for automated checks
• Manual analysis supplements with deeper insights
• Gap report complements Spec Kit's output
• Keep both .specify/memory/ specs and gap report updated
• Re-run /speckit.analyze frequently to track progress

---

Route Comparison: What Gap Analysis Means

Aspect	Greenfield	Brownfield
Analyzing	Spec completeness	Existing code vs specs
Goal	Validate specs ready to build NEW	Find gaps in CURRENT implementation
/speckit.analyze	Skip (no old code to compare)	Run (compare specs to code)
Gap Definition	Missing requirements, ambiguities	Missing features, partial implementations
Roadmap	Build order for NEW app	Fill gaps in EXISTING app
Tech Stack	ASK user (choosing for new)	Already decided (current stack)
All Features	❌ MISSING (building from scratch)	Mix of ✅⚠️❌ (some exist)

Key Insight:

• Greenfield: Specs describe WHAT to build (old code doesn't matter) - Same for ALL detection types
• Brownfield: Specs describe current reality (validate against old code) - Same for ALL detection types

Detection type doesn't change gap analysis approach - it only affects what patterns were analyzed in Gear 2

---

Remember: Check route first! Greenfield analyzes SPECS, Brownfield analyzes IMPLEMENTATION.