gap-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

这是从逆向工程到规格驱动开发流程6个步骤中的第4步。

预计耗时： 15分钟 前置条件： 已完成第3步（存在包含规格说明的

.specify/

目录） 输出结果： 针对特定路由的分析报告与实施路线图

Configuration Check (FIRST STEP!)

配置检查（第一步！）

CRITICAL: Check detection type and route:

bash

undefined

关键提醒： 检查检测类型和路由：

bash

undefined

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

---

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)"


**路由类型：**
- **greenfield** → 构建全新应用（与技术无关的规格说明）
- **brownfield** → 维护现有应用（指定技术栈的规格说明）

**检测类型：**
- **generic** → 标准应用
- **monorepo-service** → 单体仓库中的服务
- **nx-app** → Nx工作区应用
- **turborepo-package** → Turborepo包
- **lerna-package** → Lerna包

**根据路由类型，该工具的行为会有所不同！**

**示例：**
- 单体仓库服务 + 全新系统 → 分析规格说明的完整性以用于平台迁移
- 单体仓库服务 + 遗留系统 → 对比规格说明与当前实现
- Nx应用 + 全新系统 → 验证用于重构的规格说明（与框架无关）
- Nx应用 + 遗留系统 → 找出当前Nx/Angular实现中的差距

---

Greenfield Route: Spec Completeness Analysis

全新系统（Greenfield）路由：规格说明完整性分析

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

步骤1：检查规格说明完整性

For each specification:

bash

undefined

针对每个规格说明：

bash

undefined

Check each spec

for spec in .specify/specs/*/spec.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

undefined

for spec in .specify/specs/*/spec.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

undefined

Step 2: Identify Clarification Needs

步骤2：识别需要澄清的内容

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

undefined

全新系统规格说明中常见的模糊点：

UI/UX细节缺失（界面应该是什么样的？）
业务规则不明确（当发生某情况时应该如何处理？）
数据关系模糊（实体之间的关联方式是什么？）
非功能性需求不清晰（性能要求？安全标准？）

使用
[NEEDS CLARIFICATION]
标记：

markdown

undefined

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?]

undefined

用户可以上传照片 [NEEDS CLARIFICATION: 支持拖拽还是点击浏览？]
照片存储在云端 [NEEDS CLARIFICATION: 使用S3、Cloudinary还是Vercel Blob？]
最多可上传10张照片 [NEEDS CLARIFICATION: 每条鱼还是每个鱼缸的上限？]

undefined

Step 3: Ask About Target Tech Stack

步骤3：询问目标技术栈

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.

对于全新系统，你需要从零开始构建 - 必须选择技术栈！

我已将业务逻辑提取为与技术无关的规格说明。
现在我们需要决定新应用使用什么技术栈。

你希望新实现使用什么技术栈？

示例：
A) Next.js 15 + React 19 + Prisma + PostgreSQL + Vercel
B) Python FastAPI + SQLAlchemy + PostgreSQL + AWS ECS
C) Ruby on Rails 7 + PostgreSQL + Heroku
D) 自定义选择：[描述你偏好的技术栈]

将选择记录到规范文档中以保持一致性。

Step 4: Create Implementation Roadmap

步骤4：创建实施路线图

Greenfield roadmap focuses on BUILD ORDER:

markdown

undefined

全新系统路线图聚焦于构建顺序：

markdown

undefined

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

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

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

User management
Fish tracking
Tank management
Water quality logging

Phase 3: Advanced Features (Week 4)

Photo upload
Analytics dashboard
Notifications
Social features

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

---

(Greenfield = building from scratch)

Ready to proceed to:

Step 5: Resolve clarifications
Step 6: Implement features in new stack

---

Brownfield Route: Implementation Gap Analysis

遗留系统（Brownfield）路由：实现差距分析

Goal: Identify gaps in EXISTING codebase implementation

YES analyzing: Old codebase vs specs Using: AST-powered analysis as primary method, /speckit.analyze as fallback

IMPORTANT: You MUST run the AST analysis tool - don't just read the instructions!

目标： 识别现有代码库实现中的差距

需要分析内容： 旧代码库与规格说明的对比 使用工具： 以AST驱动分析为主要方法，/speckit.analyze为备选方案

重要提示：你必须运行AST分析工具 - 不要只阅读说明！

Step 1: Verify Prerequisites

步骤1：验证前置条件

CRITICAL: Check if prerequisite scripts are installed (needed for fallback):

bash

undefined

关键提醒： 检查是否已安装必备脚本（备选方案需要）：

bash

undefined

Check for scripts (used by /speckit.analyze fallback)

if [ ! -f .specify/scripts/bash/check-prerequisites.sh ]; then echo "GitHub Spec Kit scripts not found - /speckit.analyze fallback unavailable" echo "AST analysis will be the sole analysis method" fi

undefined

if [ ! -f .specify/scripts/bash/check-prerequisites.sh ]; then echo "GitHub Spec Kit scripts not found - /speckit.analyze fallback unavailable" echo "AST analysis will be the sole analysis method" fi

undefined

Step 2a: Run AST-Powered Analysis (PRIMARY METHOD)

步骤2a：运行AST驱动分析（主要方法）

ACTION REQUIRED: Run the AST analysis for deep code inspection:

bash

undefined

必须执行： 运行AST分析以进行深度代码检查：

bash

undefined

Run AST-powered roadmap generation (includes gap analysis)

node ~/stackshift/scripts/run-ast-analysis.mjs roadmap . --format=markdown


**What AST analysis provides** (primary capabilities):
- Function signature verification (not just "exists")
- Stub detection (functions returning placeholder text)
- Missing parameters detection
- Business logic pattern analysis
- Test coverage gaps
- Confidence scoring (0-100%)
- Detailed roadmap with phases, priorities, and effort estimates

**This IS the primary gap analysis method.** It provides deeper, more accurate analysis than spec-level comparison alone.

node ~/stackshift/scripts/run-ast-analysis.mjs roadmap . --format=markdown


**AST分析提供的能力**（核心功能）：
- 函数签名验证（不仅仅是“存在与否”）
- 存根检测（返回占位符文本的函数）
- 缺失参数检测
- 业务逻辑模式分析
- 测试覆盖差距
- 置信度评分（0-100%）
- 包含阶段、优先级和工作量估算的详细路线图

**这是主要的差距分析方法。** 它比单纯的规格对比提供更深入、更准确的分析。

Step 2b: Run /speckit.analyze (FALLBACK)

步骤2b：运行/speckit.analyze（备选方案）

Only if AST analysis fails or is unavailable, fall back to GitHub Spec Kit's 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

If this command also fails with "Script not found", the scripts weren't installed. Use Step 2c instead.

仅当AST分析失败或不可用时，才使用GitHub Spec Kit的验证作为备选：

bash

> /speckit.analyze

检查内容：

标记为“已完成”但未实现的规格说明
已实现但未在规格说明中记录的功能
相关规格说明之间的不一致性
跨规格说明的冲突需求
过时的实现状态

如果该命令也提示“Script not found”，说明脚本未安装，请使用步骤2c。

Step 2c: Manual Gap Analysis (last resort if both methods unavailable)

步骤2c：手动差距分析（最后手段，当两种方法都不可用时）

If both AST analysis and

/speckit.analyze

are unavailable, do manual analysis:

bash

undefined

如果AST分析和

/speckit.analyze

都不可用，请进行手动分析：

bash

undefined

For each spec, check implementation status

for spec in .specify/specs/*/spec.md; do feature=$(dirname "$spec" | xargs basename) echo "Analyzing: $feature"

Extract status from spec

status=$(grep "^## Status" "$spec" -A 1 | tail -1) echo " Status: $status"

Look for [NEEDS CLARIFICATION] markers

clarifications=$(grep -c "[NEEDS CLARIFICATION]" "$spec" 2>/dev/null || echo "0") echo " Clarifications needed: $clarifications"

echo "" done


This is the least thorough option and should only be used as a last resort.

---

for spec in .specify/specs/*/spec.md; do feature=$(dirname "$spec" | xargs basename) echo "Analyzing: $feature"

Extract status from spec

status=$(grep "^## Status" "$spec" -A 1 | tail -1) echo " Status: $status"

Look for [NEEDS CLARIFICATION] markers

clarifications=$(grep -c "[NEEDS CLARIFICATION]" "$spec" 2>/dev/null || echo "0") echo " Clarifications needed: $clarifications"

echo "" done


这是最不全面的选项，仅应作为最后手段使用。

---

Process Overview

流程概述

Step 1: Verify Prerequisites

步骤1：验证前置条件

Check that AST analysis scripts and GitHub Spec Kit scripts are available (see above).

检查AST分析脚本和GitHub Spec Kit脚本是否可用（见上文）。

Step 2: Run Analysis

步骤2：运行分析

Run AST analysis first (primary method). If it fails, fall back to

/speckit.analyze

. If that also fails, use manual analysis.

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

首先运行AST分析（主要方法）。如果失败，使用

/speckit.analyze

作为备选。如果也失败，使用手动分析。

输出示例：

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

Step 2: Detailed Gap Analysis

步骤2：详细差距分析

Expand on AST analysis findings with deeper analysis:

基于AST分析结果进行更深入的分析：

A. Review PARTIAL Features

A. 检查部分完成的功能

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)

针对每个⚠️ 部分完成的功能：

已实现的内容？（后端、前端、测试、文档）
缺失的内容？（特定组件、接口、UI）
未完成的原因？（优先级降低？时间不足？）
完成所需工作量？（小时估算）
阻塞因素？（依赖项、不明确的需求）

B. Review MISSING Features

B. 检查缺失的功能

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

C. 技术债务评估

From

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

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

从

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

中获取：

代码质量问题
缺失的测试（单元测试、集成测试、端到端测试）
文档差距
安全漏洞
性能瓶颈

D. Identify Clarification Needs

D. 识别需要澄清的内容

Mark ambiguous areas with

[NEEDS CLARIFICATION]

Unclear requirements
Missing UX/UI details
Undefined behavior
Unspecified constraints

使用

[NEEDS CLARIFICATION]

标记模糊区域：

不明确的需求
缺失的UX/UI细节
未定义的行为
未指定的约束

Step 3: Prioritize Implementation

步骤3：确定实施优先级

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

按优先级对差距进行分类：

P0 - 关键

阻塞主要用例
安全漏洞
数据完整性问题
核心功能故障

P1 - 高优先级

对核心用户价值至关重要
用户影响大
差异化竞争优势
引发问题的技术债务

P2 - 中等优先级

锦上添花的功能
现有功能的改进
次要技术债务
边缘场景

P3 - 低优先级

未来增强功能
优化和完善
非关键性能优化

Step 4: Create Implementation Roadmap

步骤4：创建实施路线图

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

将工作划分为可管理的阶段：

阶段1：P0项（约X小时）

完成关键功能
修复安全问题
解除主要工作流阻塞

阶段2：P1功能（约X小时）

构建高价值功能
处理重要技术债务
提高测试覆盖率

阶段3：P2/P3增强功能（约X小时或延后）

锦上添花的功能
优化和完善
可选改进

Output Format

输出格式

Create

docs/gap-analysis-report.md

(supplementing Spec Kit's output):

markdown

undefined

创建

docs/gap-analysis-report.md

（补充Spec Kit的输出）：

markdown

undefined

Gap Analysis Report

Date: [Current Date] Based on: AST analysis (primary) + /speckit.analyze (fallback) + 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

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

user-authentication.md (PARTIAL)
- Spec: Frontend login UI required
- Reality: No login components exist
- Impact: Users cannot authenticate
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
Orphaned Code: notifications.ts
- Implementation exists without specification
- Action: Create specification or remove code

user-authentication.md (PARTIAL)
- Spec: Frontend login UI required
- Reality: No login components exist
- Impact: Users cannot authenticate
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
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?

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?

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)

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)

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

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:

Complete F002: Fish Management UI (~4h)
- Implement photo upload API
- Build fish edit page
- Connect to backend
Add error handling to all APIs (~3h)
Implement integration tests (~5h)

Goals:

Unblock core user workflows
Fix security issues
Complete essential features

Tasks:

Complete F002: Fish Management UI (~4h)
- Implement photo upload API
- Build fish edit page
- Connect to backend
Add error handling to all APIs (~3h)
Implement integration tests (~5h)

Phase 2: P1 High Value (~20 hours)

Goals:

Build analytics dashboard
Implement notifications
Improve test coverage

Tasks:

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

Goals:

Build analytics dashboard
Implement notifications
Improve test coverage

Tasks:

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

Phase 3: P2/P3 Enhancements (~TBD)

Goals:

Add nice-to-have features
Polish and refinements

Tasks:

F005: Social Features (~12h)
F007: Dark Mode (~6h)
F008: Admin Panel (~10h)

Goals:

Add nice-to-have features
Polish and refinements

Tasks:

F005: Social Features (~12h)
F007: Dark Mode (~6h)
F008: Admin Panel (~10h)

Clarifications Needed (8 total)

Critical (P0) - 2 items

F002 - Photo Upload: Drag-drop, click-browse, or both?
F004 - Offline Sync: Full data or metadata only?

F002 - Photo Upload: Drag-drop, click-browse, or both?
F004 - Offline Sync: Full data or metadata only?

Important (P1) - 4 items

F003 - Analytics: Which chart types and metrics?
F006 - Notifications: Email, push, or both?
F003 - Data Refresh: Real-time or daily aggregates?
F006 - Alert Frequency: Per event or digest?

F003 - Analytics: Which chart types and metrics?
F006 - Notifications: Email, push, or both?
F003 - Data Refresh: Real-time or daily aggregates?
F006 - Alert Frequency: Per event or digest?

Nice-to-Have (P2) - 2 items

F007 - Dark Mode: Full theme or toggle only?
F005 - Social: Which social features (share, comment, like)?

F007 - Dark Mode: Full theme or toggle only?
F005 - Social: Which social features (share, comment, like)?

Recommendations

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

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

Next Steps

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

---

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

---

GitHub Spec Kit Integration

GitHub Spec Kit集成

After gap analysis, leverage Spec Kit commands:

差距分析完成后，利用Spec Kit命令：

Validate Continuously

持续验证

bash

undefined

bash

undefined

Re-run after making changes

/speckit.analyze

Should show fewer issues as you implement

undefined

undefined

Implement Systematically

系统化实施

bash

undefined

bash

undefined

Generate tasks for a feature

/speckit.tasks user-authentication

Implement step-by-step

/speckit.implement user-authentication

Updates spec status automatically

undefined

undefined

Clarify Ambiguities

澄清模糊点

bash

undefined

bash

undefined

Before implementing unclear features

/speckit.clarify analytics-dashboard

Interactive Q&A to fill gaps

---

---

Success Criteria

成功标准

After running this skill, you should have:

✅ AST analysis results reviewed (primary method)
✅
```
/speckit.analyze
```
results reviewed (if used as fallback)
✅ 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)

运行此工具后，你应获得：

✅ 已查看AST分析结果（主要方法）
✅ 已查看
```
/speckit.analyze
```
结果（如果用作备选）
✅ 所有不一致性已记录
✅ 已分析部分完成的功能（已实现内容vs缺失内容）
✅ 已对缺失功能进行分类
✅ 已编目技术债务
✅ 已添加
```
[NEEDS CLARIFICATION]
```
标记
✅ 已分配优先级（P0/P1/P2/P3）
✅ 已制定分阶段实施路线图
✅ 已创建
```
docs/gap-analysis-report.md
```
✅ 准备进入第5步（完善规格说明）

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.

差距分析完成后，进入：

第5步：完善规格说明 - 使用complete-spec工具以交互方式解决所有

[NEEDS CLARIFICATION]

标记。

Technical Notes

技术说明

AST analysis is the primary method for gap analysis and code inspection
```
/speckit.analyze
```
is a fallback when AST analysis is unavailable
Manual analysis supplements with deeper insights when both are unavailable
Gap report complements AST analysis output
Keep both
```
.specify/memory/
```
specs and gap report updated
Re-run AST analysis frequently to track progress

AST分析是差距分析和代码检查的主要方法
```
/speckit.analyze
```
是AST分析不可用时的备选方案
手动分析在两种方法都不可用时提供补充见解
差距报告是AST分析输出的补充
保持
```
.specify/memory/
```
中的规格说明和差距报告更新
定期重新运行AST分析以跟踪进度

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
AST Analysis	Skip (no old code to compare)	Run (primary gap analysis method)
/speckit.analyze	Skip (no old code to compare)	Fallback (if AST unavailable)
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.

维度	全新系统（Greenfield）	遗留系统（Brownfield）
分析对象	规格说明完整性	现有代码与规格说明对比
目标	验证规格说明是否可用于构建新应用	找出当前实现中的差距
AST分析	跳过（无旧代码可对比）	运行（主要差距分析方法）
/speckit.analyze	跳过（无旧代码可对比）	备选（当AST不可用时）
差距定义	缺失的需求、模糊点	缺失的功能、部分实现
路线图	新应用的构建顺序	填补现有应用的差距
技术栈	询问用户（为新应用选择）	已确定（当前技术栈）
所有功能状态	❌ 全部缺失（从零开始构建）	✅⚠️❌ 混合（部分已存在）

核心要点：

全新系统：规格说明描述需要构建的内容（旧代码无关紧要） - 所有检测类型均适用
遗留系统：规格说明描述当前状态（与旧代码对比验证） - 所有检测类型均适用

检测类型不会改变差距分析的方法 - 它仅影响在第2步中分析的模式

请记住： 首先检查路由！全新系统分析规格说明，遗留系统分析实现。