# zakirullin/cognitive-load: a code review checklist built on working memory limits

> This repository is not software. It is a prose document about extraneous cognitive load in code, and it argues that most style rules fail because they were imagined rather than measured. Here is what it actually claims, how to read it, and where it stops being useful.

**zakirullin/cognitive-load** — 🧠 Cognitive load is what matters

- Repository: https://github.com/zakirullin/cognitive-load
- Stars: 12,514 · Forks: 305
- Language: Unknown
- License: CC-BY-4.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/zakirullin-cognitive-load

## What zakirullin/cognitive-load actually is, and who should read it

The repository contains no source code. The top level holds LICENSE, README.md, README.agents.md, eight translated README files, and an img directory. That is the whole project. The README calls itself "a living document, last update: June 2026" and the last push to the repository was on 2026-06-29, so it is still being edited rather than frozen.

The problem it addresses is stated plainly: confusion while reading code costs time and money, and the cause is cognitive load. The document defines cognitive load as "how much a developer needs to think in order to complete a task" and leans on a working memory figure of roughly four chunks. It is careful about its own grounding, noting that it uses the term informally and that "sometimes it lines up with the specific scientific concept of Cognitive Load, but we don't know enough about where it does and doesn't match." That caveat is worth more than most style guides offer.

The intended reader is a working engineer who reviews other people's code and needs an argument that survives disagreement. The document is not a tutorial and not a specification. It is a set of positions with examples attached, and its value depends on whether you accept the framing that extraneous load is the part you can remove.

## Intrinsic versus extraneous load, and why the distinction carries the whole argument

The document splits load into two kinds. Intrinsic load comes from the inherent difficulty of the task and, in its words, "can't be reduced, it's at the very heart of software development." Extraneous load comes from how information is presented, is caused by factors not relevant to the task, and "can be greatly reduced." The document says it will focus on extraneous load.

That split is the load-bearing wall. Without it, the guide would collapse into a general complaint that code is hard. With it, every example becomes a claim of the same shape: this structure adds work that the problem itself did not require. A nested branch that could be an early return is extraneous. A four-level inheritance chain is extraneous. A pile of shallow classes is extraneous.

The document also offers a crude notation for tracking load as you read: a brain glyph for fresh working memory, a brain glyph with plus signs for each additional fact held, and an overload glyph past four facts. It admits the model is simplistic, writing that "our brain is much more complex and unexplored, but we can go with this simplistic model." Treat the notation as a teaching device rather than a measurement. Nothing in the repository validates it against anything.

## Complex conditionals and nested ifs: the two examples most teams will reuse

The first worked example is a compound condition. A single if statement combines a comparison with two parenthesised groups, and the document annotates each clause with rising load until the reader reaches overload. The proposed fix is intermediate boolean variables with descriptive names, so the final condition reads as a short conjunction of named facts. The claim is that you no longer have to remember the sub-conditions, because the names carry them.

The second example is nesting. A valid check wrapping a secure check wrapping the work gets annotated as load accumulating with each level. The alternative is early returns: bail out on the invalid case, bail out on the insecure case, and let the body of the function be the happy path. The document's phrasing is that after the guards, "we don't really care about earlier returns, if we are here then all good."

Both examples are written in Go, and the repository ships no other language variants of the snippets. The reasoning transfers, but the syntax does not, and a reviewer quoting the early-return example in a language where guard clauses interact badly with resource cleanup should say so rather than repeat the guide.

## The inheritance and shallow module sections, where the document takes a real position

The inheritance example walks an imagined controller hierarchy from a base controller up through guest and user controllers to an admin controller, adding load at each level, then reveals a superuser controller that extends the admin one. The point is that modifying a class you are looking at can break a class you have not opened yet. The recommendation is composition over inheritance, and the document declines to argue the case in detail, pointing to outside material instead. That is a gap, not a strength.

The shallow module section is the more interesting one because it pushes against received wisdom. It quotes the mantras that methods should be shorter than fifteen lines and classes should be small, then says they "turned out to be somewhat wrong." It contrasts a deep module (simple interface, complex functionality) with a shallow module (interface relatively complex compared to the small functionality it provides), and argues that many shallow modules force you to hold every module's responsibilities plus all their interactions. The line worth keeping is that jumping between shallow components is mentally exhausting and that linear thinking is more natural.

The supporting anecdote is two personal projects of roughly 5K lines each, one with 80 shallow classes and one with 7 deep classes, neither maintained for a year and a half. The author reports that returning to the 80-class project meant untangling a large number of interactions. This is one developer's experience with two unnamed projects, presented without measurement. It illustrates the argument; it does not establish it.

## Reading it without installing anything, and the one file that changes how you use it

There is nothing to install. The repository is a document, and the README states its own recommended entry points: a link to README.agents.md for AI agents, a blog at minds.md, and translated READMEs in Chinese, Japanese, Spanish, Korean, Turkish, Brazilian Portuguese, Vietnamese and Nepali. If you want the document locally, clone it and open the Markdown file.

```bash
git clone https://github.com/zakirullin/cognitive-load.git
cd cognitive-load
```

After cloning, the working directory contains README.md, README.agents.md, the translated README files, LICENSE and img. There is no build step, no package manifest and no test command, because there is no code.

The first real use is not running something. It is picking one example from the README and applying it to a function you are reviewing this week. The compound-conditional example is the easiest to try, because the transformation is mechanical: name the sub-conditions, then read the final condition aloud. If the names do not make the condition obvious, the original probably had a design problem rather than a naming problem.

The second use is the agents file. README.agents.md exists as a separate entry point aimed at AI coding tools, and the main README flags the AI context directly, noting that it is "especially important in the AI age, when we need to process a lot of LLM-generated code with our own brains." If you paste review guidance into a coding assistant, that file is the version written for that purpose. The README does not document what differs between the two files.

## Where the document is weak, and when it is the wrong tool

The largest limitation is that nothing here is measured. The four-chunk working memory figure is cited to a GitHub issue rather than to a study, and the repository itself says the informal use of the term may not match the scientific concept. The load notation is explicitly a simplification. The two-project anecdote has no code, no names and no numbers beyond line counts and class counts. A reader who wants evidence will not find it here.

The second limitation is scope. The document covers extraneous load in code structure and stops there. It does not address naming, test design, build times, review process or documentation, all of which consume the same working memory. A team that adopts the vocabulary and then applies it only to nesting depth has adopted a fraction of the argument.

The third is that the guide is prescriptive without being enforceable. There is no linter, no rule set and no configuration format, so nothing prevents the recommendations from becoming another set of mantras of exactly the kind the document criticises. If your problem is that reviewers disagree about structure and you need an automated gate, this repository cannot help. If your problem is that they disagree and you need a shared reason, it can.

## How it differs from the cognitive load theory literature people search for

Searches around this term mostly lead to John Sweller's cognitive load theory from 1988 and to its use in education and UX. That literature is empirical: it runs studies, separates load types, and measures outcomes. This repository borrows the vocabulary and the intuition, applies them to source code, and does not attempt the measurement. The README is upfront about that boundary.

The practical difference matters when you choose what to read. If you need to justify a design decision to a skeptical colleague with evidence, the academic literature is the right source and this document is a secondary application of it. If you need a short, opinionated text that a reviewer can read in twenty minutes and then use in a pull request comment, the education literature is the wrong shape for that job and this document is the right one. The two are complementary, not competing, and the repository is honest that it sits on the informal side of the line.

## Conclusion

Adopt this as a shared vocabulary for code review if your team argues about structure using taste rather than a stated constraint. Do not adopt it if you need a linter, a metric or an automated check; the repository has no code, no package and no CLI, so there is nothing to wire into CI. Before you quote it in a review, verify which of its examples map to your language, because the snippets are Go and the argument is language-agnostic only in intent. Read README.agents.md if you plan to feed the document to a coding assistant.

## FAQ

### What kind of cognitive load example does zakirullin/cognitive-load give?

The README works through complex conditionals, nested ifs, inheritance chains and shallow modules, annotating each with rising load and then showing a restructured version. The compound conditional and the early-return rewrite are the two examples most readers will reuse directly.

### What causes high cognitive load according to this repository?

It points at extraneous load, which it defines as load created by how information is presented rather than by the difficulty of the task itself. Its examples include compound conditions with multiple clauses, deep nesting, long inheritance chains and large numbers of shallow modules.

### What is cognitive load management in the context of this document?

The document treats it as a reading-time concern: since more time goes into reading code than writing it, the question to ask constantly is whether a change adds load the task did not require. Its proposed techniques are naming intermediate values, preferring early returns, favouring composition, and consolidating shallow modules into deep ones.

### What are the signs of cognitive overload described in zakirullin/cognitive-load?

The document marks overload as more than four facts held in working memory at once, and illustrates it with compound conditions that stack clauses and inheritance chains that add a level of context at each step. It describes the feeling as confusion while reading code.

## Sources

- [Issues](https://github.com/zakirullin/cognitive-load/issues)
- [License: CC-BY-4.0](https://github.com/zakirullin/cognitive-load/blob/main/LICENSE)
- [README](https://github.com/zakirullin/cognitive-load/blob/main/README.md)
- [Releases](https://github.com/zakirullin/cognitive-load/releases)
- [zakirullin/cognitive-load on GitHub](https://github.com/zakirullin/cognitive-load)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zakirullin-cognitive-load