# content-cognitive-chunks Check that instruction files are organized into cognitive chunks with headings | | | |---|---| | **Severity** | info (auto) | | **Autofix** | - | | **Since** | v0.7.0 | | **Category** | [Content Intelligence](content-intelligence.md) | ## Why Models process grouped instructions more reliably than flat lists. Section headings act as cognitive anchors — they help the model compartmentalize instructions by topic and retrieve the right ones when a task matches a heading. Unstructured files force the model to scan everything linearly, increasing the chance of missed instructions. ## Examples **Bad:** ```markdown Run tests before committing. Use ESLint for linting. Deploy with `make deploy`. All PRs need two approvals. Use feature branches. ``` **Good:** ```markdown ## Testing Run tests before committing. ## Code style Use ESLint for linting. ## Deployment Deploy with `make deploy`. ``` ## How to fix Add markdown headings (`##`) to group related instructions by topic. Aim for 10–30 lines per section. If the file has only one heading, break it into task-oriented subsections. A coding agent can add headings automatically. ## Configuration ```yaml rules: content-cognitive-chunks: enabled: auto # true | false | auto severity: info ``` ## 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](https://psycnet.apa.org/record/1957-02914-001) — Working memory limits - [NN/g: How Chunking Helps Content Processing](https://www.nngroup.com/articles/chunking/) — "Presenting content in chunks makes scanning easier and improves comprehension" - [OpenAI Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering) — "Use delimiters to clearly indicate distinct parts" - [Claude Code Best Practices](https://docs.anthropic.com/en/docs/claude-code/best-practices) — Recommends progressive disclosure with clear headings *Run `skillsaw explain content-cognitive-chunks` to see this documentation and the rule's effective configuration in your terminal.*