antigravity-ipa-workflow/skills/ipa-detail/SKILL.md

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

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

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

# 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

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