Cognitive Chunks¶
Rule ID: content-cognitive-chunks
Check that instruction files are organized into cognitive chunks with headings
| Severity | info (auto) |
| Autofix | llm |
| Since | v0.7.0 |
Research Basis¶
Checks that instruction files are organized into cognitive chunks with headings.
Working memory is limited to ~4–7 items (Miller, 1956; revised to ~4 by Cowan, 2001). Headings create chunk boundaries that reduce cognitive load for both humans editing the file and the model processing it. A 60-line file with no headings is a single undifferentiated block; the same content split into 4 headed sections is 4 discrete, navigable chunks.
For LLMs specifically, headings serve as natural delimiters. OpenAI's guide recommends: "Use delimiters to clearly indicate distinct parts of the input." Markdown headings are the idiomatic delimiter for instruction files.
References:
- Miller, G. A. (1956), The Magical Number Seven, Plus or Minus Two — Working memory limits
- NN/g: How Chunking Helps Content Processing — "Presenting content in chunks makes scanning easier and improves comprehension"
- OpenAI Prompt Engineering Guide — "Use delimiters to clearly indicate distinct parts"
- Claude Code Best Practices — Recommends progressive disclosure with clear headings