Initial commit: antigravity-ipa-workflow

skills/ipa-docs/SKILL.md

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