104 lines
2.7 KiB
Markdown
104 lines
2.7 KiB
Markdown
---
|
|
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
|