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

```markdown
# 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

```markdown
# 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
```