splitting-notes

Splitting Notes

Overview

Split large monolithic note files into focused, single-topic files with index-based navigation. Reduces cognitive load and improves discoverability through progressive grouping.

When to Use

digraph when_refactor {
  "Note file size > 1000 lines?" [shape=diamond];
  "Topics mixing unrelated concepts?" [shape=diamond];
  "Hard to find specific information?" [shape=diamond];
  "Refactor notes" [shape=box];
  "Keep as-is" [shape=box];

  "Note file size > 1000 lines?" -> "Refactor notes" [label="yes"];
  "Note file size > 1000 lines?" -> "Topics mixing unrelated concepts?" [label="no"];
  "Topics mixing unrelated concepts?" -> "Refactor notes" [label="yes"];
  "Topics mixing unrelated concepts?" -> "Hard to find specific information?" [label="no"];
  "Hard to find specific information?" -> "Refactor notes" [label="yes"];
  "Hard to find specific information?" -> "Keep as-is" [label="no"];
}

Use when:

• Note files exceed 1000 lines
• Single file mixes unrelated topics
• Navigation and search are difficult
• Content needs better organization

Don't use when:

• Files are already under 500 lines
• Topics are tightly coupled
• Splitting would harm coherence

Prerequisite

Complex multi-step refactoring - Must complete planning phase first.

If not currently in plan mode, invoke EnterPlanMode before starting.

• In plan mode: Complete analysis and create migration plan
• After plan mode: Execute split and verification

Core Pattern

Before - Monolithic file:

content/topic/large-file.md (1500+ lines)
├── H2 Chapter 1
├── H2 Chapter 2
├── H2 Chapter 3
└── ...10+ more sections

After - Modular structure:

content/topic/
├── topic.md (index, ~50 lines)
├── chapter-1.md (~200 lines)
├── chapter-2.md (~150 lines)
├── chapter-3.md (~180 lines)
└── ...remaining chapters

See examples.md for complete walkthroughs of:

• Simple split (300 lines, Python)
• Medium split (850 lines, Vue)
• Complex split (1500 lines, React)