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

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

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

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

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

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