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

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