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:

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

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

| File | Covered By | Count |
|------|------------|-------|
| api/handlers/vehicle.ts | 001-vehicle-details, 003-pricing | 2 |
| site/pages/Home.tsx | 001-homepage | 1 |
| lib/utils/format.ts | 001-vehicle, 002-search, 004-pricing | 3 |

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

| Category | Total Files | Covered | Coverage % |
|----------|-------------|---------|------------|
| Backend | 45 | 42 | 93% |
| Frontend | 38 | 35 | 92% |
| Infrastructure | 12 | 10 | 83% |
| Database | 8 | 8 | 100% |
| Scripts | 6 | 4 | 67% |
| **TOTAL** | **109** | **99** | **91%** |

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)

| File | Specs | Count | Risk |
|------|-------|-------|------|
| lib/utils/pricing.ts | 001, 003, 004, 007, 009 | 5 | 🔴 HIGH |
| lib/api/client.ts | 002, 005, 006, 008 | 4 | 🔴 HIGH |
| lib/types/vehicle.ts | 001, 002, 011 | 3 | 🟡 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

# 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

1. End of Gear 6 (Implement) – After all features implemented
2. Cleanup Phase – When finalizing documentation
3. 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

| File | Covered By Specs | Count | Risk |
|------|------------------|-------|------|
| lib/utils/pricing.ts | 001, 003, 004, 007, 009 | 5 | 🔴 HIGH |
| lib/api/client.ts | 002, 005, 006, 008 | 4 | 🔴 HIGH |
| api/handlers/vehicle-details.ts | 001 | 1 | 🟢 LOW |
| site/pages/Home.tsx | 003 | 1 | 🟢 LOW |
| lib/types/vehicle.ts | 001, 002, 011 | 3 | 🟡 MEDIUM |

... [99 files total]

---

## Coverage Statistics

| Category | Total Files | Covered | Uncovered | Coverage % |
|----------|-------------|---------|-----------|------------|
| Backend | 45 | 42 | 3 | 93% |
| Frontend | 38 | 35 | 3 | 92% |
| Infrastructure | 12 | 10 | 2 | 83% |
| Database | 8 | 8 | 0 | 100% |
| Scripts | 6 | 4 | 2 | 67% |
| **TOTAL** | **109** | **99** | **10** | **91%** |

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

| File | Referenced By | Count | Risk Level |
|------|---------------|-------|------------|
| lib/utils/pricing.ts | 001, 003, 004, 007, 009 | 5 | 🔴 HIGH |
| lib/api/client.ts | 002, 005, 006, 008 | 4 | 🔴 HIGH |
| lib/types/vehicle.ts | 001, 002, 011 | 3 | 🟡 MEDIUM |
| lib/validators/input.ts | 001, 002, 005 | 3 | 🟡 MEDIUM |

### 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:
```typescript
// 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!