gh-jschulte-claude-plugins-stackshift/skills/spec-coverage-map/SKILL.md

name, description

name	description
spec-coverage-map	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.

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!