vm-requirements-cross-reference

# VM Requirements Cross-Reference

## Overview

Given two structured requirement or capability sets (Source A and Source B), this skill performs a **bidirectional semantic cross-reference** — identifying what is in A but missing from B, what is in B but missing from A, what partially overlaps, and producing coverage scores with match rationale.

This is a **generative** skill: semantic matching between informally-expressed items (e.g., a change request's stated goals) and a structured set (e.g., capabilities extracted from RE Agent output) requires LLM reasoning, not simple string comparison. This skill provides structured methodology to guide that reasoning consistently.

## Brownfield Context

In brownfield scenarios, Source A is typically a document (requirement, change request, system appreciation doc) and Source B is a set of capabilities extracted from the existing codebase (via RE Agent output, file deep analysis, or flow mapper results). The cross-reference answers:

- "What in this change request already exists in the codebase?" (avoid re-implementing)
- "What does this requirement ask for that has no code equivalent?" (net-new work)
- "What does the codebase implement that the requirement doc never mentions?" (undocumented behavior, potential drift)

## When to Use

Invoke when:
- Comparing a change request against existing codebase capabilities
- Mapping a system appreciation document's stated features to what the code actually does
- Cross-referencing old requirements vs new requirements to find what changed
- Building a traceability matrix between a requirement set and an implementation inventory

Do NOT use when:
- Extracting requirements from a single document (use vm-document-markdown-converter + vm-document-section-classifier first)
- Checking a single requirement set for internal completeness
- Evaluating requirement quality

## Unitary Function

**ONE RESPONSIBILITY:** Take two pre-structured requirement/capability sets and produce a bidirectional coverage map with semantic match rationale, gap identification, and scoring.

**NOT RESPONSIBLE FOR:**
- Extracting requirements from raw documents (caller must pre-extract)
- Converting document formats (use vm-document-markdown-converter first)
- Classifying document sections (use vm-document-section-classifier first)
- Generating the final formatted report (use vm-gap-analysis-report-generator after this skill)

## Inputs

```json
{
  "cross_reference_id": "XREF-uuid",
  "source_a": {
    "label": "Change Request / Requirement Document",
    "type": "requirement_doc|change_request|system_appreciation|specification|meeting_notes",
    "items": [
      {
        "id": "A-001",
        "text": "Normalized requirement text",
        "original_text": "Exact quote from source document",
        "source_location": "Section/page reference",
        "category": "functional|non-functional|constraint|assumption",
        "priority": "mandatory|important|nice-to-have|unspecified"
      }