Modularize Document

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:

1. Original file → Clean index with title, intro, linked section list
2. 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:

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:

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

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