Initial commit

2025-11-30 08:29:31 +08:00
commit f8e59e249c
39 changed files with 12575 additions and 0 deletions
--- a/skills/gap-analysis/SKILL.md
+++ b/skills/gap-analysis/SKILL.md
@@ -0,0 +1,596 @@
+---
+name: gap-analysis
+description: 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:
+
+```bash
+# 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:
+
+```bash
+# 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]:**
+```markdown
+### 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:**
+
+```markdown
+# 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:
+
+```bash
+> /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:
+
+```bash
+> /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](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](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](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):
+
+```markdown
+# 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
+```bash
+# Re-run after making changes
+> /speckit.analyze
+
+# Should show fewer issues as you implement
+```
+
+### Implement Systematically
+```bash
+# Generate tasks for a feature
+> /speckit.tasks user-authentication
+
+# Implement step-by-step
+> /speckit.implement user-authentication
+
+# Updates spec status automatically
+```
+
+### Clarify Ambiguities
+```bash
+# 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.