140 lines
3.6 KiB
Markdown
140 lines
3.6 KiB
Markdown
---
|
|
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.
|