Generate a visual spec-to-code coverage map showing which code files are covered by which specifications. Creates ASCII diagrams, reverse indexes, and coverage statistics. Use after implementation or during cleanup to validate spec coverage.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
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
Creates a visual map showing:
# 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"
For each spec, look for file references in these sections:
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:
Group files by type:
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)
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:
## 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%
## 🚨 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
## 🔥 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
# 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]
# Check current coverage
cat .stackshift-state.json | grep currentGear
# If Gear 6 complete or in cleanup:
"Generate spec-to-code coverage map"
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
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
After generating coverage map, you should have:
docs/spec-coverage-map.md file created# 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.
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
api/handlers/vehicle.tsapi/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 "└─────────────────────────────────┘"
// 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;
// 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%
✅ 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%
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
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: "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!"
.specify/memory/specifications/ and specs/*/spec.md formatsThis coverage map provides crucial visibility into spec-code alignment and helps identify documentation gaps!