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

name: ipa-spec description: Generate SRD.md and UI_SPEC.md with design research — Stage 1 of the IPA pipeline. Use when starting a new project or feature that needs structured requirements and UI specification, when converting raw ideas into formal docs, or when combining text, URL, and image inputs into a full spec. Trigger phrases: "generate srd and ui spec", "create ipa spec", "stage 1 ipa specification".

Overview

Generates Stage 1 IPA documents: SRD (System Requirement Definition) and UI_SPEC (Basic Design with Design System). Includes a design research phase that extracts visual inspiration from URLs or images before generating the spec.

When to Use

• Starting a new project or feature from a raw idea
• Converting external requirements into IPA format
• Design research is needed before writing UI specifications
• Combining text description with visual references

Don't Use When

• SRD already exists and only UI_SPEC needs regeneration (use ipa-bd)
• You have an external SRS document to import (use ipa-import)
• Fast mode is preferred and gates should be skipped (use ipa-fast)

Flags

• --fast: Skip GATE 2 prompt (not recommended for new projects)
• --no-design: Skip design research phase

Input Types

Input	Prefix	Purpose
Raw requirement	(none)	Text describing the feature/project
URL reference	@https://...	Design inspiration from website
Image reference	@./path.png	Design inspiration from screenshot

Examples

# Raw requirement only
ipa-spec "Build a FinOps dashboard for cloud cost management"

# Raw requirement + URL reference
ipa-spec "Build a FinOps dashboard" @https://stripe.com/billing

# Raw requirement + image
ipa-spec "Build a FinOps dashboard" @./design-mockup.png

# URL only (requirement inferred)
ipa-spec @https://linear.app

Design Research Phase

Case 1: User provides @url and/or @image

1. Analyze the reference(s) — fetch URL or read image
2. Extract color palette, typography, layout patterns, component styles
3. Document in UI_SPEC.md Design System section

Case 2: Raw requirement only (no @url/@image)

1. Search for design inspiration: best {project-type} dashboard design 2025 2026
2. Propose 3 design options to user
3. After user selects, analyze chosen reference
4. Document in Design System section

Design System Output (Mandatory)

UI_SPEC.md must include a complete Design System with:

• Color palette (primary, semantic, greys)
• Typography scale (h1-h4, body, caption)
• Spacing scale (xs, sm, md, lg, xl)
• Border radius tokens
• Shadow tokens
• CJX stage variables

Workflow

1. Design Research Phase (extract from @url/@image or search)
2. Analyze input (check lean output, read existing docs)
3. Generate SRD.md with FR-xx, S-xx, E-xx IDs
4. Generate UI_SPEC.md with Design System and screen specs
5. Output GATE 2 checklist

Required Output Structure

docs/SRD.md

# System Requirement Definition (SRD)

## 1. System Overview
## 2. Actors (User Roles)
## 3. Functional Requirements (FR-xx)
## 4. Screen List (S-xx)
## 5. Entity List (E-xx)
## 6. Non-Functional Requirements

docs/UI_SPEC.md

# Basic Design (UI Specification)

## 1. Screen Flow
## 2. Screen Specifications
### S-01: Login Screen
## 3. Design System
## 4. Design Rationale

GATE 2: Requirements Validation

At end of response, output checklist:

## GATE 2: Requirements Validation

Before proceeding to ipa-design:
- [ ] Stakeholders reviewed SRD.md
- [ ] Feature priorities (P1/P2/P3) confirmed
- [ ] Scope still matches lean output
- [ ] No scope creep detected

Next: ipa-design