nono/antigravity-ipa-workflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: antigravity-ipa-workflow

Browse Source
This commit is contained in:
nvtien
2026-02-16 13:58:02 +09:00
commit c5d9aab580
43 changed files with 4436 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
skills/.gitkeep Normal file
View File

87
skills/ipa-all/SKILL.md Normal file
View File

@@ -0,0 +1,87 @@
---
name: ipa-all
description: Run the full IPA documentation pipeline in sequence — spec, design, detail, validate. Use when you want to generate all IPA docs in one command, need a complete documentation pass for a project, or are a power user comfortable skipping individual validation gates. Trigger phrases: "generate all IPA docs", "full IPA pipeline", "run ipa all".
---
> WARNING: This skill chains all IPA stages without stopping at individual validation gates.
>
> Recommended step-by-step flow:
> ```
> lean → ipa-spec → ipa-design → ipa-detail
> ```
>
> Use ipa-all only for rapid prototyping, existing projects with established docs, or when you understand the risks.
## Overview
Generate all IPA documentation in sequence:
1. SRD (System Requirement Definition)
2. UI_SPEC (Basic Design)
3. API_SPEC + DB_DESIGN (Detail Design)
4. Validation report (auto-run at end)
## When to Use
- Rapid prototyping or throwaway code
- Existing projects where full docs are needed quickly
- Power users who understand IPA gates and accept the risk
## Don't Use When
- First time using IPA workflow
- Complex enterprise projects with multiple stakeholders
- User research or scope validation has not been completed
- You want gate checkpoints between phases
## Workflow
### Step 1: Generate SRD
Read requirements from arguments, `docs/requirements.md`, or `docs/PRD.md`. Generate `docs/SRD.md` with 14 IPA sections. Wait for user approval before continuing.
### Step 2: Generate UI_SPEC
Read `docs/SRD.md`. Generate `docs/UI_SPEC.md`. Optionally generate HTML mockups. Wait for user approval.
### Step 3: Generate Detail Design
Read `docs/SRD.md` + `docs/UI_SPEC.md`. Generate `docs/API_SPEC.md` and `docs/DB_DESIGN.md`. Wait for user approval.
### Step 4: Validate
Run ipa-validate logic automatically. Check ID consistency (FR-xx, S-xx, E-xx) and traceability chain. Report errors and warnings.
## Output
```
docs/
├── SRD.md
├── UI_SPEC.md
├── API_SPEC.md
├── DB_DESIGN.md
└── tech-stack.md (if created)
ui-mockup/ (optional)
```
## Traceability Chain
```
Requirements
↓
SRD.md (FR-xx, S-xx, E-xx)
↓
UI_SPEC.md (S-xx → Screen specs)
↓
API_SPEC.md (API ↔ FR-xx ↔ S-xx)
DB_DESIGN.md (Table ↔ E-xx)
↓
plan → Tasks ref docs/
```
## Next Steps
After all docs generated and validated:
1. Review validation report
2. Fix any errors found
3. Run planning skill to create implementation tasks

87
skills/ipa-bd/SKILL.md Normal file
View File

@@ -0,0 +1,87 @@
---
name: ipa-bd
description: Generate UI_SPEC.md only from an existing SRD. Use when you need granular control over basic design generation, want to regenerate only the UI specification without touching the SRD, or are working on UI-only updates. Trigger phrases: "generate UI spec", "create basic design", "generate ui_spec only".
---
> TIP: Use ipa-spec instead to generate both SRD.md + UI_SPEC.md in one step.
>
> This skill is for granular control when you only need UI_SPEC.md.
>
> Prerequisite: `docs/SRD.md` must exist.
## Overview
Generate Basic Design documentation following IPA standard, with Customer Journey Experience (CJX), design reference support, and platform-specific UX patterns.
Output: `docs/UI_SPEC.md`
## When to Use
- SRD already exists and only UI spec is needed
- Regenerating UI spec after SRD changes
- Iterating on design system without touching requirements
## Don't Use When
- SRD does not yet exist (run ipa-spec first)
- You need both SRD and UI_SPEC generated together (use ipa-spec)
## Project Type Handling
| Project Type | UX Spec Focus |
|--------------|---------------|
| Web App | Screens, components, responsive |
| Desktop App | Windows, dialogs, menus |
| CLI Tool | Commands, output, prompts |
| MCP Server | Tool descriptions, prompts |
| Chatbot/RAG | Conversation flows, responses |
| Library/SDK | API docs, examples |
## User Research Integration
If `docs/USER_RESEARCH.md` exists:
1. Read personas and journey maps
2. Map journey stages to screens
3. Add design rationale to each screen
4. Apply emotional design (CJX)
## Workflow
### With Reference URL
1. Fetch reference URL
2. Extract design system (colors, fonts, spacing)
3. Analyze screenshots if needed
4. Generate UI_SPEC with extracted values
### Without Reference
1. Ask user for color preference or use neutral palette
2. Generate default design system
3. Generate UI_SPEC
## Output Structure
```markdown
# UI Specification (Basic Design)
## 1. Customer Journey Experience (CJX)
### User Personas
### Customer Journey Map
## 2. Design System
### Color Palette
### Typography
## 3. Screen Specifications
### S-01: [Screen Name]
**Refs:** FR-xx (SRD), CJX Stage: [stage]
**Layout:** [ASCII diagram]
**Components:** [table]
```
## After Generation
1. Save to `docs/UI_SPEC.md`
2. Ask user to review design system
3. Next step: run ipa-design to generate HTML mockups, or ipa-detail for API/DB design

99
skills/ipa-context-aware-planning/SKILL.md Normal file
View File

@@ -0,0 +1,99 @@
---
name: ipa-context-aware-planning
description: Extends planning with @path context syntax for design mockup integration and tech-stack-aware code generation. Use when planning with design file references, when a plan command includes @path arguments pointing to mockups or prototypes, or when tech-stack-specific code generation is needed. Trigger phrases: "plan with design context", "use @path in plan", "planning with mockups".
---
## Overview
Supplements the planning workflow with @path context reference parsing, design mockup analysis, and tech-stack-aware code transformation.
## When to Use
- Planning commands include `@path` syntax (e.g., `@docs/design-mockups`)
- Keywords "design", "mockup", "prototype", or "UI" appear with file references
- Tech-stack-specific code output is required in plan tasks
## Don't Use When
- No design files or @path references are present
- Planning a purely backend or data-only task with no UI component
## Syntax
| Pattern | Example | Description |
|---------|---------|-------------|
| `@folder` | `@docs/design` | Include entire folder as context |
| `@file` | `@docs/spec.md` | Include single file |
| Multiple | `@docs/design @docs/api` | Space-separated refs |
## Workflow
### Step 0: Tech Stack Detection (FIRST)
Detect target framework from project docs:
1. Read `.claude/tech-stack.md` (primary)
2. Fallback: `CLAUDE.md`, `docs/tech-stack.md`, `docs/project-overview-pdr.md`
3. Extract frontend framework (Next.js, React, Vue, Angular, Astro, Svelte)
4. Set transformation rules for output code
### Step 1: Context Parsing
Parse @path references from arguments:
1. Extract all @path patterns
2. Validate each path exists
3. Categorize files by type (design/docs/config)
4. Build structured context object
### Step 2: Design Analysis (if HTML/CSS/JS detected)
Hybrid analysis workflow:
1. Screenshot HTML with visual analysis tool
2. Parse HTML structure and CSS variables
3. Extract component inventory, colors, typography, exact content
4. Generate design-analysis-report.md
### Step 3: Code Transformation
Apply tech-stack rules to extracted code:
- Transform `class` → `className` for React/Next.js or keep as `class`
- Adapt icon imports for target library
- Generate correct component file extensions
- Apply framework-specific patterns
### Step 4: Integration with Planning
1. Copy design files to `{plan-dir}/design/`
2. Save report to `{plan-dir}/reports/design-analysis-report.md`
3. Pass enriched context to planning workflow
4. Include tech-stack-adapted code in phases
## Output Structure
```
{plan-dir}/
├── design/
│ └── prototype/
│ ├── login.html
│ └── login.css
├── reports/
│ └── design-analysis-report.md
├── plan.md
└── phase-XX-xxx.md
```
## File Categorization
| Category | Extensions | Action |
|----------|------------|--------|
| design | .html, .css, .js, .jsx, .tsx, .vue, .svelte | Analyze + copy |
| docs | .md, .txt, .rst | Read as context |
| config | .json, .yaml, .yml | Read as context |
| other | * | List only |
## Error Handling
| Error | Action |
|-------|--------|
| Path not found | Warn user, continue without |
| Too many files (>50) | Warn, ask to narrow scope |
| Visual analysis unavailable | Fallback to code-only parsing |

62
skills/ipa-dd/SKILL.md Normal file
View File

@@ -0,0 +1,62 @@
---
name: ipa-dd
description: Alias for ipa-detail — generate API_SPEC.md and DB_DESIGN.md from SRD and UI_SPEC. Use when referring to the detail design stage by its legacy name, generating interface and data design specs, or completing Stage 3 of the IPA pipeline. Trigger phrases: "generate detail design", "create api spec and db design", "ipa dd".
---
<HARD-GATE>Do NOT generate API_SPEC/DB_DESIGN until UI_SPEC.md exists. Run ipa-design first.</HARD-GATE>
> TIP: `ipa-detail` is the canonical name for this skill. ipa-dd is kept for backward compatibility. Both produce identical output.
## Overview
Generate Detail Design (Stage 3) 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
- SRD.md and UI_SPEC.md both exist
- Ready to define API contracts and database schema
- Completing Stage 3 of the IPA pipeline
## Don't Use When
- UI_SPEC.md does not yet exist (run ipa-design first)
- SRD.md is missing (run ipa-spec first)
## 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 — 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 and features
2. Read `docs/UI_SPEC.md` for screen → API mapping
3. Generate `docs/API_SPEC.md` (OpenAPI standard)
4. Generate `docs/DB_DESIGN.md` (SQL standard)
5. Add implementation notes if tech-stack.md exists
6. Ask user to review
## Traceability Check
- Every table corresponds to an E-xx
- Every endpoint links to an FR-xx
## Next Steps
After generation: run planning skill to create implementation tasks.

125
skills/ipa-design/SKILL.md Normal file
View File

@@ -0,0 +1,125 @@
---
name: ipa-design
description: Generate production-ready HTML/CSS/JS prototypes from UI_SPEC.md. Use when you need visual mockups for all screens defined in the UI spec, want to validate UI before proceeding to detail design, or need HTML prototypes for design analysis. Trigger phrases: "generate prototypes", "create html mockups", "generate ui prototypes from spec".
---
<HARD-GATE>Do NOT generate UI mockups until SRD.md exists in ./docs/. Run ipa-spec first.</HARD-GATE>
## Overview
Generate production-ready HTML/CSS/JS prototypes from `docs/UI_SPEC.md`. This skill implements the spec exactly — no creative design decisions.
## When to Use
- UI_SPEC.md exists and is complete
- Visual prototypes are needed for user testing or development reference
- Completing Stage 2 (design) of the IPA pipeline
## Don't Use When
- UI_SPEC.md does not exist (run ipa-spec first)
- You want to make design decisions — this skill only implements what the spec defines
- Rapid text-only documentation is sufficient
## Mandatory Rules (NON-NEGOTIABLE)
1. Read `docs/UI_SPEC.md` COMPLETELY before generating any screen
2. Screen content MUST match UI_SPEC exactly — no improvisation
3. If spec says "API Keys" → output "API Keys", not "Integrations"
4. No creative additions beyond what spec defines
5. If spec is unclear → output placeholder with `<!-- TODO: clarify in spec -->`
## Workflow
```
1. Read docs/UI_SPEC.md completely
├── Count total screens
├── Note each screen's purpose
└── Extract Design System tokens
2. For EACH screen in UI_SPEC:
├── Read screen spec section
├── Generate HTML matching spec exactly
├── Apply CJX stage from spec
└── Use layout classes from references
3. Generate shared files:
├── styles.css (design tokens from UI_SPEC)
├── components.css
├── interactions.js (CJX animations)
└── README.md (FR mapping)
4. Validate:
├── Count screens matches UI_SPEC
├── Each screen content matches spec
└── All layout classes correct
```
## Output Structure
```
prototypes/
├── README.md # Index + FR mapping
├── styles.css # Design tokens from UI_SPEC
├── components.css # Reusable components
├── interactions.js # CJX animations
├── s01-{screen}.html
├── s02-{screen}.html
└── ...
```
## Screen File Template
```html
<!--
Screen: S-XX {Name from UI_SPEC}
CJX Stage: {from UI_SPEC}
FR Mapping: FR-XX
-->
<!DOCTYPE html>
<html lang="en">
<head>
<title>{Screen Name}</title>
<link rel="stylesheet" href="styles.css">
<link rel="stylesheet" href="components.css">
</head>
<body class="cjx-{stage}">
<div class="app-layout">
<nav class="sidebar hide-mobile">...</nav>
<main class="main-content" data-cjx-entrance>
<!-- Content matching UI_SPEC exactly -->
</main>
</div>
<script src="interactions.js"></script>
</body>
</html>
```
## Style Presets (Optional)
| Preset | Description |
|--------|-------------|
| `minimalist` | Clean, whitespace |
| `dashboard` | Data-dense |
| `dark` | Dark theme |
## Quality Gates
| Check | Requirement |
|-------|-------------|
| Spec Match | Every screen matches UI_SPEC |
| Layout | Uses `app-layout`, `main-content` |
| CJX | Body class + animations |
| Charts | Real SVG, no placeholders |
| Responsive | Mobile breakpoint works |
## GATE 3: Design Validation
Before proceeding to ipa-detail:
- [ ] User testing completed with 5+ users
- [ ] Critical issues addressed
- [ ] Design matches MVP scope
## Next Steps
After generation: run ipa-detail to generate API_SPEC and DB_DESIGN.

109
skills/ipa-detail/SKILL.md Normal file
View File

@@ -0,0 +1,109 @@
---
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.

103
skills/ipa-docs-split/SKILL.md Normal file
View File

@@ -0,0 +1,103 @@
---
name: ipa-docs-split
description: Split large IPA documentation files into modular folder structures when they exceed 500 lines. Use when an IPA doc becomes too large to navigate efficiently, when splitting API_SPEC, DB_DESIGN, or SRD into domain-based modules, or when docs exceed 500 lines. Trigger phrases: "split large ipa doc", "modularize api spec", "split docs into folders".
---
## Overview
Reorganizes large IPA documentation files (API_SPEC, DB_DESIGN, SRD) into modular folder structures when files exceed 500 lines. Preserves all traceability IDs and cross-references.
## When to Use
- A doc file exceeds 500 lines and is hard to navigate
- Splitting API_SPEC by domain group (auth, users, orders)
- Splitting DB_DESIGN by domain (user tables, order tables)
- Splitting SRD by feature area
## Don't Use When
- File is under 500 lines (no split needed)
- You want to modify content, not just reorganize structure
## Usage
```
# Split specific doc
ipa-docs-split API_SPEC
ipa-docs-split DB_DESIGN
ipa-docs-split SRD
# Auto-detect and split all large docs
ipa-docs-split
```
## Workflow
### Step 1: Analyze Document
1. Read target doc
2. Check line count: < 500 lines → skip; ≥ 500 lines → proceed
3. Identify sections by headers
### Step 2: Create Folder Structure
Create `docs/{DOC_NAME}/` with `README.md` and `index.md`.
### Step 3: Generate index.md
Extract matrix/overview:
- API_SPEC: Endpoint Matrix table
- DB_DESIGN: Table Matrix
- SRD: Requirements Matrix (FR-xx list)
### Step 4: Split Content
For each major section (## headers):
1. Create `{section-slug}.md`
2. Move section content
3. Add backlink to index.md
## Section Detection
### API_SPEC.md — split by API group
- `/auth/*` endpoints → `auth.md`
- `/users/*` endpoints → `users.md`
- `/orders/*` endpoints → `orders.md`
### DB_DESIGN.md — split by domain
- User tables → `users-tables.md`
- Order tables → `orders-tables.md`
### SRD.md — split by feature
- FR-01xx → `feature-auth.md`
- FR-02xx → `feature-orders.md`
## Output Structure
```
docs/
├── API_SPEC/
│ ├── README.md # Agent guide
│ ├── index.md # Endpoint matrix
│ ├── auth.md
│ ├── users.md
│ └── orders.md
```
## Traceability Preservation
- `index.md` contains full matrix with IDs
- Detail files preserve ID anchors: `### API-001: POST /auth/login {#API-001}`
- Cross-references remain valid: `See [FR-001](../SRD/index.md#FR-001)`
## Rollback
Original file backed up to: `docs/.backup/{DOC_NAME}.md.{timestamp}`
## Important
- Only split if file > 500 lines
- Always backup original before split
- Preserve all FR-xx, API-xx, D-xx IDs
- Update cross-references to new paths
- Does not modify code

99
skills/ipa-docs-sync/SKILL.md Normal file
View File

@@ -0,0 +1,99 @@
---
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

109
skills/ipa-docs/SKILL.md Normal file
View File

@@ -0,0 +1,109 @@
---
name: ipa-docs
description: IPA documentation sync specialist — tracks implementation status with symbols (pending/done/synced) across API_SPEC, DB_DESIGN, and UI_SPEC. Use when syncing docs after code implementation, verifying endpoint coverage, or keeping IPA docs accurate without full regeneration. Trigger phrases: "sync ipa docs", "update api spec after coding", "sync docs with implementation".
---
## Overview
Synchronizes IPA-generated documentation with actual implementation after coding is complete. Updates status tracking, schema changes, and table definitions while preserving traceability IDs and manual notes.
## When to Use
- After backend implementation to update endpoint and schema status
- When API routes or DB schema have changed
- After running a docs sync command in an IPA project
- When `docs/SRD.md` exists and implementation has progressed
## Don't Use When
- No IPA docs exist yet (run ipa-spec first)
- You want to regenerate docs from scratch (use ipa-init instead)
- Only planning phase — no implementation has happened yet
## IPA Documentation Structure
```
docs/
├── SRD.md # System Requirement Definition
├── UI_SPEC.md # Basic Design
├── API_SPEC.md # Detail Design (Interface)
└── DB_DESIGN.md # Detail Design (Database)
```
## Sync Workflow
### 1. API_SPEC.md Sync
Status update rules:
| Before | After | Condition |
|--------|-------|-----------|
| pending | done | Endpoint implemented in code |
| done | synced | Docs verified match code exactly |
| synced | done | Code changed, needs re-sync |
Steps:
1. Scan codebase for API routes/endpoints
2. Compare with Endpoint Matrix
3. Update status column
4. Update request/response schemas if changed
5. Preserve traceability lines (FR-xx, S-xx refs)
### 2. DB_DESIGN.md Sync
Steps:
1. Read actual schema (Drizzle, Prisma, raw SQL)
2. Compare with Table Definitions
3. Update table columns, types, constraints
4. Update ERD if structure changed
5. Preserve traceability lines (E-xx refs)
### 3. UI_SPEC.md Sync (if requested)
Steps:
1. Scan UI components in codebase
2. Update Screen Specifications
3. Preserve CJX section (personas, journey map)
4. Preserve Design System section
## Protected Sections
Never overwrite these manually-created sections:
| Doc | Protected Sections |
|-----|-------------------|
| SRD.md | All (source of truth) |
| UI_SPEC.md | CJX, Design System |
| API_SPEC.md | Traceability lines, Implementation Notes |
| DB_DESIGN.md | Traceability lines, Implementation Notes |
## Sync Report Format
```
## Docs Sync Report
### API_SPEC.md
- Status Updates:
- POST /auth/login: pending → done
- GET /users/:id: done → synced
- Schema Updates:
- Updated: GET /users/:id response (added `avatar` field)
### DB_DESIGN.md
- Table Updates:
- users: Added `avatar_url` column
```
## Traceability Validation
During sync, validate:
1. Every endpoint has FR-xx ref
2. Every screen has S-xx ref
3. Every table has E-xx ref
## Core Principles
- Update only what changed
- Preserve manual notes and comments
- Use incremental sync, not full regeneration
- Respect YAGNI/KISS/DRY

103
skills/ipa-fast/SKILL.md Normal file
View File

@@ -0,0 +1,103 @@
---
name: ipa-fast
description: Run the complete IPA workflow in one command with minimal prompts, skipping all validation gates. Use when experienced with IPA and project scope is well understood, for rapid prototyping with a known requirement, or when combining raw text, URL, and image references in one pass. Trigger phrases: "ipa fast mode", "full ipa in one command", "skip all gates and generate everything".
---
## Overview
Fast mode runs the complete IPA pipeline — lean analysis, spec, design, detail — in one command, skipping all gate prompts. Supports three input types individually or combined.
## When to Use
- Experienced with IPA workflow and gates
- Project scope is well understood and validated externally
- Rapid prototyping where throwaway docs are acceptable
- Combining multiple input references (text + URL + image)
## Don't Use When
- First time using IPA workflow
- Complex enterprise projects or multi-stakeholder environments
- User research is incomplete
- You want gate checkpoints between phases
## 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-fast "Build a task management app for remote teams"
# Raw requirement + URL reference
ipa-fast "Build a SaaS dashboard" @https://stripe.com/billing
# Raw requirement + image reference
ipa-fast "Build a dashboard" @./design-mockup.png
# All 3 inputs combined
ipa-fast "Build a FinOps dashboard" @https://stripe.com @./color-palette.png
# URL only (requirement inferred)
ipa-fast @https://linear.app
```
## Pipeline
```
ipa-fast "requirement" [@url] [@image]
↓
1. lean "requirement" --fast (GATE 1 skipped)
↓
2. ipa-spec "requirement" @url @image --fast (GATE 2 skipped)
→ Design System extracted from references
↓
3. ipa-design --fast (GATE 3 skipped)
→ Prototypes generated from Design System
↓
4. ipa-detail
↓
Output: All IPA docs generated
↓
Final: "Review generated docs. Ready to plan?"
```
## Execution Steps
### Step 1: Lean Analysis
Run lean with fast flag — skip GATE 1. Log warning: "GATE 1 (Scope Validation) skipped".
### Step 2: Spec Generation
Run ipa-spec with fast flag — skip GATE 2. Log warning: "GATE 2 (Spec Validation) skipped".
### Step 3: Design Generation
Run ipa-design with fast flag — skip GATE 3. Log warning: "GATE 3 (Design Validation) skipped".
### Step 4: Detail Design
Run ipa-detail to generate API_SPEC.md and DB_DESIGN.md.
### Step 5: Final Summary
```
IPA Fast Mode Complete
Generated docs:
- docs/SRD.md
- docs/UI_SPEC.md
- docs/API_SPEC.md
- docs/DB_DESIGN.md
- prototypes/html-mockups/
Skipped gates: GATE 1, GATE 2, GATE 3
Next steps:
1. Review generated docs for accuracy
2. Run ipa-validate to check traceability
3. Plan with docs and prototypes as context
```

109
skills/ipa-help/SKILL.md Normal file
View File

@@ -0,0 +1,109 @@
---
name: ipa-help
description: Display the IPA workflow quick reference cheatsheet with commands, warnings, tips, and workflow paths. Use when you need a summary of available IPA commands, want to understand the full pipeline at a glance, or need to share workflow guidance. Trigger phrases: "ipa help", "show ipa commands", "ipa cheatsheet".
---
## Overview
Displays the IPA workflow quick reference with all commands, critical warnings, tips, and workflow paths for different project scenarios.
## When to Use
- Need a summary of all IPA commands and their purpose
- Onboarding to the IPA workflow for the first time
- Want to verify the correct command sequence
- Sharing workflow guidance with collaborators
## Don't Use When
- You need to actually run a workflow step (use the specific skill instead)
## Output
Display the following cheatsheet:
```
IPA QUICK REFERENCE
───────────────────────────────────────────────────────
FAST MODE (Power Users)
ipa-fast "idea" Full workflow, no prompts
WARNING: Skips all gates — use only when confident
STEP-BY-STEP (Recommended)
lean "idea" → MVP analysis [GATE 1]
ipa-spec → SRD + UI_SPEC [GATE 2]
ipa-design → HTML mockups [GATE 3]
ipa-detail → API_SPEC + DB_DESIGN
plan → code → Implementation
UTILITIES
ipa-init Extract docs from existing code
ipa-import @file Import external SRS document
ipa-validate Check traceability matrix
ipa-docs-sync Sync docs with implementation
ipa-start Interactive wizard
───────────────────────────────────────────────────────
CRITICAL WARNINGS
1. PLANNING WITH CONTEXT
ALWAYS include docs + mockups when planning:
CORRECT: plan @docs/ @prototypes/html-mockups/
WRONG: plan "implement feature"
Why? Ensures:
- Traceability: FR-xx → S-xx → E-xx → T-xx
- Accurate UI: Code matches mockup exactly
- Design tokens: Colors, fonts, spacing applied
2. DOCS SYNC REQUIRES HUMAN REVIEW
After coding, run: ipa-docs-sync
REVIEW CHANGES before accepting
Never auto-approve without checking
3. GATE VALIDATION
GATE 1: After lean
- 3+ user interviews about problem
- Scope ≤ 3 phases
GATE 2: After ipa-spec
- Stakeholder reviewed SRD
- Priorities confirmed (P1/P2/P3)
GATE 3: After ipa-design
- 5+ user testing sessions
- Usability issues addressed
4. TRACEABILITY IDs
FR-xx → Functional Requirement (SRD)
S-xx → Screen (UI_SPEC)
E-xx → API Endpoint (API_SPEC)
T-xx → Database Table (DB_DESIGN)
Check with: ipa-validate
TIPS
First time? Run ipa-start for guided setup
Large docs? Split with: ipa-docs-split API_SPEC
External SRS? Import with: ipa-import @file.md
Check coverage: ipa-validate shows traceability matrix
WORKFLOWS
New Project (step-by-step):
lean → ipa-spec → ipa-design → ipa-detail → plan @docs/ @prototypes/
New Project (fast):
ipa-fast "idea" → plan @docs/ @prototypes/
Existing (no docs):
ipa-init → lean [feature] → plan @docs/
Existing (has docs):
lean [feature] → plan @docs/ → code → ipa-docs-sync
Import external:
ipa-import @srs.md → ipa-design → ipa-detail → plan
```

94
skills/ipa-import/SKILL.md Normal file
View File

@@ -0,0 +1,94 @@
---
name: ipa-import
description: Import external requirements documents (SRS, PRD, research reports) into the IPA documentation structure with proper IDs and traceability. Use when converting external specs from Gemini Deep Research, Perplexity, or manually written SRS files into IPA format. Trigger phrases: "import external srs", "convert requirements to ipa", "import requirements document".
---
## Overview
Reads external requirements documents (markdown, PDF, plain text) and converts them into IPA-standard documentation with proper traceability IDs (FR-xx, S-xx, E-xx, API-xx, D-xx). Runs ipa-validate automatically after import.
## When to Use
- External SRS or PRD document exists and needs IPA conversion
- Requirements come from an AI research tool or external stakeholder
- Merging external requirements into existing IPA docs
## Don't Use When
- No external document exists (start with lean + ipa-spec instead)
- The document is already in IPA format
## Usage
```
# Import from markdown file
ipa-import @path/to/external-srs.md
# Import from PDF (AI vision extraction)
ipa-import @path/to/requirements.pdf
# Import with specific focus
ipa-import @external.md --focus=api # Only API requirements
ipa-import @external.md --focus=ui # Only UI requirements
# Merge modes
ipa-import @external.md # Merge with existing (default)
ipa-import @external.md --replace # Replace existing (with backup)
ipa-import @external.md --append # Append only new requirements
```
## Workflow
### Step 1: Read External Document
Read external SRS file and analyze structure:
- Business requirements
- Functional requirements
- UI/UX specifications
- API requirements
- Data/Database requirements
- Non-functional requirements
### Step 2: Extract and Categorize
| External Content | IPA Doc |
|------------------|---------|
| Business requirements | `SRD.md` (FR-xx) |
| User stories | `SRD.md` (FR-xx) |
| UI mockup descriptions | `UI_SPEC.md` (S-xx) |
| API endpoints | `API_SPEC.md` (API-xx) |
| Data models | `DB_DESIGN.md` (D-xx) |
### Step 3: Generate IPA IDs
| Type | ID Format | Example |
|------|-----------|---------|
| Functional Requirement | FR-XXX | FR-001 |
| Screen | S-XX | S-01 |
| Entity | E-XX | E-01 |
| API Endpoint | API-XXX | API-001 |
| Database Table | D-XX | D-01 |
### Step 4: Generate IPA Docs
Create or update: SRD.md, UI_SPEC.md, API_SPEC.md, DB_DESIGN.md
### Step 5: Auto-Validate
Run ipa-validate automatically to check ID uniqueness and traceability links.
## Merge Behavior
1. Read existing IPA docs
2. Find max existing ID (e.g., FR-015)
3. Start new IDs from FR-016
4. Preserve existing content
5. Add new content at end
## Important
- Always note original source in generated docs
- Don't overwrite existing IDs in merge mode
- Always run ipa-validate after import
- Import is ~80% accurate — human review recommended
- Does not implement code

107
skills/ipa-init/SKILL.md Normal file
View File

@@ -0,0 +1,107 @@
---
name: ipa-init
description: Initialize IPA documentation by reverse-engineering an existing codebase that has no docs. Use when applying the IPA workflow to a running project, extracting API routes and DB schema from code, or generating a documentation baseline for legacy systems. Trigger phrases: "extract docs from code", "initialize ipa for existing project", "reverse engineer ipa docs".
---
## Overview
Generates IPA-standard documentation from an existing codebase with no docs. Scans code for API routes, DB schema, and UI screens, then infers SRD from business logic. Runs ipa-validate automatically after generation.
## When to Use
- Existing project has no IPA docs
- Existing project has partial docs that need enhancement
- Separate frontend/backend repos need combined docs
- Microservices architecture needs unified documentation baseline
## Don't Use When
- Starting a brand new project from scratch (use lean + ipa-spec)
- Implementation tasks are done and only sync is needed (use ipa-docs-sync)
## Supported Structures
```
# Monorepo
ipa-init
ipa-init ./my-project
# Separate FE/BE repos
ipa-init ./frontend ./backend
# Microservices
ipa-init ./user-service ./order-service ./payment-service
```
## Workflow
### Step 1: Detect Tech Stack
Scan for:
- `package.json` → Node.js ecosystem
- `requirements.txt` / `pyproject.toml` → Python
- `go.mod` → Go
- `Cargo.toml` → Rust
Auto-detect framework, ORM, and UI library. Save to `docs/tech-stack.md` if not exists.
### Step 2: Extract API Routes → API_SPEC.md
Scan for route definitions across frameworks (Express, NestJS, FastAPI, etc.).
### Step 3: Extract DB Schema → DB_DESIGN.md
Scan for schema definitions (Drizzle, Prisma, raw SQL, etc.).
### Step 4: Extract UI Screens → UI_SPEC.md
Scan for page components (Next.js `app/page.tsx`, React routes, etc.).
### Step 5: Infer SRD.md
From collected data, infer:
- Entities (E-xx): From DB tables
- Features (FR-xx): From API endpoints grouped by resource
- Screens (S-xx): From UI pages
### Step 6: Auto-Validate
Run ipa-validate logic automatically.
## After Generation
```
ipa-init complete
↓
Auto-validation ran
↓
Review generated docs and validation report
↓
Enhance manually:
- Add business context to SRD
- Add CJX to UI_SPEC
- Fix any validation warnings
↓
Ready for:
- lean [new feature] to extend
- plan to create tasks
```
## Usage
```
# Initialize IPA docs
ipa-init
# Force regenerate (overwrite existing)
ipa-init --force
```
## Important Notes
1. Review generated docs — auto-inference is not perfect
2. Add business context — code doesn't capture "why"
3. Enhance CJX manually — user journeys need human input
4. SRD business rules need domain knowledge
Does not implement code — only generates documentation.

112
skills/ipa-mockup-analyze/SKILL.md Normal file
View File

@@ -0,0 +1,112 @@
---
name: ipa-mockup-analyze
description: Extract design specifications from HTML mockups using AI vision and CSS parsing to generate a UI_DESIGN_SPEC.md with design tokens, component mapping, and responsive specs. Use when converting visual prototypes into implementation-ready specs, analyzing HTML mockups for design system extraction, or preparing tech-stack-specific component mappings. Trigger phrases: "analyze html mockups", "extract design tokens from prototypes", "generate ui design spec from mockups".
---
## Overview
Generates `docs/UI_DESIGN_SPEC.md` from HTML mockups using a hybrid approach: AI vision analysis for visual patterns plus HTML/CSS parsing for exact values. Output serves as single source of truth for UI implementation.
## When to Use
- HTML/CSS mockups exist and need to be converted to implementation specs
- Design tokens need to be extracted for a component library
- Tech-stack-specific component mappings are needed (e.g., shadcn/ui, Tailwind)
- Preparing accurate implementation tasks from visual designs
## Don't Use When
- No HTML mockups exist yet (run ipa-design first)
- Only text-based specifications are needed
## Input
Default mockup directory: `docs/UI-new-mock/` or `docs/prototypes/`
Custom: pass path as argument.
## Workflow
### Step 1: Discover Mockup Files
Find all HTML files in mockup directory.
### Step 2: Screenshot Each Mockup
Capture visual representation of each HTML file.
### Step 3: AI Vision Analysis
For each screenshot, extract:
1. Color Palette (hex values)
2. Typography (fonts, sizes, weights)
3. Spacing System (padding, margin, gap)
4. Border and Effects (radius, shadows, blur)
5. Component Patterns (buttons, inputs, cards)
6. Layout Structure (grid, container widths)
7. Responsive Behavior (breakpoint changes)
### Step 4: HTML/CSS Parsing (Verification)
Parse HTML/CSS to verify AI vision analysis:
- Extract CSS custom properties (`--color-*`, `--font-*`, etc.)
- Extract Tailwind config if present
- Priority: CSS values > AI vision estimates (CSS is ground truth)
### Step 5: Component Mapping
Map HTML patterns to target tech stack:
- Which component library component?
- Which utility classes?
- Custom component needed?
### Step 6: Generate UI_DESIGN_SPEC.md
Write `docs/UI_DESIGN_SPEC.md` with design tokens, component mapping, and responsive specs.
## Output Template
```markdown
# UI Design Specification
**Generated:** {date}
**Source:** {mockup-directory}
**Screens Analyzed:** {count}
## Design Tokens
### Colors
| Token | Hex | Tailwind | Usage | Mockup Source |
|-------|-----|----------|-------|---------------|
| primary | #2563EB | blue-600 | Primary CTA, links | 01-login.html line 12 |
### Typography
| Element | Font | Size | Weight | Tailwind |
|---------|------|------|--------|----------|
| H1 | Outfit | 48px | 700 | text-5xl font-bold |
### Spacing System
| Token | Value | Tailwind | Usage |
|-------|-------|----------|-------|
| md | 16px | p-4 | Card padding |
## Component Mapping
### 01-login-screen.html
**HTML Structure:** [Extracted HTML]
**Tech Stack Implementation:** [Framework-specific code]
## Quality Checklist
- [ ] All colors extracted
- [ ] All fonts identified
- [ ] Spacing system consistent
- [ ] Components mapped
- [ ] Responsive tested
```
## Notes
- AI vision provides visual pattern extraction
- HTML/CSS parsing provides exact values (ground truth)
- Hybrid approach ensures accuracy
- Does not modify or create code files

125
skills/ipa-planner/SKILL.md Normal file
View File

@@ -0,0 +1,125 @@
---
name: ipa-planner
description: IPA-aware planning that enriches implementation plans with traceability references (FR-xx, S-xx, E-xx), TDD detection for logic-heavy tasks, and design context from @path mockup references. Use when creating plans in projects with IPA docs, when tasks need to reference SRD features and API specs, or when design mockups should inform implementation tasks. Trigger phrases: "create ipa plan", "plan with traceability", "ipa-aware implementation plan".
---
## Overview
Extends the planning workflow with IPA documentation awareness. Reads SRD, UI_SPEC, API_SPEC, and DB_DESIGN to generate tasks that reference specific doc sections. Falls back to light mode (no traceability) when IPA docs are absent.
## When to Use
- `docs/SRD.md` exists in the project
- Running a plan command in an IPA project
- Tasks need FR-xx, S-xx, E-xx traceability references
- Design mockups via @path syntax are included in the plan command
## Don't Use When
- No IPA docs exist and a plain task breakdown is sufficient
## IPA Docs Check
```
docs/
├── SRD.md # System Requirements (FR-xx, S-xx, E-xx)
├── UI_SPEC.md # UX Specification (screens, CJX)
├── API_SPEC.md # Interface contracts
└── DB_DESIGN.md # Database design
```
## Design Context via @path
When plan command includes `@path` references:
1. Activate ipa-context-aware-planning skill
2. Parse and analyze design files (HTML/CSS/JS)
3. Generate `design-analysis-report.md` in plan folder
4. Use report to create UI tasks with 100% match requirements
## Light Mode (No IPA Docs)
When IPA docs are missing:
- Skip traceability rules (FR-xx)
- Still detect project type (FE/BE)
- Still create phase folders and layer files
- Use "Self-Contained" instead of docs refs
- Add warning: "LIGHT MODE: No traceability" to plan header
## Task Generation Rules
1. Granularity: Break down into atomic tasks (S/M size)
2. Dependencies: Identify blockers
3. Traceability: Every task must reference specific doc sections
## TDD Auto-Detection
Scan FR-xx and task requirements for logic-heavy keywords:
- "calculate", "compute", "formula", "algorithm"
- "validate", "verify", "check rules"
- "transform", "parse", "convert"
- "financial", "tax", "price", "discount"
- "permission", "authorization", "policy"
When detected: append `[TDD]` to task title, add TDD protocol block.
## Task Template
```markdown
### Task [N]: [Task Name] [S/M/L]
**Refs:**
- Feature: docs/SRD.md#FR-xx
- API: docs/API_SPEC.md#section
- UI: docs/UI_SPEC.md#S-xx
- DB: docs/DB_DESIGN.md#E-xx
**Files:**
- `src/path/file.ts`
**Acceptance:**
- [ ] Matches contract in docs/API_SPEC.md
- [ ] Implements FR-xx from docs/SRD.md
- [ ] Visual 100% match to design (if UI task)
```
## Plan File Frontmatter
```yaml
---
title: "{Brief title}"
description: "{One sentence for card preview}"
status: pending
priority: P2
effort: {sum of phases}
tags: [relevant, tags]
created: {YYYY-MM-DD}
---
```
## IPA Docs Summary in plan.md
```markdown
## IPA Docs Reference
| Doc | Status | Key Items |
|-----|--------|-----------|
| SRD.md | Read | FR-01 to FR-10, S-01 to S-08 |
| UI_SPEC.md | Read | 8 screens, CJX defined |
| API_SPEC.md | Read | 15 endpoints |
| DB_DESIGN.md | Read | 6 tables |
```
## After Each Phase
Add docs sync reminder:
```markdown
## After Implementation
- [ ] Run ipa-docs-sync to update IPA docs
- [ ] Verify API_SPEC.md status: pending → done
```
## Core Principles
YAGNI, KISS, DRY — reference docs, never duplicate content.
Does not implement code — only creates plans.

125
skills/ipa-spec/SKILL.md Normal file
View File

@@ -0,0 +1,125 @@
---
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
```

96
skills/ipa-srd/SKILL.md Normal file
View File

@@ -0,0 +1,96 @@
---
name: ipa-srd
description: Generate SRD.md only — the System Requirement Definition following IPA standard with 15 sections. Use when granular control over requirement generation is needed, when only the SRD needs to be regenerated without touching UI_SPEC, or when working as a Business Analyst generating structured requirements. Trigger phrases: "generate srd only", "create system requirement definition", "generate srd without ui spec".
---
> TIP: Use ipa-spec instead to generate both SRD.md + UI_SPEC.md in one step.
>
> This skill is for granular control when you only need SRD.md.
## Overview
Generate System Requirement Definition (SRD) following IPA (Information-technology Promotion Agency, Japan) standard from raw requirements. Output: `docs/SRD.md`.
## When to Use
- Only the SRD needs to be created or regenerated
- Granular control is needed over requirement documentation
- Iterating on requirements without changing UI spec
- Acting as Business Analyst generating structured requirements
## Don't Use When
- Both SRD and UI_SPEC are needed (use ipa-spec)
- Existing SRD needs only minor updates (edit directly)
## Input
Read from arguments, then `docs/requirements.md`, then `docs/PRD.md`, then ask user.
## Role
Business Analyst following IPA guidelines:
- Requirement Definition (要件定義)
- Ensure traceability: FR ↔ Screen ↔ Flow ↔ Entity
## Output: docs/SRD.md (15 Sections)
```markdown
# System Requirement Definition (SRD)
## 1. System Name
## 2. System Objectives
## 3. User Roles (RBAC)
| Role ID | Role Name | Description | Permissions |
## 4. Feature List
| FR-ID | Feature Name | Description | Priority | Screens |
## 5. Screen List
| S-ID | Screen Name | Description | Features |
## 6. Batch List
| B-ID | Batch Name | Description | Schedule |
## 7. Report List
| R-ID | Report Name | Description | Format |
## 8. Integration List (I/F)
| IF-ID | Name | Type | Description |
## 9. Entity List & ER Diagram
| E-ID | Entity Name | Description |
## 10. Screen Flow
[Mermaid flowchart]
## 11. Main Business Flows
## 12. Use Cases
| UC-ID | Name | Actor | Precondition | Flow | Postcondition |
## 13. Non-Functional Requirements (NFR)
## 14. Key Decisions
| D-ID | Decision | Context | Alternatives | Chosen | Rationale |
## 15. IPA Checklist
- [ ] All features covered
- [ ] ID consistency (FR-xx, S-xx, E-xx, D-xx)
- [ ] ERD + Screen Flow present
- [ ] NFR defined
- [ ] Key decisions documented
- [ ] Acceptance criteria defined
```
## Rules
- No fabrication: only document what is in requirements
- Consistent IDs: FR-xx, S-xx, B-xx, R-xx, IF-xx, E-xx
- Traceability: FR ↔ Screen ↔ Flow ↔ Entity must trace back
## After Generation
1. Save to `docs/SRD.md`
2. Ask user to review
3. Proceed to ipa-bd for Basic Design, or ipa-spec for SRD + UI_SPEC together
Does not implement code — only generates documentation.

173
skills/ipa-start/SKILL.md Normal file
View File

@@ -0,0 +1,173 @@
---
name: ipa-start
description: Interactive wizard that guides users through selecting the correct IPA workflow path based on their project situation. Use when starting the IPA process for the first time, when unsure which IPA command to run first, or when onboarding to the workflow. Trigger phrases: "start ipa workflow", "ipa wizard", "help me start ipa".
---
## Overview
Interactive wizard that detects the user's project situation and provides a tailored workflow path with specific next commands and critical warnings. Retains full wizard behavior with user questions and branching output.
## When to Use
- First time using IPA workflow
- Unsure which IPA command to run first
- Onboarding collaborators to the IPA process
- Need a reminder of the correct path for a specific scenario
## Don't Use When
- Already familiar with IPA and know the next command to run
- Looking for a command reference (use ipa-help instead)
## Flow
### Step 1: Project Type Detection
Ask user which scenario applies:
```
What type of project are you starting?
1. New project — Building from scratch
→ Full workflow: lean → ipa-spec → ipa-design → ipa-detail
2. Existing project (no IPA docs) — Code exists, need docs
→ Extract docs: ipa-init → lean [feature] → plan
3. Existing project (has IPA docs) — Add feature/improvement
→ Feature mode: lean [feature] → plan → code
4. Import external SRS — Have requirements document
→ Import: ipa-import @path/to/srs.md → continue workflow
```
### Step 2: Workflow Guide
Based on selection, output next steps with warnings.
---
## Output for New Project
```
## New Project Workflow
Your Path:
lean "your idea" ← Start here
↓ [GATE 1: Scope]
ipa-spec → SRD.md + UI_SPEC.md
↓ [GATE 2: Spec]
ipa-design → HTML mockups
↓ [GATE 3: Design]
ipa-detail → API_SPEC.md + DB_DESIGN.md
↓
plan @docs/ @prototypes/ → Implementation plan
IMPORTANT TIPS
1. GATE VALIDATION (Don't skip on first project)
- GATE 1: Validate scope with 3+ user interviews
- GATE 2: Get stakeholder sign-off on SRD
- GATE 3: Test mockups with 5+ users
2. PLANNING WITH CONTEXT
Always include design context when planning:
CORRECT: plan @docs/ @prototypes/html-mockups/
WRONG: plan "implement feature"
3. DOCS SYNC
After coding, run ipa-docs-sync
Review changes before accepting
Alternative: Fast Mode
If experienced: ipa-fast "your idea" (skips all gates)
Next Command:
lean "describe your idea here"
```
---
## Output for Existing Project (No Docs)
```
## Existing Project (No Docs) Workflow
Your Path:
ipa-init ← Start here
↓
Review generated docs → Fix inaccuracies
↓
lean "feature idea" → Feature analysis
↓
plan @docs/ → Implementation plan
IMPORTANT TIPS
1. Review generated docs — ipa-init infers from code, may not be 100% accurate
2. Always include docs in plan: plan [feature] @docs/
3. Check traceability after changes: ipa-validate
Next Command:
ipa-init
```
---
## Output for Existing Project (Has Docs)
```
## Existing Project (Has Docs) Workflow
Your Path:
lean "feature idea" ← Start here
↓
plan @docs/ → Implementation plan
↓
code → Implementation
↓
ipa-docs-sync → Update docs
IMPORTANT TIPS
1. lean auto-detects existing docs and runs in Feature Mode
2. Always include docs and prototypes in plan command
3. If adding new screens, run ipa-design first
Next Command:
lean "describe your feature idea"
```
---
## Output for Import External SRS
```
## Import External SRS Workflow
Your Path:
ipa-import @path/to/srs.md ← Start here
↓
Review converted docs → Fix format issues
↓
[GATE 2: Verify conversion]
↓
ipa-design → Create mockups
↓
Continue normal workflow...
SUPPORTED FORMATS: Markdown, PDF, Plain text
REVIEW CONVERSION: External SRS may not map perfectly to IPA format.
Review FR-xx IDs and S-xx mappings.
Next Command:
ipa-import @path/to/your-srs-file.md
```
---
## Quick Reference Reminder
After completing wizard, suggest:
```
Need help anytime? Run ipa-help for quick reference.
```

139
skills/ipa-validate/SKILL.md Normal file
View File

@@ -0,0 +1,139 @@
---
name: ipa-validate
description: Validate IPA documentation consistency, traceability, and completeness — checks ID cross-references, coverage gaps, and gate status across all four IPA docs. Use after manually editing docs, before planning, or after running ipa-docs-sync to verify completeness. Trigger phrases: "validate ipa docs", "check ipa traceability", "run ipa validation".
---
<HARD-GATE>Do NOT validate until API_SPEC.md AND DB_DESIGN.md exist. Run ipa-detail first.</HARD-GATE>
## Overview
Runs IPA validation across SRD, UI_SPEC, API_SPEC, and DB_DESIGN to check ID consistency, cross-references, traceability chain, and coverage gaps. Outputs a structured report with errors, warnings, and recommendations.
## When to Use
- After manually editing any IPA doc
- Before planning to ensure docs are valid
- After ipa-docs-sync to verify sync completeness
- As a quality gate before implementation
## Don't Use When
- IPA docs do not yet exist (run ipa-spec and ipa-detail first)
- After ipa-all or ipa-init — those run validation automatically
## Prerequisites
All four IPA docs must exist:
- `docs/SRD.md`
- `docs/UI_SPEC.md`
- `docs/API_SPEC.md`
- `docs/DB_DESIGN.md`
## Workflow
### Step 1: Check Docs Exist
Verify all required IPA docs are present. Report missing docs and stop if any are absent.
### Step 2: Extract IDs from SRD
Parse tables for:
- FR-xx (Feature List)
- S-xx (Screen List)
- E-xx (Entity List)
- B-xx (Batch List)
- R-xx (Report List)
- IF-xx (Integration List)
### Step 3: Validate Cross-References
Check each doc references valid SRD IDs:
- UI_SPEC.md → S-xx refs
- API_SPEC.md → FR-xx, S-xx refs
- DB_DESIGN.md → E-xx refs
### Step 4: Check Status Tracking
Verify API_SPEC.md Endpoint Matrix has status column with valid values: pending, done, synced.
### Step 5: Build Traceability Matrix
Map each FR-xx to its implementations across Screen, Endpoint, and Table.
### Step 6: Validate Gates
Check gate completion status (soft enforcement):
- GATE 1: Scope validation from lean
- GATE 2: Spec validation from ipa-spec
- GATE 3: Design validation from ipa-design
### Step 7: Generate Report
## Output
```markdown
## IPA Validation Report
### Summary
- Total Features (FR): X
- Total Screens (S): X
- Total Entities (E): X
- Total Endpoints: X
- Total Tables (T): X
- Errors: X
- Warnings: X
- Status: PASS / FAIL
### Traceability Matrix
| FR ID | Screen | API Endpoint | DB Table | Status |
|-------|--------|--------------|----------|--------|
| FR-01 | S-01 | E-01 | T-01 | Full |
| FR-02 | S-02 | E-02, E-03 | T-01 | Full |
| FR-03 | S-03 | — | — | Partial|
| FR-04 | — | — | — | Missing|
### Coverage Summary
- Full coverage: 2 (50%)
- Partial coverage: 1 (25%)
- Missing coverage: 1 (25%)
### Gaps
- FR-03: Missing API endpoint mapping
- FR-04: Not mapped to any screen/API/DB
### Errors (blocking)
### Warnings (non-blocking)
### Recommendations
```
## Coverage Status
| Status | Meaning |
|--------|---------|
| Full | FR mapped to Screen + Endpoint + Table |
| Partial | FR mapped to some but not all components |
| Missing | FR not mapped to any component |
## Bi-directional Traceability
- Forward: FR-01 → S-01 → Endpoint → Table (every requirement has implementation)
- Backward: Table → Endpoint → S-01 → FR-01 (every implementation traces to a requirement)
- Orphan detection for both directions
## Usage
```
# After manual edits
ipa-validate
# Before planning
ipa-validate
plan
# After sync
ipa-docs-sync
ipa-validate
```
Does not modify docs — only validates.

63
skills/ipa-validator/SKILL.md Normal file
View File

@@ -0,0 +1,63 @@
---
name: ipa-validator
description: Core IPA validation engine — checks documentation consistency, ID cross-references, and traceability chain across SRD, UI_SPEC, API_SPEC, and DB_DESIGN. Activated automatically by ipa-validate, ipa-all, and ipa-init. Trigger phrases: "validate ipa documentation", "check id consistency", "ipa traceability check".
---
## Overview
Core validation logic for IPA documentation. Validates ID consistency, cross-reference integrity, status tracking, and traceability chain completeness. Used by ipa-validate, ipa-all, and ipa-init internally.
## When to Use
- Invoked automatically by ipa-validate, ipa-all, ipa-init
- When explicitly checking IPA doc validity
- After generating or editing any IPA document
## Don't Use When
- IPA docs do not yet exist
- Only a quick command reference is needed (use ipa-help)
## Required Docs
- `docs/SRD.md` — System Requirement Definition
- `docs/UI_SPEC.md` — UX Specification (Basic Design)
- `docs/API_SPEC.md` — Interface Specification (Detail Design)
- `docs/DB_DESIGN.md` — Database Design (Detail Design)
## Validation Rules
1. **Docs Exist** — All four required IPA docs present
2. **ID Extraction** — Parse FR-xx, S-xx, E-xx from SRD tables
3. **Cross-Reference Validation** — Every ID referenced in other docs must exist in SRD
4. **Status Tracking** — API_SPEC Endpoint Matrix must have valid status values
5. **Traceability Chain** — Each FR-xx must map to Screen + Endpoint + Table
6. **Orphan Detection** — IDs in detail docs not referenced in SRD indicate scope creep
## Workflow
1. Check docs exist — stop and report if any missing
2. Extract IDs — parse all ID types from SRD
3. Validate refs — check cross-references in UI_SPEC, API_SPEC, DB_DESIGN
4. Check status — verify Endpoint Matrix status column
5. Generate report — output validation results with counts, gaps, and recommendations
## Output
Validation report with:
- ID consistency check result
- Traceability chain check result
- Cross-reference validation result
- Status tracking validation result
- Recommendations for fixing gaps
## Usage
```
# Run validation via ipa-validate
ipa-validate
# Or invoke directly
"Validate IPA docs"
"Check IPA traceability"
```

131
skills/lean-analyst/SKILL.md Normal file
View File

@@ -0,0 +1,131 @@
---
name: lean-analyst
description: Lean Software Development methodology framework — provides MVP definition criteria, feature prioritization matrix, assumption validation methods, and phase breakdown rules. Activated automatically by lean, lean-user-research, and lean-analyze-usage. Trigger phrases: "lean methodology", "mvp framework", "feature prioritization lean".
---
## Overview
Provides Lean Software Development methodology for analyzing ideas and defining MVPs. Core reference for the lean, lean-user-research, and lean-analyze-usage skills.
## When to Use
- Invoked automatically during lean analysis
- When applying lean methodology to MVP definition
- When prioritizing features using value vs effort matrix
- When planning phase breakdown for a project
## Don't Use When
- IPA documentation already exists and implementation is ready to begin
- Only a quick command reference is needed
## The 7 Lean Principles (Mary Poppendieck)
| # | Principle | Application |
|---|-----------|-------------|
| 1 | Eliminate Waste | Only build features with proven user value |
| 2 | Amplify Learning | Validate assumptions early, iterate fast |
| 3 | Decide as Late as Possible | Keep options open until necessary |
| 4 | Deliver as Fast as Possible | Smallest valuable increment first |
| 5 | Empower the Team | Trust team decisions |
| 6 | Build Integrity In | Quality from start |
| 7 | See the Whole | Optimize whole system, not parts |
## 7 Wastes in Software Development
| Waste | How to Eliminate |
|-------|------------------|
| Partially Done Work | Smaller batches, complete before starting new |
| Extra Features | Validate need before building |
| Relearning | Document decisions (D-xx in SRD) |
| Handoffs | Cross-functional teams |
| Task Switching | Focus on one thing at a time |
| Delays | Remove blockers proactively |
| Defects | Quality built in, early testing |
## MVP Definition
```
MVP = Minimum + Viable + Product
Minimum: Smallest feature set
Viable: Actually solves the problem
Product: Can be used by real users
```
MVP Checklist:
- [ ] Solves a real user problem
- [ ] Has clear success metrics
- [ ] Can be built in reasonable time
- [ ] Assumptions are identified
- [ ] Validation plan exists
## Feature Prioritization
| Priority | Criteria | Action |
|----------|----------|--------|
| P1 | Core value, must have for launch | Build in MVP |
| P2 | Important, enhances value | Build after MVP validation |
| P3 | Nice to have | Defer, validate need first |
| P4 | Future consideration | Document, don't build |
## Assumption Validation Methods
| Type | Example | How to Validate |
|------|---------|-----------------|
| Problem | Users have this pain | User interviews |
| Solution | Our approach works | Prototype testing |
| Market | People will pay | Landing page test |
| Technical | We can build it | Spike/POC |
## Phase Breakdown Rules
| Features | Recommended Phases |
|----------|-------------------|
| 1-3 P1 features | 1 phase |
| 4-6 P1 features | 2 phases |
| 7+ P1 features | 3+ phases (consider re-scoping) |
## Lean → IPA Mapping
| Lean Output | IPA Input |
|-------------|-----------|
| Problem Statement | SRD Section 2 (Objectives) |
| MVP Features | SRD Section 4 (Feature List) |
| Target Users | SRD Section 3 (User Roles) |
| Assumptions | SRD Section 14 (Key Decisions) |
| Out of Scope | SRD Section 2 (exclusions) |
## Data Analysis Integration
### Pre-Build (User Research)
| Method | When to Use |
|--------|-------------|
| Persona Development | Before lean |
| Journey Mapping | Before ipa-bd |
| Competitor Analysis | Before MVP definition |
### Post-Build (Usage Analytics)
| Method | When to Use |
|--------|-------------|
| Behavioral Analysis | After launch |
| Funnel Analysis | Optimization phase |
| Cohort Analysis | Growth phase |
## Workflow Integration
```
lean-user-research → docs/USER_RESEARCH.md
↓
lean → MVP definition (data-informed)
↓
ipa-bd → UI_SPEC.md (with design rationale)
↓
Launch → Collect usage data
↓
lean-analyze-usage → Improvement insights
↓
lean [improvement] → Next iteration
```

115
skills/lean-analyze-usage/SKILL.md Normal file
View File

@@ -0,0 +1,115 @@
---
name: lean-analyze-usage
description: Analyze post-launch usage data to generate improvement recommendations with prioritized action items. Use after a product has launched and usage data is available, when identifying feature adoption gaps or funnel drop-offs, or when planning the next iteration based on real user behavior. Trigger phrases: "analyze usage data", "post-launch analysis", "lean usage analysis".
---
## Overview
Generates a usage analysis report from analytics data (CSV or manual input) to inform the next product iteration. Outputs `plans/reports/usage-analysis-{date}.md` with findings, funnel analysis, retention data, and prioritized recommendations.
## When to Use
- Product has launched and 30+ days of usage data are available
- Identifying which features are underused or causing drop-off
- Planning the next improvement cycle based on real behavior
- Presenting data-driven recommendations to stakeholders
## Don't Use When
- Product has not launched yet (use lean-user-research instead)
- No usage data is available
## Input
Supported:
- CSV file path (exported from GA, Mixpanel, Amplitude, etc.)
- "manual" (guided input via questions)
## Workflow
### Step 1: Collect Data
If CSV provided: parse user_id, event, timestamp, properties.
If "manual": ask for:
- Total users (DAU/WAU/MAU)
- Key events (signups, activations, feature usage)
- Funnels (conversion rates)
- Retention (D1, D7, D30)
### Step 2: Analyze Patterns
- Feature usage: most/least used features, power vs casual users
- Drop-off analysis: where users abandon flows, conversion per step
- Retention: return rates after 1/7/30 days, cohort quality
- Correlations: features correlated with retention, acquisition source vs conversion
### Step 3: Generate Report
```markdown
# Usage Analysis Report
**Period:** {start} to {end}
**Generated:** {date}
## Executive Summary
**Key Findings:**
1. Finding 1 (Impact: HIGH)
2. Finding 2 (Impact: MEDIUM)
**Top Opportunity:** [Highest impact improvement]
## Metrics Overview
| Metric | Value | Benchmark | Status |
|--------|-------|-----------|--------|
| MAU | X | 1,000+ | pass/warn |
| Signup → Activation | X% | 40%+ | pass/warn |
| D7 Retention | X% | 20%+ | pass/warn |
## Feature Adoption
| Feature | Users | % of Total | Trend |
|---------|-------|------------|-------|
## Funnel Analysis
| Step | Users | Conversion | Drop-off |
|------|-------|------------|----------|
## Cohort Retention
| Source | Users | D1 | D7 | D30 | Quality |
## Recommendations
### P0 (Do First)
**1. [Issue Title]**
- Issue: [Problem]
- Root Cause: [Why]
- Solution: [Fix]
- Expected Impact: [Metric improvement]
### P1 (Medium Priority)
### P2 (Low Priority)
## Next Steps
1. Review with team
2. Create improvement plan: lean [improvement]
3. Implement P0 recommendations
4. Re-analyze in 30 days
## Data Sources
- Platform: {name}
- Date Range: {range}
- Limitations: {data quality notes}
```
## Integration
```
Launch MVP
↓
Collect usage data (30+ days)
↓
lean-analyze-usage → plans/reports/usage-analysis-{date}.md
↓
lean [improvement] → Next iteration
↓
plan → Implement improvements
```

117
skills/lean-user-research/SKILL.md Normal file
View File

@@ -0,0 +1,117 @@
---
name: lean-user-research
description: Generate user research documentation — personas, customer journey maps, and competitor landscape — before MVP definition. Runs BEFORE lean and IPA stages. Use when defining target users and their pain points, mapping the customer journey to inform UI design, or researching competitors before committing to an MVP scope. Trigger phrases: "user research", "create personas", "customer journey map".
---
## Overview
Generates `docs/USER_RESEARCH.md` with 2-3 user personas and a customer journey map to inform lean MVP definition and UI specification design rationale. Runs before lean for data-informed product decisions.
## When to Use
- Defining target users before MVP scoping
- Informing design decisions with empathy-driven research
- Mapping customer journey stages to planned screens
- Researching competitors before committing to product direction
## Don't Use When
- User research already exists in `docs/USER_RESEARCH.md`
- Product is already in post-launch iteration phase (use lean-analyze-usage)
## Input
Examples:
- "SaaS product managers struggling with tool fragmentation"
- "Small business owners managing inventory manually"
## Workflow
### Step 1: Clarify Context
Ask user:
- Who is the target user? (role, demographics)
- What problem are they experiencing?
- What do they currently use?
- What constraints do they have?
### Step 2: Research
If needed: search for competitor analysis and industry trends, analyze competitor screenshots.
### Step 3: Generate Personas (2-3)
```markdown
### Persona 1: [Name + Archetype]
**Demographics:**
- Age: [range]
- Role: [job title]
- Location: [geography]
**Behaviors:** [Key activities, tool patterns]
**Goals:** [Primary, Secondary]
**Pain Points:** [Frustration 1, Frustration 2]
**Quote:** "[Mindset statement]"
**Tech Savviness:** Low/Medium/High
```
### Step 4: Map Customer Journey (5 Stages)
For primary persona:
```markdown
### Stage 1: Discovery
**Touchpoint:** [Where they encounter product]
**Emotion:** [Feeling]
**Actions:** [What they do]
**Pain Points:** [Frustrations]
**Opportunities:** [Improvements]
**Design Implications:** [UI/UX decisions]
```
Stages: Discovery → Onboarding → Usage → Retention → Advocacy
### Step 5: Output docs/USER_RESEARCH.md
```markdown
# User Research
**Generated:** {date}
**Context:** {problem-space}
## Executive Summary
**Target Users:** [Description]
**Key Insights:** [Insight 1, Insight 2]
## Personas
[Persona 1]
[Persona 2]
## Customer Journey Map
[Journey for primary persona]
## Competitor Landscape
| Competitor | Features | Strengths | Weaknesses | Differentiation |
## Assumptions to Validate
- [ ] Assumption 1 (validate via...)
- [ ] Assumption 2 (validate via...)
## Next Steps
1. Use personas in lean MVP definition
2. Map journey stages to screens in ipa-bd
3. Validate assumptions via interviews/testing
```
## Integration
```
lean-user-research "target users"
↓
docs/USER_RESEARCH.md
↓
lean → reads USER_RESEARCH.md → data-informed MVP
↓
ipa-bd → UI_SPEC.md (with design rationale from personas)
```

161
skills/lean/SKILL.md Normal file
View File

@@ -0,0 +1,161 @@
---
name: lean
description: Lean Software Development analysis — defines MVP scope for new projects or analyzes improvement opportunities for existing ones. Runs BEFORE IPA stages. Use when starting a new idea that needs MVP definition and scope validation, when analyzing a feature improvement against an existing system, or when eliminating waste before committing to full IPA documentation. Trigger phrases: "lean analysis", "define mvp", "lean feature analysis".
---
## Flags
- `--fast`: Skip GATE 1 prompt (not recommended for new projects)
## Overview
Lean Software Development analyst combining Product Owner vision with Data Analyst rigor. Automatically detects context: MVP definition mode (no docs) or feature improvement mode (docs exist).
## When to Use
- Starting a new project idea that needs MVP scoping
- Analyzing a feature improvement against an existing system
- Validating scope before committing to IPA documentation
- Eliminating waste and surfacing assumptions before building
## Don't Use When
- IPA docs already exist and you are ready to implement (go straight to plan)
- Design or detail work is already complete
## Mode Detection
1. **No docs exist** → MVP Definition Mode
- Define core problem
- Identify MVP features
- List assumptions to validate
2. **docs/SRD.md exists** → Feature Improvement Mode
- Read existing system docs
- Analyze current state
- Suggest specific improvements
## Core Principles (Lean Software Development)
| Principle | Application |
|-----------|-------------|
| Eliminate Waste | Only features with clear user value |
| Amplify Learning | Validate assumptions early |
| Decide Late | Keep options open until necessary |
| Deliver Fast | Smallest valuable increment first |
| Build Integrity In | Quality from start |
| See The Whole | Consider full user journey |
## Workflow
### Phase 1: Context Understanding
Check for existing docs (SRD.md, API_SPEC.md, UI_SPEC.md). Read if present; proceed with MVP definition if absent.
### Phase 2: Discovery
Clarify with user:
- Who is the target user?
- What problem are we solving?
- What does success look like?
- What constraints exist?
### Phase 3: Analysis
MVP Mode: define core problem, minimum features, assumptions, explicit out-of-scope items.
Feature Mode: analyze current capabilities, improvement opportunities, impact vs effort, prioritized changes.
### Phase 4: Research (if needed)
Search for market/competitor analysis, technical feasibility, external package research, mockup analysis.
### Phase 5: Explore Alternatives
For significant decisions, present 2-3 viable approaches with pros/cons and a recommendation.
### Phase 6: Output
Generate structured output ready for ipa-spec or plan.
## Output Format
### MVP Mode
```markdown
# Lean MVP Analysis: [Project Name]
## Problem Statement
## Target Users
| User Type | Description | Primary Need |
## MVP Features (→ FR-xx)
| Priority | Feature | User Value | Screen | Assumption |
## Implementation Phases
| Phase | Focus | Key Features | Effort |
## GATE 1: Scope Validation
- [ ] Talked to 3+ potential users
- [ ] Users confirmed real pain point
- [ ] MVP scope ≤ 3 phases
- [ ] Assumptions documented
- [ ] Team aligned on priorities
## MVP Screens (→ S-xx)
## Data Entities (→ E-xx)
## User Flow (→ Screen Flow)
## Tech Decisions (→ D-xx)
## Nice-to-Have (Post-MVP)
## Key Assumptions to Validate
## Out of Scope
## Risks
```
### Feature Improvement Mode
```markdown
# Lean Feature Analysis: [Feature Name]
## Current State
## Problem/Opportunity
## Proposed Changes
| Change | User Value | Effort | Priority |
## Impact Analysis
- Affected screens: [S-xx]
- Affected APIs: [endpoints]
- Affected entities: [E-xx]
## Assumptions
## Recommendation
## Next Step
```
## Save Report
Save report to: `plans/reports/lean-{date}-{slug}.md`
## Critical Rules
1. Focus on VALUE — every feature must have clear user value
2. Challenge assumptions — question what user thinks they need
3. Keep it small — MVP means MINIMUM viable
4. Validate first — identify riskiest assumptions
5. No implementation — only analysis and requirements
## Integration
```
lean [idea]
↓
MVP/Feature Requirements
↓
ipa-spec → SRD.md + UI_SPEC.md
↓
ipa-design → HTML mockups
↓
ipa-detail → API_SPEC.md, DB_DESIGN.md
↓
plan → Implementation tasks
```