Philosophy

Large documents are hard to navigate and maintain.

Breaking them into focused, linked modules improves both readability and maintainability.

Core Principle: Ask When Unsure

When in doubt, use AskUserQuestion to confirm with the user.

This ensures the highest quality outcome. Never make assumptions about:

•Which pattern defines sections
•How the user wants files organized
•Whether detected sections are correct
•Any ambiguous aspect of the document

The AskUserQuestion tool is your primary mechanism for maintaining quality.

Input/Output

Input: Single markdown file with multiple sections (any consistent pattern)

Output:

•Original file → Clean index with title, intro, linked section list
•Each section → Numbered file (1-section-name.md, 2-section-name.md, etc.)

Usage

Invoke with any markdown file path:

•/modularize-document /path/to/document.md
•/modularize-document ./relative/path/doc.md

Detail files are created based on user's chosen output structure.

Section Detection

Analyze the document to detect logical sections using any consistent pattern:

•## headings (most common)
•# headings (if multiple top-level headings exist)
•Numbered headings (1., 2., 1), etc.)
•Bold text used as section headers (**Section Name**)
•Horizontal rules (---) as dividers
•Any other consistent structural pattern

Do NOT hardcode to only look for ##. Adapt to whatever structure the document uses.

Output Structures

Option A - Flat (same directory)

All detail files in the same directory as the original:

code

original-dir/
├── document.md (becomes index)
├── 1-introduction.md
├── 2-core-concepts.md
└── 3-api-reference.md

Links: [Section Name](./1-section-name.md)

Option B - Nested (subdirectory per section)

Each section gets its own subdirectory:

code

original-dir/
├── document.md (becomes index)
├── 1-introduction/
│   └── 1-introduction.md
├── 2-core-concepts/
│   └── 2-core-concepts.md
└── 3-api-reference/
    └── 3-api-reference.md

Links: [Section Name](./1-section-name/1-section-name.md)

Index File Structure

•Title (from original # heading or document start)
•Brief intro sentence (if present before first section)
•Sections as linked headers: ### [1. Section Name](./path-to-file.md)
•2-3 sentence description per section

Detail File Structure

•# Section Name (promoted to top-level heading)
•Full original content preserved
•All subsections kept intact
•Self-contained and readable standalone

Workflow

Input: File path to a markdown document

code

1. ANALYZE
   - Read the file
   - Detect section boundaries (adapt to document's pattern, not just ##)
   - Identify title and any intro text before first section

2. CONFIRM SECTIONS (use AskUserQuestion)
   - Present detected sections to user:
     "I found N sections in this document:
      1. First Section
      2. Second Section
      3. Third Section
      Does this look right?"
   - Options: "Yes, proceed" / "Let me adjust"
   - If uncertain about detection pattern, ask for clarification

3. CHOOSE OUTPUT STRUCTURE (use AskUserQuestion)
   - Ask user: "How should the output be organized?"
   - Options:
     - Flat: All files in same directory
     - Nested: Each section gets its own subdirectory

4. GENERATE DETAIL FILES
   - For each section:
     - Create numbered file (1-kebab-name.md, 2-kebab-name.md...)
     - If nested: create subdirectory first
     - Promote section heading to #
     - Include all content until next section or EOF

5. TRANSFORM INDEX
   - Keep original file as index
   - Retain title and intro
   - Replace sections with linked list + brief descriptions
   - Use correct link format based on chosen structure

6. REPORT
   - Output structure used
   - Files created
   - Content preserved confirmation

Filename Convention

Convert section titles to kebab-case:

•"Core Concepts" → 1-core-concepts.md
•"API Reference & Examples" → 2-api-reference-and-examples.md
•"Getting Started" → 3-getting-started.md

User Interaction Guidelines

Asking is the default, not a fallback. Quality comes from confirmation, not assumptions.

Always use AskUserQuestion for:

•Confirming detected sections are correct
•Choosing between flat and nested output structures
•Section detection is ambiguous (multiple possible patterns)
•Only 1 section found (ask if they still want to proceed)
•Any uncertainty about document structure

The bar for "uncertainty" is low - if you're even slightly unsure, ask. A quick question prevents incorrect output that wastes user time.

Constraints

•Never lose content - All section content goes into detail files
•Preserve subsections - Nested headings stay within their parent detail file
•Use kebab-case - Filenames derived from section titles
•Relative paths - Links use ./ prefix
•Maintain order - Numbering reflects original document order
•Adapt detection - Use whatever section pattern the document follows
•
Handle edge cases:
- •No sections found → Report "nothing to modularize" and exit without changes
- •Only 1 section → Ask user if they still want to proceed
- •Ambiguous structure → Ask user to clarify which pattern to use