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