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

What This Does

Creates a visual map showing:

• Spec → Files: Which code files each spec covers

• Files → Specs: Which spec(s) cover each code file (reverse index)

• Coverage Statistics: Percentages by category (backend, frontend, infrastructure)

• Gap Analysis: Code files not covered by any spec

• Shared Files: Files referenced by multiple specs

Process

Step 1: Discover All Specifications

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

Count them

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

Step 2: Extract File References from Each Spec

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:

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

Step 3: Categorize Files

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/

Step 4: Generate ASCII Box Diagrams

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)

Step 5: Create Reverse Index

Build a table showing which spec(s) cover each file:

Files → Specs Reverse Index

Highlight:

• 🟢 Single spec (1 spec) - Normal coverage

• 🟡 Shared (2-3 specs) - Multiple features use this

• 🔴 Hot (4+ specs) - Critical shared utility

Step 6: Calculate Coverage Statistics

Coverage Statistics

Coverage Heat Map:

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

Step 7: Identify Gaps

🚨 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

Step 8: Highlight Shared Files

🔥 Shared Files (Referenced by 3+ Specs)

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

Spec-to-Code Coverage Map

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

Coverage by Spec

[For each spec, ASCII box diagram with files]

Files → Specs Reverse Index

[Table of all files and which specs cover them]

Coverage Statistics

[Stats table and heat map]

Coverage Gaps

[List of files not covered by any spec]

Shared Files

[Files referenced by multiple specs with risk assessment]

Recommendations

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

When to Generate

Automatic Triggers

• End of Gear 6 (Implement) - After all features implemented

• Cleanup Phase - When finalizing documentation

• Manual Request - User asks for coverage analysis

Manual Invocation

Check current coverage

cat .stackshift-state.json | grep currentGear

If Gear 6 complete or in cleanup:

"Generate spec-to-code coverage map"

Integration Points

In Gear 6 (Implement) Skill

After completing all implementations, add:

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

In Cleanup/Finalization

When user says "cleanup" or "finalize documentation":

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

Example Output

Spec-to-Code Coverage Map

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

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]

Files → Specs Reverse Index

... [99 files total]

Coverage Statistics

Coverage Heat Map

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

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?

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

Shared Files (Referenced by 3+ Specs)

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

Summary

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

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.

Implementation Details

File Path Extraction Patterns

Look for these patterns in spec markdown:

In "Files" or "Implementation Status" sections:

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

In code blocks:

// File: lib/utils/pricing.ts

In lists:

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

### ASCII Box Generation

```bash
# Box characters
TOP="┌─┐"
SIDE="│"
DIVIDER="├─┤"
BOTTOM="└─┘"
BRANCH="├─"
LAST_BRANCH="└─"

# 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 "└─────────────────────────────────┘"

Coverage Calculation

// 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

// 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%

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

Usage Examples

After Gear 6 Completion

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

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!