principle-minimize-reader-load
cursor/plugins
Reduce code complexity by minimizing reader cognitive load—collapse unnecessary layers and shrink mutable state.
What is principle-minimize-reader-load?
This principle guides code review and refactoring by measuring maintainability through two axes: layers of indirection between a question and its answer, and hidden or mutable state readers must hold in memory. Apply it when code is hard to trace, to identify and eliminate unnecessary wrappers, pass-through abstractions, and scattered state.
- Count indirection layers between a code question and its answer to identify unnecessary abstraction
- Measure hidden or mutable state that readers must keep in working memory
- Collapse one-caller wrappers and pass-through adapters that repeat methods without compression
- Shrink mutable scope by preferring pure functions, locals over fields, and derived over synchronized state
- Demand interface compression at boundaries to hide meaningful decisions rather than repeat surface complexity
How to install principle-minimize-reader-load
npx skills add https://github.com/cursor/plugins --skill principle-minimize-reader-loadHow to use principle-minimize-reader-load
- 1.When reviewing code, identify the two axes: count layers between the question and answer, and list hidden or mutable state readers must track
- 2.Apply the 30-second test: can a new reader answer 'where does X come from?' and 'what can change X?' in under 30 seconds?
- 3.If the test fails, collapse unnecessary layers by inlining one-caller wrappers and removing pass-through adapters
- 4.Shrink state scope by converting mutations to returns, moving fields to locals, and deriving values instead of syncing them
- 5.Before adding a new layer or state, verify it reduces reader load elsewhere by at least as much as it costs
Use cases
- Reviewing a codebase where tracing a feature requires jumping through multiple adapter layers
- Refactoring a module with broad interfaces that expose both surface and implementation details
- Identifying why a new team member struggles to answer 'where does X come from?' quickly
- Deciding whether to add a new abstraction layer or inline an existing one
- Reducing cognitive overhead in codebases with scattered global or module-level mutable state
- Code reviewers evaluating maintainability
- Refactoring engineers optimizing for readability
- Team leads designing module boundaries
- Developers onboarding to complex codebases
principle-minimize-reader-load FAQ
Reader load directly measures cognitive work—the thing that matters for maintainability. LOC and cyclomatic complexity are proxies that can miss flat files with 50 globals or miss the real cost of indirection.
A layer that repeats the same methods and arguments as the layer below it without changing the abstraction. It adds reader load without compression and should be collapsed.
Keep it only if it reduces reader load elsewhere by at least as much as it costs. A single-caller wrapper that hides a complex decision or shrinks state scope may be worth keeping.
Document or encode the constraint once at the interface level (e.g., in a type or precondition) so readers learn it once, rather than inferring it from every consumer.
Both protect finite cognitive resources—one for AI models, one for human readers. Reader load is the human analog of context-window pressure.
Full instructions (SKILL.md)
Source of truth, from cursor/plugins.
name: principle-minimize-reader-load description: "Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope." disable-model-invocation: true
Minimize Reader Load
Maintainability is the work a reader must do to understand code. Track two axes:
- Layers to trace. How many indirections sit between the question and the answer.
- State to hold. How much hidden or mutable context the reader must keep in their head.
Why: Code is read far more than it is written. LOC, cyclomatic complexity, and "clean architecture" are proxies. Reader load is the thing that matters. The two axes are independent. A flat file with 50 globals can be as hard to reason about as a 6-layer adapter stack. Guard both. This is the human analog of Guard the Context Window. Working memory is finite for readers too.
The pattern:
- Collapse layers that cost more than they save: wrappers with one caller, adapters with no second implementation, speculative indirection that was never needed. Inline them.
- Make adjacent layers change the abstraction. A layer that repeats the same methods and arguments adds reader load without compression. Collapse pass-through layers.
- Demand interface compression. A broad interface that hides little complexity makes readers learn both the surface and the implementation. Prefer boundaries that hide meaningful decisions.
- Shrink state scope: prefer pure functions (returns over mutations), locals over fields, fields over module state, and module state over globals. Derive instead of sync.
- Name the invariant at the boundary, not in every consumer, so the reader learns it once.
- Before adding a layer or a piece of state, ask: does this reduce reader load somewhere else by at least as much?
The test: Can a new reader answer "where does X come from?" and "what can change X?" in under 30 seconds? If not, cut layers or cut state.
Related skills
More from cursor/plugins and the wider catalog.
principle-model-the-domain
Encode domain logic in structures instead of scattered conditionals and repeated assumptions.
principle-never-block-on-the-human
Proceed with reversible work without asking permission; reserve confirmation for irreversible actions only.
principle-outcome-oriented-execution
Prioritize end-state correctness over intermediate stability during planned rewrites and migrations.
principle-prove-it-works
Verify task completion by checking real artifacts, not proxies or self-reports.
principle-redesign-from-first-principles
Redesign existing systems as if new requirements were foundational, not bolted-on.
principle-separate-before-serializing-shared-state
Eliminate concurrent write conflicts by separating mutable state before applying serialization.