Initial commit: antigravity-ipa-workflow

skills/ipa-validate/SKILL.md

@@ -0,0 +1,139 @@
+---
+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.