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

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:

Run tests before committing.
Use ESLint for linting.
Deploy with `make deploy`.
All PRs need two approvals.
Use feature branches.

Good:

## 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

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 — 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

Run skillsaw explain content-cognitive-chunks to see this documentation and the rule's effective configuration in your terminal.