---
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