---
name: ipa-detail
description: Generate API_SPEC.md and DB_DESIGN.md from SRD and UI_SPEC — Stage 3 of the IPA pipeline. Use when SRD and UI_SPEC are complete and interface contracts plus database schema need to be defined, when designing API endpoints from screen requirements, or when creating language-agnostic data models from entity lists. Trigger phrases: "generate api spec and db design", "ipa detail design", "stage 3 ipa".
---

<HARD-GATE>Do NOT generate API_SPEC/DB_DESIGN until UI_SPEC.md exists. Run ipa-design first.</HARD-GATE>

## Overview

Generate Stage 3 Detail Design documents following IPA standard. Platform agnostic — works with any project type.

Output:
- `docs/API_SPEC.md` — Interface specifications (API/CLI/MCP/Chat)
- `docs/DB_DESIGN.md` — Data design (SQL/NoSQL/Vector/File)

## When to Use

- docs/SRD.md and docs/UI_SPEC.md both exist and are reviewed
- Ready to define API contracts and database schema
- Completing Stage 3 of the IPA pipeline before planning

## Don't Use When

- UI_SPEC.md does not exist (run ipa-design first)
- SRD.md is missing (run ipa-spec first)
- Only UI changes are needed with no API/DB impact

## Project Type Handling

| Project Type | Interface Spec | Data Design |
|--------------|----------------|-------------|
| Web App | REST/GraphQL API | SQL/NoSQL |
| Desktop App | IPC/Native API | SQLite/Local |
| CLI Tool | Commands/Args/Flags | Config files |
| MCP Server | Tools/Resources/Prompts | — |
| Chatbot/RAG | Conversation flows | Vector DB |
| Library/SDK | Public API/Methods | — |

## Language-Agnostic Principle

API_SPEC.md uses:
- OpenAPI 3.x standard (YAML/JSON)
- Standard HTTP methods
- JSON Schema for request/response
- No framework-specific code

DB_DESIGN.md uses:
- Standard SQL (DDL)
- ER Diagram (Mermaid)
- Portable data types
- No ORM-specific syntax

## Workflow

1. Read `docs/SRD.md` for entities (E-xx) and features (FR-xx)
2. Read `docs/UI_SPEC.md` for screen → API mapping (S-xx)
3. Read prototypes if available for data flow visualization
4. Generate `docs/DB_DESIGN.md` (schema based on E-xx, 3NF, ER diagram)
5. Generate `docs/API_SPEC.md` (endpoints supporting all FR-xx and S-xx)
6. Verify traceability: API ↔ Screen ↔ Feature ↔ Entity
7. Ask user to review

## Required Output Structure

### docs/DB_DESIGN.md

```markdown
# Database Detailed Design

## 1. ER Diagram
[Mermaid ERD]

## 2. Table Definitions

### E-01: Users (users)
| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | uuid | PK | Unique ID |
| email | varchar | Unique, Not Null | User email |
```

### docs/API_SPEC.md

```markdown
# Interface Specification (API)

## 1. Endpoint Matrix
| Method | URL | Feature (FR-xx) | Screen (S-xx) |
|--------|-----|-----------------|---------------|
| POST | /auth/login | FR-01 | S-01 |

## 2. Endpoint Details

### POST /auth/login
- **Description**: Authenticate user
- **Request**: { "email": "...", "password": "..." }
- **Response**: { "token": "..." }
```

## Traceability Check

- Every table corresponds to an E-xx
- Every endpoint links to an FR-xx

## Next Steps

After generation: run plan to create implementation tasks.

Does not implement code — only generates documentation.