Back to Details

spec-coverage-map

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec-to-Code Coverage Map

规格-代码覆盖映射图

Generate a comprehensive coverage map showing the relationship between specifications and implementation files.
When to run: After Gear 6 (Implementation) or during cleanup/documentation phases
Output: 
docs/spec-coverage-map.md
生成全面的覆盖映射图，展示规格文档与实现文件之间的关系。
运行时机： 在第6阶段（功能实现）完成后，或在代码清理/文档完善阶段
输出文件： 
docs/spec-coverage-map.md

What This Does

功能说明

Creates a visual map showing:
  1. Spec → Files: Which code files each spec covers
  2. Files → Specs: Which spec(s) cover each code file (reverse index)
  3. Coverage Statistics: Percentages by category (backend, frontend, infrastructure)
  4. Gap Analysis: Code files not covered by any spec
  5. Shared Files: Files referenced by multiple specs
创建可视化映射图，包含以下内容：
  1. 规格→文件：每个规格文档覆盖的代码文件
  2. 文件→规格：每个代码文件被哪些规格文档覆盖（反向索引）
  3. 覆盖统计数据：按分类（后端、前端、基础设施）统计的覆盖率百分比
  4. 缺口分析：未被任何规格文档覆盖的代码文件
  5. 共享文件：被多个规格文档引用的文件

Process

操作流程

Step 1: Discover All Specifications

步骤1：发现所有规格文档

bash
undefined
bash
undefined

Find all spec files

Find all spec files

find .specify/memory/specifications -name "*.md" -type f 2>/dev/null ||
find specs -name "spec.md" -type f 2>/dev/null
find .specify/memory/specifications -name "*.md" -type f 2>/dev/null ||
find specs -name "spec.md" -type f 2>/dev/null

Count them

Count them

SPEC_COUNT=$(find .specify/memory/specifications -name "*.md" -type f 2>/dev/null | wc -l) echo "Found $SPEC_COUNT specifications"
undefined
SPEC_COUNT=$(find .specify/memory/specifications -name "*.md" -type f 2>/dev/null | wc -l) echo "Found $SPEC_COUNT specifications"
undefined

Step 2: Extract File References from Each Spec

步骤2：从每个规格文档中提取文件引用

For each spec, look for file references in these sections:
  • "Files" or "File Structure"
  • "Implementation Status"
  • "Components Implemented"
  • "Technical Details"
  • Code blocks with file paths
Pattern matching:
bash
undefined
针对每个规格文档，在以下部分查找文件引用：
  • "Files"（文件）或 "File Structure"（文件结构）
  • "Implementation Status"（实现状态）
  • "Components Implemented"（已实现组件）
  • "Technical Details"（技术细节）
  • 包含文件路径的代码块
模式匹配示例：
bash
undefined

Common file reference patterns in specs

Common file reference patterns in specs

  • src/handlers/foo.js
  • api/handlers/vehicle-details.ts
  • site/pages/Home.tsx
  • infrastructure/terraform/main.tf
  • .github/workflows/deploy.yml

Read each spec and extract:
- File paths mentioned
- Component names that map to files
- Directory references
  • src/handlers/foo.js
  • api/handlers/vehicle-details.ts
  • site/pages/Home.tsx
  • infrastructure/terraform/main.tf
  • .github/workflows/deploy.yml

读取每个规格文档并提取：
- 提及的文件路径
- 映射到文件的组件名称
- 目录引用

Step 3: Categorize Files

步骤3：文件分类

Group files by type:
  • Backend: api/, src/handlers/, src/services/, lib/
  • Frontend: site/, pages/, components/, app/
  • Infrastructure: infrastructure/, terraform/, .github/workflows/
  • Database: prisma/, migrations/, schema/
  • Scripts: scripts/, bin/
  • Config: package.json, tsconfig.json, etc.
  • Tests: *.test.ts, *.spec.ts, tests/
按类型对文件进行分组：
  • 后端：api/, src/handlers/, src/services/, lib/
  • 前端：site/, pages/, components/, app/
  • 基础设施：infrastructure/, terraform/, .github/workflows/
  • 数据库：prisma/, migrations/, schema/
  • 脚本：scripts/, bin/
  • 配置：package.json, tsconfig.json 等
  • 测试：*.test.ts, *.spec.ts, tests/

Step 4: Generate ASCII Box Diagrams

步骤4：生成ASCII框图

For each spec, create a box diagram:
┌─────────────────────────────────┐
│  001-feature-name               │ Status: ✅ COMPLETE
├─────────────────────────────────┤
│ Backend:                        │
│  ├─ api/src/handlers/foo.js     │
│  └─ api/src/services/bar.js     │
│ Frontend:                       │
│  └─ site/src/pages/Foo.tsx      │
│ Infrastructure:                 │
│  └─ .github/workflows/deploy.yml│
└─────────────────────────────────┘
Box Drawing Characters:
┌ ─ ┐  (top)
│     (sides)
├ ─ ┤  (divider)
└ ─ ┘  (bottom)
├ └   (tree branches)
为每个规格文档创建框图：
┌─────────────────────────────────┐
│  001-feature-name               │ Status: ✅ COMPLETE
├─────────────────────────────────┤
│ Backend:                        │
│  ├─ api/src/handlers/foo.js     │
│  └─ api/src/services/bar.js     │
│ Frontend:                       │
│  └─ site/src/pages/Foo.tsx      │
│ Infrastructure:                 │
│  └─ .github/workflows/deploy.yml│
└─────────────────────────────────┘
框图绘制字符：
┌ ─ ┐  (top)
│     (sides)
├ ─ ┤  (divider)
└ ─ ┘  (bottom)
├ └   (tree branches)

Step 5: Create Reverse Index

步骤5：创建反向索引

Build a table showing which spec(s) cover each file:
markdown
undefined
构建表格，展示每个文件被哪些规格文档覆盖：
markdown
undefined

Files → Specs Reverse Index

Files → Specs Reverse Index

FileCovered ByCount
api/handlers/vehicle.ts001-vehicle-details, 003-pricing2
site/pages/Home.tsx001-homepage1
lib/utils/format.ts001-vehicle, 002-search, 004-pricing3

**Highlight:**
- 🟢 **Single spec** (1 spec) - Normal coverage
- 🟡 **Shared** (2-3 specs) - Multiple features use this
- 🔴 **Hot** (4+ specs) - Critical shared utility
FileCovered ByCount
api/handlers/vehicle.ts001-vehicle-details, 003-pricing2
site/pages/Home.tsx001-homepage1
lib/utils/format.ts001-vehicle, 002-search, 004-pricing3

**高亮标记：**
- 🟢 **单一规格**（1个规格）- 正常覆盖
- 🟡 **共享文件**（2-3个规格）- 被多个功能使用
- 🔴 **高频共享**（4+个规格）- 关键共享工具

Step 6: Calculate Coverage Statistics

步骤6：计算覆盖统计数据

markdown
undefined
markdown
undefined

Coverage Statistics

Coverage Statistics

CategoryTotal FilesCoveredCoverage %
Backend454293%
Frontend383592%
Infrastructure121083%
Database88100%
Scripts6467%
TOTAL1099991%

**Coverage Heat Map:**
Backend [████████████████░░] 93% Frontend [████████████████░░] 92% Infrastructure [███████████████░░░] 83% Database [████████████████████] 100% Scripts [█████████░░░░░░░░░] 67%
undefined
CategoryTotal FilesCoveredCoverage %
Backend454293%
Frontend383592%
Infrastructure121083%
Database88100%
Scripts6467%
TOTAL1099991%

**覆盖热力图：**
Backend [████████████████░░] 93% Frontend [████████████████░░] 92% Infrastructure [███████████████░░░] 83% Database [████████████████████] 100% Scripts [█████████░░░░░░░░░] 67%
undefined

Step 7: Identify Gaps

步骤7：识别覆盖缺口

markdown
undefined
markdown
undefined

🚨 Coverage Gaps (10 files)

🚨 Coverage Gaps (10 files)

Files not covered by any specification:
Backend:
  • api/handlers/legacy-foo.js (deprecated?)
  • api/utils/debug.ts (utility?)
Frontend:
  • site/components/DevTools.tsx (dev-only?)
Scripts:
  • scripts/experimental/test.sh (WIP?)
  • scripts/deprecated/old-deploy.sh (remove?)
Recommendations:
  • Remove deprecated files
  • Create specs for utilities if they contain business logic
  • Document dev-only tools in a utilities spec
undefined
Files not covered by any specification:
Backend:
  • api/handlers/legacy-foo.js (deprecated?)
  • api/utils/debug.ts (utility?)
Frontend:
  • site/components/DevTools.tsx (dev-only?)
Scripts:
  • scripts/experimental/test.sh (WIP?)
  • scripts/deprecated/old-deploy.sh (remove?)
Recommendations:
  • Remove deprecated files
  • Create specs for utilities if they contain business logic
  • Document dev-only tools in a utilities spec
undefined

Step 8: Highlight Shared Files

步骤8：高亮共享文件

markdown
undefined
markdown
undefined

🔥 Shared Files (Referenced by 3+ Specs)

🔥 Shared Files (Referenced by 3+ Specs)

FileSpecsCountRisk
lib/utils/pricing.ts001, 003, 004, 007, 0095🔴 HIGH
lib/api/client.ts002, 005, 006, 0084🔴 HIGH
lib/types/vehicle.ts001, 002, 0113🟡 MEDIUM
High-risk files (4+ specs):
  • Changes affect multiple features
  • Require extra testing
  • Should have comprehensive test coverage
  • Consider refactoring if too coupled

---
FileSpecsCountRisk
lib/utils/pricing.ts001, 003, 004, 007, 0095🔴 HIGH
lib/api/client.ts002, 005, 006, 0084🔴 HIGH
lib/types/vehicle.ts001, 002, 0113🟡 MEDIUM
High-risk files (4+ specs):
  • Changes affect multiple features
  • Require extra testing
  • Should have comprehensive test coverage
  • Consider refactoring if too coupled

---

Complete Output Template

完整输出模板

markdown
undefined
markdown
undefined

Spec-to-Code Coverage Map

Spec-to-Code Coverage Map

Generated: [TIMESTAMP] Total Specs: [COUNT] Total Files Covered: [COUNT] Overall Coverage: [PERCENTAGE]%
Generated: [TIMESTAMP] Total Specs: [COUNT] Total Files Covered: [COUNT] Overall Coverage: [PERCENTAGE]%

Coverage by Spec

Coverage by Spec

[For each spec, ASCII box diagram with files]
[For each spec, ASCII box diagram with files]

Files → Specs Reverse Index

Files → Specs Reverse Index

[Table of all files and which specs cover them]
[Table of all files and which specs cover them]

Coverage Statistics

Coverage Statistics

[Stats table and heat map]
[Stats table and heat map]

Coverage Gaps

Coverage Gaps

[List of files not covered by any spec]
[List of files not covered by any spec]

Shared Files

Shared Files

[Files referenced by multiple specs with risk assessment]
[Files referenced by multiple specs with risk assessment]

Recommendations

Recommendations

  • [Action items based on analysis]
  • [Gaps to address]
  • [Refactoring opportunities]

---
  • [Action items based on analysis]
  • [Gaps to address]
  • [Refactoring opportunities]

---

When to Generate

生成时机

Automatic Triggers

自动触发时机

  1. End of Gear 6 (Implement) - After all features implemented
  2. Cleanup Phase - When finalizing documentation
  3. Manual Request - User asks for coverage analysis
  1. 第6阶段（功能实现）结束后 - 所有功能实现完成后
  2. 代码清理阶段 - 最终完善文档时
  3. 手动请求 - 用户要求进行覆盖分析时

Manual Invocation

手动调用方式

bash
undefined
bash
undefined

Check current coverage

Check current coverage

cat .stackshift-state.json | grep currentGear
cat .stackshift-state.json | grep currentGear

If Gear 6 complete or in cleanup:

If Gear 6 complete or in cleanup:

"Generate spec-to-code coverage map"

---
"Generate spec-to-code coverage map"

---

Integration Points

集成点

In Gear 6 (Implement) Skill

在第6阶段（功能实现）技能中

After completing all implementations, add:
markdown
undefined
完成所有功能实现后，添加以下内容：
markdown
undefined

Final Step: Generate Coverage Map

Final Step: Generate Coverage Map

Creating spec-to-code coverage map...
[Run coverage map generation]
✅ Coverage map saved to docs/spec-coverage-map.md
Summary:
  • 109 files covered by 12 specs
  • 91% overall coverage
  • 10 gap files identified
  • 3 high-risk shared files
undefined
Creating spec-to-code coverage map...
[Run coverage map generation]
✅ Coverage map saved to docs/spec-coverage-map.md
Summary:
  • 109 files covered by 12 specs
  • 91% overall coverage
  • 10 gap files identified
  • 3 high-risk shared files
undefined

In Cleanup/Finalization

在代码清理/最终完善阶段

When user says "cleanup" or "finalize documentation":
markdown
Running final cleanup tasks:

1. ✅ Generate spec-coverage-map.md
2. ✅ Update README with coverage stats
3. ✅ Commit all documentation
4. ✅ Create summary report
当用户说“cleanup”或“finalize documentation”时：
markdown
Running final cleanup tasks:

1. ✅ Generate spec-coverage-map.md
2. ✅ Update README with coverage stats
3. ✅ Commit all documentation
4. ✅ Create summary report

Success Criteria

成功标准

After generating coverage map, you should have:
  • ✅ 
    docs/spec-coverage-map.md
    file created
  • ✅ Visual ASCII diagrams for each spec
  • ✅ Reverse index table (files → specs)
  • ✅ Coverage statistics and heat map
  • ✅ Gap analysis with recommendations
  • ✅ Shared files risk assessment
  • ✅ Actionable next steps
生成覆盖映射图后，应满足以下条件：
  • ✅ 创建了 
    docs/spec-coverage-map.md
    文件
  • ✅ 每个规格文档都有对应的ASCII框图
  • ✅ 包含反向索引表（文件→规格）
  • ✅ 包含覆盖统计数据和热力图
  • ✅ 包含覆盖缺口分析及建议
  • ✅ 包含共享文件风险评估
  • ✅ 有可执行的后续步骤

Example Output

示例输出

markdown
undefined
markdown
undefined

Spec-to-Code Coverage Map

Spec-to-Code Coverage Map

Generated: 2025-11-19T17:45:00Z Total Specs: 12 Total Files Covered: 99 Overall Coverage: 91%
Generated: 2025-11-19T17:45:00Z Total Specs: 12 Total Files Covered: 99 Overall Coverage: 91%

Coverage by Spec

Coverage by Spec

┌─────────────────────────────────────────────┐ │ 001-vehicle-details-display │ Status: ✅ COMPLETE ├─────────────────────────────────────────────┤ │ Backend (3 files): │ │ ├─ api/handlers/vehicle-details.ts │ │ ├─ api/services/vehicle-data.ts │ │ └─ lib/validators/vin.ts │ │ Frontend (2 files): │ │ ├─ site/pages/VehicleDetails.tsx │ │ └─ site/components/VehicleCard.tsx │ │ Tests (2 files): │ │ ├─ api/handlers/vehicle-details.test.ts │ │ └─ site/pages/VehicleDetails.test.tsx │ └─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐ │ 002-inventory-search │ Status: ✅ COMPLETE ├─────────────────────────────────────────────┤ │ Backend (4 files): │ │ ├─ api/handlers/search.ts │ │ ├─ api/services/elasticsearch.ts │ │ ├─ lib/query-builder.ts │ │ └─ lib/filters/vehicle-filters.ts │ │ Frontend (3 files): │ │ ├─ site/pages/Search.tsx │ │ ├─ site/components/SearchBar.tsx │ │ └─ site/components/FilterPanel.tsx │ └─────────────────────────────────────────────┘
... [10 more specs]
┌─────────────────────────────────────────────┐ │ 001-vehicle-details-display │ Status: ✅ COMPLETE ├─────────────────────────────────────────────┤ │ Backend (3 files): │ │ ├─ api/handlers/vehicle-details.ts │ │ ├─ api/services/vehicle-data.ts │ │ └─ lib/validators/vin.ts │ │ Frontend (2 files): │ │ ├─ site/pages/VehicleDetails.tsx │ │ └─ site/components/VehicleCard.tsx │ │ Tests (2 files): │ │ ├─ api/handlers/vehicle-details.test.ts │ │ └─ site/pages/VehicleDetails.test.tsx │ └─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐ │ 002-inventory-search │ Status: ✅ COMPLETE ├─────────────────────────────────────────────┤ │ Backend (4 files): │ │ ├─ api/handlers/search.ts │ │ ├─ api/services/elasticsearch.ts │ │ ├─ lib/query-builder.ts │ │ └─ lib/filters/vehicle-filters.ts │ │ Frontend (3 files): │ │ ├─ site/pages/Search.tsx │ │ ├─ site/components/SearchBar.tsx │ │ └─ site/components/FilterPanel.tsx │ └─────────────────────────────────────────────┘
... [10 more specs]

Files → Specs Reverse Index

Files → Specs Reverse Index

FileCovered By SpecsCountRisk
lib/utils/pricing.ts001, 003, 004, 007, 0095🔴 HIGH
lib/api/client.ts002, 005, 006, 0084🔴 HIGH
api/handlers/vehicle-details.ts0011🟢 LOW
site/pages/Home.tsx0031🟢 LOW
lib/types/vehicle.ts001, 002, 0113🟡 MEDIUM
... [99 files total]
FileCovered By SpecsCountRisk
lib/utils/pricing.ts001, 003, 004, 007, 0095🔴 HIGH
lib/api/client.ts002, 005, 006, 0084🔴 HIGH
api/handlers/vehicle-details.ts0011🟢 LOW
site/pages/Home.tsx0031🟢 LOW
lib/types/vehicle.ts001, 002, 0113🟡 MEDIUM
... [99 files total]

Coverage Statistics

Coverage Statistics

CategoryTotal FilesCoveredUncoveredCoverage %
Backend4542393%
Frontend3835392%
Infrastructure1210283%
Database880100%
Scripts64267%
TOTAL109991091%
CategoryTotal FilesCoveredUncoveredCoverage %
Backend4542393%
Frontend3835392%
Infrastructure1210283%
Database880100%
Scripts64267%
TOTAL109991091%

Coverage Heat Map

Coverage Heat Map

Backend       [████████████████░░] 93%
Frontend      [████████████████░░] 92%
Infrastructure [███████████████░░░] 83%
Database      [████████████████████] 100%
Scripts       [█████████░░░░░░░░░] 67%
Backend       [████████████████░░] 93%
Frontend      [████████████████░░] 92%
Infrastructure [███████████████░░░] 83%
Database      [████████████████████] 100%
Scripts       [█████████░░░░░░░░░] 67%

Coverage Gaps (10 files)

Coverage Gaps (10 files)

Files not covered by any specification:
Backend (3 files):
  • api/handlers/legacy-foo.js - Deprecated?
  • api/utils/debug.ts - Dev utility?
  • api/middleware/cors.ts - Shared infrastructure?
Frontend (3 files):
  • site/components/DevTools.tsx - Dev-only component
  • site/pages/404.tsx - Error page (needs spec?)
  • site/utils/logger.ts - Utility (shared)
Infrastructure (2 files):
  • .github/workflows/experimental.yml - WIP?
  • infrastructure/terraform/dev-only.tf - Dev env?
Scripts (2 files):
  • scripts/experimental/test.sh - WIP
  • scripts/deprecated/old-deploy.sh - Remove?
Files not covered by any specification:
Backend (3 files):
  • api/handlers/legacy-foo.js - Deprecated?
  • api/utils/debug.ts - Dev utility?
  • api/middleware/cors.ts - Shared infrastructure?
Frontend (3 files):
  • site/components/DevTools.tsx - Dev-only component
  • site/pages/404.tsx - Error page (needs spec?)
  • site/utils/logger.ts - Utility (shared)
Infrastructure (2 files):
  • .github/workflows/experimental.yml - WIP?
  • infrastructure/terraform/dev-only.tf - Dev env?
Scripts (2 files):
  • scripts/experimental/test.sh - WIP
  • scripts/deprecated/old-deploy.sh - Remove?

Recommendations:

Recommendations:

  1. Remove deprecated files (3 files identified)
  2. Create utility spec for shared utils (cors, logger)
  3. Document dev tools in separate spec
  4. Review experimental workflows/scripts
  1. Remove deprecated files (3 files identified)
  2. Create utility spec for shared utils (cors, logger)
  3. Document dev tools in separate spec
  4. Review experimental workflows/scripts

Shared Files (Referenced by 3+ Specs)

Shared Files (Referenced by 3+ Specs)

FileReferenced ByCountRisk Level
lib/utils/pricing.ts001, 003, 004, 007, 0095🔴 HIGH
lib/api/client.ts002, 005, 006, 0084🔴 HIGH
lib/types/vehicle.ts001, 002, 0113🟡 MEDIUM
lib/validators/input.ts001, 002, 0053🟡 MEDIUM
FileReferenced ByCountRisk Level
lib/utils/pricing.ts001, 003, 004, 007, 0095🔴 HIGH
lib/api/client.ts002, 005, 006, 0084🔴 HIGH
lib/types/vehicle.ts001, 002, 0113🟡 MEDIUM
lib/validators/input.ts001, 002, 0053🟡 MEDIUM

Risk Assessment:

Risk Assessment:

🔴 High-risk files (4+ specs):
  • Changes affect multiple features
  • Require comprehensive testing
  • Should have 95%+ test coverage
  • Consider splitting if too coupled
🟡 Medium-risk files (2-3 specs):
  • Changes affect few features
  • Standard testing required
  • Monitor for increased coupling
🟢 Low-risk files (1 spec):
  • Feature-specific
  • Standard development flow
🔴 High-risk files (4+ specs):
  • Changes affect multiple features
  • Require comprehensive testing
  • Should have 95%+ test coverage
  • Consider splitting if too coupled
🟡 Medium-risk files (2-3 specs):
  • Changes affect few features
  • Standard testing required
  • Monitor for increased coupling
🟢 Low-risk files (1 spec):
  • Feature-specific
  • Standard development flow

Summary

Summary

  • ✅ 91% coverage - Excellent
  • ⚠️ 10 gap files - Need review
  • 🔴 2 high-risk shared files - Monitor closely
  • 📊 12 specs covering 99 files
  • ✅ 91% coverage - Excellent
  • ⚠️ 10 gap files - Need review
  • 🔴 2 high-risk shared files - Monitor closely
  • 📊 12 specs covering 99 files

Action Items:

Action Items:

  1. Review 10 gap files and either:
    • Create specs for them
    • Remove if deprecated
    • Document as infrastructure/utilities
  2. Add extra test coverage for high-risk shared files
  3. Consider refactoring pricing.ts (5 specs depend on it)
Next Steps:
Run 
/speckit.clarify
to resolve any [NEEDS CLARIFICATION] markers in specs that were identified during coverage analysis.

---
  1. Review 10 gap files and either:
    • Create specs for them
    • Remove if deprecated
    • Document as infrastructure/utilities
  2. Add extra test coverage for high-risk shared files
  3. Consider refactoring pricing.ts (5 specs depend on it)
Next Steps:
Run 
/speckit.clarify
to resolve any [NEEDS CLARIFICATION] markers in specs that were identified during coverage analysis.

---

Implementation Details

实现细节

File Path Extraction Patterns

文件路径提取模式

Look for these patterns in spec markdown:
markdown
undefined
在规格文档的Markdown中查找以下模式：
markdown
undefined

In "Files" or "Implementation Status" sections:

In "Files" or "Implementation Status" sections:

  • api/handlers/foo.ts
    ✅
  • Backend: 
    src/services/bar.js
  • File: 
    site/pages/Home.tsx
  • api/handlers/foo.ts
    ✅
  • Backend: 
    src/services/bar.js
  • File: 
    site/pages/Home.tsx

In code blocks:

In code blocks:

typescript
// File: lib/utils/pricing.ts
typescript
// File: lib/utils/pricing.ts

In lists:

In lists:

Backend Components

Backend Components

  • Vehicle handler: 
    api/handlers/vehicle.ts
  • Pricing service: 
    api/services/pricing.ts

**Extraction strategy:**
1. Parse markdown sections titled "Files", "Implementation Status", "Components"
2. Extract backtick-wrapped paths: `path/to/file.ext`
3. Extract bold paths: **File:** path/to/file.ext
4. Look for file extensions: .ts, .tsx, .js, .jsx, .py, .go, .tf, .yml, etc.
5. Validate paths actually exist in codebase
  • Vehicle handler: 
    api/handlers/vehicle.ts
  • Pricing service: 
    api/services/pricing.ts

**提取策略：**
1. 解析标题为"Files"、"Implementation Status"、"Components"的Markdown章节
2. 提取反引号包裹的路径：`path/to/file.ext`
3. 提取加粗标记的路径：**File:** path/to/file.ext
4. 查找包含以下扩展名的文件：.ts, .tsx, .js, .jsx, .py, .go, .tf, .yml 等
5. 验证路径在代码库中实际存在

ASCII Box Generation

ASCII框图生成

bash
undefined
bash
undefined

Box characters

Box characters

TOP="┌─┐" SIDE="│" DIVIDER="├─┤" BOTTOM="└─┘" BRANCH="├─" LAST_BRANCH="└─"
TOP="┌─┐" SIDE="│" DIVIDER="├─┤" BOTTOM="└─┘" BRANCH="├─" LAST_BRANCH="└─"

Example template

Example template

echo "┌─────────────────────────────────┐" echo "│ $SPEC_NAME │ Status: $STATUS" echo "├─────────────────────────────────┤" echo "│ Backend: │" for file in $BACKEND_FILES; do echo "│ ├─ $file" done echo "│ Frontend: │" for file in $FRONTEND_FILES; do echo "│ ├─ $file" done echo "└─────────────────────────────────┘"
undefined
echo "┌─────────────────────────────────┐" echo "│ $SPEC_NAME │ Status: $STATUS" echo "├─────────────────────────────────┤" echo "│ Backend: │" for file in $BACKEND_FILES; do echo "│ ├─ $file" done echo "│ Frontend: │" for file in $FRONTEND_FILES; do echo "│ ├─ $file" done echo "└─────────────────────────────────┘"
undefined

Coverage Calculation

覆盖统计计算

javascript
// Calculate coverage percentage
const totalFiles = Object.keys(allFiles).length;
const coveredFiles = Object.keys(filesToSpecs).length;
const coveragePercent = Math.round((coveredFiles / totalFiles) * 100);

// By category
const backendCoverage = (coveredBackend / totalBackend) * 100;
const frontendCoverage = (coveredFrontend / totalFrontend) * 100;
javascript
// Calculate coverage percentage
const totalFiles = Object.keys(allFiles).length;
const coveredFiles = Object.keys(filesToSpecs).length;
const coveragePercent = Math.round((coveredFiles / totalFiles) * 100);

// By category
const backendCoverage = (coveredBackend / totalBackend) * 100;
const frontendCoverage = (coveredFrontend / totalFrontend) * 100;

Heat Map Visualization

热力图可视化

javascript
// Generate heat map bar
function heatMapBar(percentage) {
  const filled = Math.round(percentage / 5); // 20 blocks total
  const empty = 20 - filled;
  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${percentage}%`;
}

// Example output:
// [████████████████░░] 92%
javascript
// Generate heat map bar
function heatMapBar(percentage) {
  const filled = Math.round(percentage / 5); // 20 blocks total
  const empty = 20 - filled;
  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${percentage}%`;
}

// Example output:
// [████████████████░░] 92%

Success Criteria

成功标准

✅ Coverage map generated at 
docs/spec-coverage-map.md
✅ ASCII box diagram for every spec ✅ Reverse index table (files → specs) ✅ Coverage statistics by category ✅ Heat map visualization ✅ Gap analysis with recommendations ✅ Shared files risk assessment ✅ Overall coverage percentage > 85%
✅ 已在 
docs/spec-coverage-map.md
生成覆盖映射图 ✅ 每个规格文档都有对应的ASCII框图 ✅ 包含反向索引表（文件→规格） ✅ 包含按分类统计的覆盖数据 ✅ 包含热力图可视化 ✅ 包含覆盖缺口分析及建议 ✅ 包含共享文件风险评估 ✅ 整体覆盖率 > 85%

Error Handling

错误处理

If no specs found:
⚠️ No specifications found in .specify/memory/specifications/ or specs/
Cannot generate coverage map without specs.

Run Gear 3 first: /stackshift.create-specs
If specs have no file references:
⚠️ Specs don't contain file references.
Cannot generate coverage map.

This usually means:
1. Specs were created but implementation hasn't started
2. Specs need "Files" or "Implementation Status" sections
3. Using old spec format (update specs)
If coverage very low (< 50%):
⚠️ Coverage is only 35%

This indicates:
- Many files not documented in specs
- Specs may be incomplete
- Consider running /speckit.analyze to validate alignment
如果未找到规格文档：
⚠️ No specifications found in .specify/memory/specifications/ or specs/
Cannot generate coverage map without specs.

Run Gear 3 first: /stackshift.create-specs
如果规格文档中没有文件引用：
⚠️ Specs don't contain file references.
Cannot generate coverage map.

This usually means:
1. Specs were created but implementation hasn't started
2. Specs need "Files" or "Implementation Status" sections
3. Using old spec format (update specs)
如果覆盖率极低（<50%）：
⚠️ Coverage is only 35%

This indicates:
- Many files not documented in specs
- Specs may be incomplete
- Consider running /speckit.analyze to validate alignment

Usage Examples

使用示例

After Gear 6 Completion

第6阶段完成后

User: [Gear 6 completes all implementations]

StackShift: "✅ All features implemented!

Let me generate a coverage map to visualize spec-to-code relationships..."

[Generates coverage map]

StackShift: "📊 Coverage Map Complete!

✅ 91% coverage (99/109 files)
🚨 10 gap files identified
🔴 2 high-risk shared files

Saved to: docs/spec-coverage-map.md

Would you like me to:
1. Review gap files
2. Create specs for missing files
3. Commit all changes"
User: [Gear 6 completes all implementations]

StackShift: "✅ All features implemented!

Let me generate a coverage map to visualize spec-to-code relationships..."

[Generates coverage map]

StackShift: "📊 Coverage Map Complete!

✅ 91% coverage (99/109 files)
🚨 10 gap files identified
🔴 2 high-risk shared files

Saved to: docs/spec-coverage-map.md

Would you like me to:
1. Review gap files
2. Create specs for missing files
3. Commit all changes"

During Cleanup

代码清理阶段

User: "Clean up the documentation and finalize"

StackShift: "Running cleanup tasks:

1. Generating spec-coverage-map...
2. Updating README with coverage stats...
3. Removing temporary files...
4. Creating final summary...

✅ Cleanup complete!"
User: "Clean up the documentation and finalize"

StackShift: "Running cleanup tasks:

1. Generating spec-coverage-map...
2. Updating README with coverage stats...
3. Removing temporary files...
4. Creating final summary...

✅ Cleanup complete!"

Technical Notes

技术说明

  • Parse specs in sorted order (001, 002, etc.) for consistent output
  • Handle both 
    .specify/memory/specifications/
    and 
    specs/*/spec.md
    formats
  • Use relative paths from project root
  • Validate file existence before including in map
  • Mark non-existent files as ❌ in coverage map
  • Use unicode box-drawing characters (not ASCII art approximations)
  • Generate clean markdown tables with proper alignment
  • Include timestamp for tracking coverage over time
This coverage map provides crucial visibility into spec-code alignment and helps identify documentation gaps!
  • 按排序后的顺序解析规格文档（001、002等）以保证输出一致
  • 支持 
    .specify/memory/specifications/
    和 
    specs/*/spec.md
    两种格式
  • 使用项目根目录的相对路径
  • 在添加到映射图前验证文件是否存在
  • 在覆盖映射图中将不存在的文件标记为 ❌
  • 使用Unicode框图绘制字符（而非ASCII近似字符）
  • 生成格式规范的Markdown表格，对齐正确
  • 包含时间戳以跟踪覆盖率随时间的变化
此覆盖映射图为规格文档与代码的对齐情况提供了关键可见性，并有助于发现文档缺口！