vm-gap-analysis-report-generator

# VM Gap Analysis Report Generator

## Overview

Given gap analysis data (from vm-requirements-cross-reference, coverage calculations, or completeness assessments), this skill produces standardized reports in JSON + Markdown format. The skill is a **report formatter** — it does not perform the analysis itself. Consuming agents provide the analysis data; this skill structures it into consistent, readable reports.

## Brownfield Context

Brownfield gap reports serve a different audience than greenfield requirements reports. They communicate to development teams and architects:
- What the change/requirement asks for that does not yet exist
- What the existing code does that the spec never mentions (drift risk)
- What exists in both the spec and the code (confirmed, no action needed)
- Priority of action based on criticality and effort

This skill produces reports structured around those brownfield concerns.

## When to Use

- After vm-requirements-cross-reference produces mapping results
- After change impact analysis produces an affected-files list and net-new requirement set
- After requirement gap analysis produces coverage data for a system appreciation doc
- Any agent workflow that produces structured gap findings needing a formatted report

## When NOT to Use

- The analysis has not been performed yet (run analysis skill/agent first)
- A simple list of gaps is sufficient without a formal report

## Unitary Function

**ONE RESPONSIBILITY:** Format gap analysis data into standardized JSON + Markdown reports

**NOT RESPONSIBLE FOR:**
- Performing the gap analysis (use vm-requirements-cross-reference first)
- Making build-vs-buy decisions
- Creating GitHub issues (use vm-github-issue-writer)

## Inputs

```json
{
  "report_type": "change_impact|requirement_gap|standards_gap|traceability",
  "metadata": {
    "title": "Report title",
    "date": "ISO-8601",
    "source_a": "Source A name (e.g., Change Request CR-2026-042)",
    "source_b": "Source B name (e.g., Codebase capabilities from RE Agent output)",
    "analyst_agent": "Agent name that performed analysis"
  },
  "coverage_data": {
    "total_items": 0,
    "by_coverage": {
      "full_match": 0,
      "partial_match": 0,
      "no_match": 0
    },
    "overall_score": 0.0,
    "weighted_score": 0.0
  },
  "gaps": [
    {
      "id": "GAP-001",
      "source_item_id": "A-005",
      "source_item_text": "The system shall support MFA for all admin users",
      "severity": "critical|major|minor",
      "category": "New capability required",
      "description": "No MFA implementation found in existing codebase",
      "evidence": "auth/ module — only password-based authentication found",
      "recommendation": "Implement TOTP-based MFA in the auth layer"
    }
  ],
  "mappings": [],
  "priority_breakdown": {}
}
```

## Report Types

| Report Type | Use Case | Key Sections |
|---|---|---|
| `change_impact` | Change request vs existing codebase | Impact matrix, net-new items, affected existin