110 lines
3.1 KiB
Markdown
110 lines
3.1 KiB
Markdown
---
|
|
name: ipa-docs
|
|
description: IPA documentation sync specialist — tracks implementation status with symbols (pending/done/synced) across API_SPEC, DB_DESIGN, and UI_SPEC. Use when syncing docs after code implementation, verifying endpoint coverage, or keeping IPA docs accurate without full regeneration. Trigger phrases: "sync ipa docs", "update api spec after coding", "sync docs with implementation".
|
|
---
|
|
|
|
## Overview
|
|
|
|
Synchronizes IPA-generated documentation with actual implementation after coding is complete. Updates status tracking, schema changes, and table definitions while preserving traceability IDs and manual notes.
|
|
|
|
## When to Use
|
|
|
|
- After backend implementation to update endpoint and schema status
|
|
- When API routes or DB schema have changed
|
|
- After running a docs sync command in an IPA project
|
|
- When `docs/SRD.md` exists and implementation has progressed
|
|
|
|
## Don't Use When
|
|
|
|
- No IPA docs exist yet (run ipa-spec first)
|
|
- You want to regenerate docs from scratch (use ipa-init instead)
|
|
- Only planning phase — no implementation has happened yet
|
|
|
|
## IPA Documentation Structure
|
|
|
|
```
|
|
docs/
|
|
├── SRD.md # System Requirement Definition
|
|
├── UI_SPEC.md # Basic Design
|
|
├── API_SPEC.md # Detail Design (Interface)
|
|
└── DB_DESIGN.md # Detail Design (Database)
|
|
```
|
|
|
|
## Sync Workflow
|
|
|
|
### 1. API_SPEC.md Sync
|
|
|
|
Status update rules:
|
|
|
|
| Before | After | Condition |
|
|
|--------|-------|-----------|
|
|
| pending | done | Endpoint implemented in code |
|
|
| done | synced | Docs verified match code exactly |
|
|
| synced | done | Code changed, needs re-sync |
|
|
|
|
Steps:
|
|
1. Scan codebase for API routes/endpoints
|
|
2. Compare with Endpoint Matrix
|
|
3. Update status column
|
|
4. Update request/response schemas if changed
|
|
5. Preserve traceability lines (FR-xx, S-xx refs)
|
|
|
|
### 2. DB_DESIGN.md Sync
|
|
|
|
Steps:
|
|
1. Read actual schema (Drizzle, Prisma, raw SQL)
|
|
2. Compare with Table Definitions
|
|
3. Update table columns, types, constraints
|
|
4. Update ERD if structure changed
|
|
5. Preserve traceability lines (E-xx refs)
|
|
|
|
### 3. UI_SPEC.md Sync (if requested)
|
|
|
|
Steps:
|
|
1. Scan UI components in codebase
|
|
2. Update Screen Specifications
|
|
3. Preserve CJX section (personas, journey map)
|
|
4. Preserve Design System section
|
|
|
|
## Protected Sections
|
|
|
|
Never overwrite these manually-created sections:
|
|
|
|
| Doc | Protected Sections |
|
|
|-----|-------------------|
|
|
| SRD.md | All (source of truth) |
|
|
| UI_SPEC.md | CJX, Design System |
|
|
| API_SPEC.md | Traceability lines, Implementation Notes |
|
|
| DB_DESIGN.md | Traceability lines, Implementation Notes |
|
|
|
|
## Sync Report Format
|
|
|
|
```
|
|
## Docs Sync Report
|
|
|
|
### API_SPEC.md
|
|
- Status Updates:
|
|
- POST /auth/login: pending → done
|
|
- GET /users/:id: done → synced
|
|
- Schema Updates:
|
|
- Updated: GET /users/:id response (added `avatar` field)
|
|
|
|
### DB_DESIGN.md
|
|
- Table Updates:
|
|
- users: Added `avatar_url` column
|
|
```
|
|
|
|
## Traceability Validation
|
|
|
|
During sync, validate:
|
|
1. Every endpoint has FR-xx ref
|
|
2. Every screen has S-xx ref
|
|
3. Every table has E-xx ref
|
|
|
|
## Core Principles
|
|
|
|
- Update only what changed
|
|
- Preserve manual notes and comments
|
|
- Use incremental sync, not full regeneration
|
|
- Respect YAGNI/KISS/DRY
|