antigravity-ipa-workflow/skills/ipa-validate/SKILL.md

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".

Do NOT validate until API_SPEC.md AND DB_DESIGN.md exist. Run ipa-detail first.

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

## 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.