Initial commit: antigravity-ipa-workflow

skills/ipa-docs-split/SKILL.md

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