5 Cognitive Facts About ADHD Reading That Drive the i-have-adhd Rules

The i-have-adhd skill is built on five evidence‑based cognitive facts about ADHD reading—limited working memory, knowledge‑action friction, initiation difficulty, uniform time perception, and dopamine scarcity—that dictate how AI assistants must structure their responses.

The ayghri/i-have-adhd repository codifies these psychological principles into deterministic output rules for AI agents. According to the source code in skills/i-have-adhd/SKILL.md, these cognitive facts are explicitly listed at lines 21‑30 and directly inform the rule implementations at lines 31‑143, ensuring every interaction accommodates how readers with ADHD actually process information.

The Five Cognitive Facts About ADHD Reading

1. Working‑Memory Capacity Is Limited

ADHD readers forget information that scrolls off the screen almost immediately. To compensate, Rule 1 ("Lead with the next action") and Rule 5 ("Restate state every turn") require that the current step always remain physically visible and be reiterated on every turn. This design ensures that critical context never vanishes into working‑memory decay.

2. Knowing the Answer ≠ Doing the Answer

The mental friction between understanding what to do and actually initiating the action often paralyzes task completion. Rule 3 ("End with one concrete next action") directly targets this gap by forcing every response to terminate with a single, executable instruction, converting abstract knowledge into kinetic action.

3. Starting Is the Hardest Step

Initiation inertia means the barrier to entry must be minimized to the smallest possible atomic action. This fact drives Rule 2 ("Number multi‑step tasks"), which breaks complex work into bounded, sequentially numbered items, and reinforces Rule 1 by ensuring the very first item is tiny, obvious, and doable without deliberation.

4. Time Estimates Feel Uniform

Vague temporal descriptors like "a bit of work" or "a few hours" are processed by ADHD cognition as identical, undefined durations. Rule 6 ("Give specific time estimates") mandates concrete minute‑level timing (e.g., "15 minutes") to counter this perceptual flattening and enable realistic scheduling.

5. Dopamine Is Scarce

Motivation requires visible progress; hidden or abstract wins provide no neurological reward. This fact implements Rule 7 ("Make completed work visible") and Rule 9 ("Cap lists to 5 items"), which foreground immediate achievements and restrict the visible workload to maintain dopaminergic engagement without overwhelming the reader.

Implementation in the Source Code

The cognitive facts are canonically defined in skills/i-have-adhd/SKILL.md within the section titled "What ADHD changes about reading" (lines 21‑30). The subsequent lines (31‑143) instantiate these facts as programmatic rules governing output formatting. The AGENTS.md file maps these constraints to runtime adapters, while README.md provides the user‑facing rationale for the repository’s design.

Practical Code Examples

Below are concrete implementations demonstrating how these cognitive principles transform response formatting.

Single‑Step Friction Removal

Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`.

This example satisfies Rule 1 and Rule 3 by placing the executable command first and eliminating any ambiguity about what to do next, directly countering the "starting is hardest" cognitive fact.

Multi‑Step Task With State Restatement

1. Open `src/auth.ts`  
2. Replace `verifyToken` (lines 42‑58) with the snippet below  
3. Run `npm test -- auth.spec.ts`

**Step 2 of 3 done:** verifyToken replaced. **Next:** run the test (≈ 5 minutes).

This format implements Rule 2 (numbering), Rule 5 (restating current progress), and Rule 6 (specific time estimates), addressing working‑memory limitations, knowledge‑action friction, and time‑perception distortions simultaneously.

Dopamine‑Optimizing Win Visibility

Login now works with magic links. Try: `npm run dev`, open `/login`.

By foregrounding the completed achievement, this snippet applies Rule 7, providing the immediate dopaminergic feedback required by the "dopamine is scarce" cognitive fact.

Summary

• The i-have-adhd skill translates five cognitive facts about ADHD reading into strict output rules documented in skills/i-have-adhd/SKILL.md.
• Working‑memory limits enforce leading with actions and restating state every turn to prevent information loss.
• Knowledge‑action friction requires ending every response with one concrete, executable next step.
• Initiation difficulty drives the use of sequential numbering and atomic first steps.
• Uniform time perception necessitates specific minute‑level estimates rather than vague qualitative descriptors.
• Dopamine scarcity mandates visible progress markers and a maximum of five visible list items per response.

Frequently Asked Questions

Where are the cognitive facts about ADHD reading documented in the repository?

The facts are explicitly listed in skills/i-have-adhd/SKILL.md at lines 21‑30 under the heading "What ADHD changes about reading". These lines form the theoretical foundation for the practical rules defined immediately afterward in lines 31‑143 of the same file.

How does the skill compensate for ADHD working‑memory limitations?

It enforces Rule 1 (Lead with the next action) and Rule 5 (Restate state every turn) to ensure that the current instruction never leaves the physical screen and is repeated on every interaction, mitigating the rapid decay characteristic of ADHD working memory.

Why must time estimates be specific rather than vague?

Because Rule 6 requires concrete timing (e.g., "15 minutes") to counter the cognitive fact that vague descriptors like "a while" or "soon" are interpreted as uniform, undefined durations by ADHD readers, which prevents accurate planning and increases anxiety.

What is the role of the AGENTS.md file in the i-have-adhd repository?

AGENTS.md maps the ADHD‑focused skill rules to various runtime adapters and explains how the cognitive‑fact‑driven constraints are invoked across different execution contexts, bridging the gap between the theoretical framework in SKILL.md and practical deployment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}