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

name: ipa-docs-sync description: Sync IPA docs (API_SPEC, DB_DESIGN, UI_SPEC) with actual codebase implementation after coding is complete. Use after finishing backend tasks, when endpoint or schema drift has occurred, or to mark endpoints as implemented. Trigger phrases: "sync docs after coding", "update api spec from code", "ipa docs sync".

Overview

Detects differences between IPA documentation and actual implementation, then updates docs to reflect reality. Preserves manual notes and traceability references.

When to Use

• After completing backend implementation tasks
• When API routes or DB schema have changed since docs were generated
• To update endpoint status from pending to done
• After running any coding phase

Don't Use When

• No implementation has happened yet
• You want to regenerate docs from scratch (use ipa-init)
• Only UI changes occurred and API/DB is unchanged

Docs Synced

Doc	Sync From	When
docs/API_SPEC.md	Actual API endpoints in codebase	After backend tasks
docs/DB_DESIGN.md	Actual database schema	After backend tasks
docs/UI_SPEC.md	Actual UI components	After frontend tasks (if changed)

Workflow

Step 1: Detect Changes

1. Read current docs/API_SPEC.md
2. Scan codebase for actual API endpoints (Express, NestJS, FastAPI, etc.)
3. Extract request/response types
4. Compare and identify differences

Step 2: Update API_SPEC.md

If differences found:

1. Update endpoint list
2. Update request/response schemas
3. Update error codes
4. Update Endpoint Matrix status: pending → done (implemented), done → synced (verified)
5. Preserve manual notes and comments

Step 3: Update DB_DESIGN.md

1. Read actual database schema (Drizzle, Prisma, TypeORM, etc.)
2. Compare with docs/DB_DESIGN.md
3. Update table definitions, column types, relationships, indexes

Step 4: Update UI_SPEC.md (if requested)

Only if "ui" or "all" specified:

1. Scan UI components
2. Update screen list
3. Update component specs

Usage

# Sync API and DB docs (default)
ipa-docs-sync

# Sync all including UI
ipa-docs-sync all

# Sync specific doc
ipa-docs-sync api
ipa-docs-sync db
ipa-docs-sync ui

Output

## Docs Sync Report

### API_SPEC.md
- Added: POST /api/users/register
- Updated: GET /api/users/:id response schema
- Status Updates:
  - POST /auth/login: pending → done
  - GET /users/:id: pending → synced

### DB_DESIGN.md
- Added: sessions table
- Updated: users table (added email_verified column)

Important

• Preserve manual notes — don't overwrite human-added comments
• Create backup if significant changes are detected
• Show diff before applying changes
• Does not implement code