split

Purpose

Split large IPA documentation files (API_SPEC, DB_DESIGN, SRD) into modular folder structure when files exceed 500 lines.

---

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

---

Output Structure

Before (Single File)

docs/
├── API_SPEC.md         # 800+ lines, hard to navigate

After (Modular)

docs/
├── API_SPEC/
│   ├── README.md       # Agent guide for this folder
│   ├── index.md        # Endpoint matrix (mục lục)
│   ├── auth.md         # /auth/* endpoints
│   ├── users.md        # /users/* endpoints
│   └── orders.md       # /orders/* endpoints

---

Workflow

Step 1: Analyze Document

1. Read target doc (e.g., docs/API_SPEC.md)
2. Check line count:
   • < 500 lines: Skip (no split needed)
   • ≥ 500 lines: Proceed with split
3. Identify sections by headers (## or ###)

Step 2: Create Folder Structure

1. Create folder: docs/{DOC_NAME}/
2. Generate README.md:

# {DOC_NAME}

This folder contains modular IPA documentation split from {DOC_NAME}.md

## Files

| File | Description |
|------|-------------|
| index.md | Overview and navigation |
| {section}.md | {Section description} |

## Usage

Agent should read `index.md` first for overview, then specific files as needed.

Step 3: Generate index.md

Extract matrix/overview section:

• For API_SPEC: Endpoint Matrix table
• For DB_DESIGN: Table Matrix
• For SRD: Requirements Matrix (FR-xx list)

Add links to detail files.

Step 4: Split Content

For each major section (identified by ## headers):

1. Create {section-slug}.md
2. Move section content
3. Add backlink to index.md

---

Section Detection by Doc Type

API_SPEC.md

Split by API group:

• Sections with /auth/* → auth.md
• Sections with /users/* → users.md
• Sections with /orders/* → orders.md

DB_DESIGN.md

Split by domain:

• User tables → users-tables.md
• Order tables → orders-tables.md
• System tables → system-tables.md