100 lines
2.7 KiB
Markdown
100 lines
2.7 KiB
Markdown
---
|
|
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
|