antigravity-ipa-workflow/skills/ipa-docs-split/SKILL.md

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