---
name: ipa-validate
description: Validate IPA documentation consistency, traceability, and completeness — checks ID cross-references, coverage gaps, and gate status across all four IPA docs. Use after manually editing docs, before planning, or after running ipa-docs-sync to verify completeness. Trigger phrases: "validate ipa docs", "check ipa traceability", "run ipa validation".
---

<HARD-GATE>Do NOT validate until API_SPEC.md AND DB_DESIGN.md exist. Run ipa-detail first.</HARD-GATE>

## Overview

Runs IPA validation across SRD, UI_SPEC, API_SPEC, and DB_DESIGN to check ID consistency, cross-references, traceability chain, and coverage gaps. Outputs a structured report with errors, warnings, and recommendations.

## When to Use

- After manually editing any IPA doc
- Before planning to ensure docs are valid
- After ipa-docs-sync to verify sync completeness
- As a quality gate before implementation

## Don't Use When

- IPA docs do not yet exist (run ipa-spec and ipa-detail first)
- After ipa-all or ipa-init — those run validation automatically

## Prerequisites

All four IPA docs must exist:
- `docs/SRD.md`
- `docs/UI_SPEC.md`
- `docs/API_SPEC.md`
- `docs/DB_DESIGN.md`

## Workflow

### Step 1: Check Docs Exist

Verify all required IPA docs are present. Report missing docs and stop if any are absent.

### Step 2: Extract IDs from SRD

Parse tables for:
- FR-xx (Feature List)
- S-xx (Screen List)
- E-xx (Entity List)
- B-xx (Batch List)
- R-xx (Report List)
- IF-xx (Integration List)

### Step 3: Validate Cross-References

Check each doc references valid SRD IDs:
- UI_SPEC.md → S-xx refs
- API_SPEC.md → FR-xx, S-xx refs
- DB_DESIGN.md → E-xx refs

### Step 4: Check Status Tracking

Verify API_SPEC.md Endpoint Matrix has status column with valid values: pending, done, synced.

### Step 5: Build Traceability Matrix

Map each FR-xx to its implementations across Screen, Endpoint, and Table.

### Step 6: Validate Gates

Check gate completion status (soft enforcement):
- GATE 1: Scope validation from lean
- GATE 2: Spec validation from ipa-spec
- GATE 3: Design validation from ipa-design

### Step 7: Generate Report

## Output

```markdown
## IPA Validation Report

### Summary
- Total Features (FR): X
- Total Screens (S): X
- Total Entities (E): X
- Total Endpoints: X
- Total Tables (T): X
- Errors: X
- Warnings: X
- Status: PASS / FAIL

### Traceability Matrix

| FR ID | Screen | API Endpoint | DB Table | Status |
|-------|--------|--------------|----------|--------|
| FR-01 | S-01   | E-01         | T-01     | Full   |
| FR-02 | S-02   | E-02, E-03   | T-01     | Full   |
| FR-03 | S-03   | —            | —        | Partial|
| FR-04 | —      | —            | —        | Missing|

### Coverage Summary
- Full coverage: 2 (50%)
- Partial coverage: 1 (25%)
- Missing coverage: 1 (25%)

### Gaps
- FR-03: Missing API endpoint mapping
- FR-04: Not mapped to any screen/API/DB

### Errors (blocking)
### Warnings (non-blocking)
### Recommendations
```

## Coverage Status

| Status | Meaning |
|--------|---------|
| Full | FR mapped to Screen + Endpoint + Table |
| Partial | FR mapped to some but not all components |
| Missing | FR not mapped to any component |

## Bi-directional Traceability

- Forward: FR-01 → S-01 → Endpoint → Table (every requirement has implementation)
- Backward: Table → Endpoint → S-01 → FR-01 (every implementation traces to a requirement)
- Orphan detection for both directions

## Usage

```
# After manual edits
ipa-validate

# Before planning
ipa-validate
plan

# After sync
ipa-docs-sync
ipa-validate
```

Does not modify docs — only validates.