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