5 ADHD Cognitive Facts That Inform the I Have ADHD Rules Design

The i-have-adhd skill encodes five evidence-based ADHD cognitive facts—covering working memory constraints, initiation friction, and dopamine regulation—to structure AI responses that minimize cognitive load and maximize task completion.

The ayghri/i-have-adhd repository defines a prompt engineering framework that adapts AI output specifically for readers with ADHD. By hardcoding these ADHD cognitive facts into the agent's ruleset, the system ensures every response accounts for neurological differences in memory, motivation, and time perception. These principles are explicitly listed in skills/i-have-adhd/SKILL.md (lines 25–29) and form the foundation for the eight concrete formatting rules that govern all agent output.

The Five ADHD Cognitive Facts

The skill definition organizes its guidance around five observations about how ADHD-impacted brains process and act on information.

1. Working Memory Is Limited

Anything not on screen is forgotten. The ADHD brain has reduced working memory capacity, making it impossible to "keep in mind" information that is not immediately visible.

According to the source code in SKILL.md at line 25, this fact mandates that the skill never asks the reader to remember something for later. Every required detail must appear in the current response, eliminating the need to hold context across turns.

2. Knowing Is Not Doing

The friction between "got it" and "done it" is where work dies. Understanding a concept and executing it are neurologically distinct events for readers with ADHD.

As documented at line 26 of SKILL.md, this gap requires turning instructions into concrete, actionable steps rather than abstract explanations. The rules forbid vague guidance and demand specific, executable commands.

3. Starting Is the Hardest Step

The first action must be obvious, small, and doable now. Initiation is the primary barrier to productivity.

Line 27 of SKILL.md dictates that the very first line of every response must be a single, executable action—such as a terminal command or a specific file edit—removing all ambiguity about where to begin.

4. Time Estimates Feel Uniform

"A bit of work" and "a few hours" register the same. Vague temporal language fails to communicate actual effort because ADHD impacts time perception.

The rule at line 28 requires all estimates to use concrete units (minutes, hours, days) so readers can accurately gauge effort and allocate focus. Abstract qualifiers are prohibited.

5. Dopamine Is Scarce

Visible progress matters; buried wins do not register. The ADHD brain requires externalized feedback to maintain motivation.

As stated at line 29 of SKILL.md, every response must highlight completed work ("wins") clearly, turning abstract progress into tangible outcomes that provide dopamine reinforcement.

Applying the Facts: Code Examples

These ADHD cognitive facts translate directly into response formatting rules. Below are practical implementations showing how the skill transforms standard AI output into ADHD-optimized instructions.

Leading with an Obvious First Action

Instead of abstract investigation instructions, the skill demands an immediate executable command:

// Violates Fact 3: "Starting is the hardest step"
console.log("Let's investigate the auth flow.");

// Applies Fact 3: Obvious, small, doable now
console.log("Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`.");

Providing Concrete Time Estimates

Vague duration language is replaced with specific units to respect Fact 4:

// Violates Fact 4: "Time estimates feel uniform"
console.log("It will take some work.");

// Applies Fact 4: Concrete units for accurate gauging
console.log("About 15 minutes if tests already cover this; an afternoon otherwise.");

Making Wins Visible

Completed work is explicitly surfaced to address Fact 5:

// Violates Fact 5: "Dopamine is scarce"
console.log("I fixed several things.");

// Applies Fact 5: Tangible outcomes register as progress
console.log("Login now works with magic links. Try: `npm run dev` and open `/login`.");

Full Compliant Response Structure

A complete response that honors all five ADHD cognitive facts follows this pattern:

1. Open `src/auth.ts` (takes < 2 min).
2. Replace the `verifyToken` function with the snippet below.
3. Run `npm test -- auth.spec.ts` (≈ 5 min).

✅ Login now works with magic links. Try: `npm run dev` and open `/login`.
⏱ Estimated total time: ~ 15 minutes.

Source Code Location

The ADHD cognitive facts and their derived rules are canonically defined in the following repository files:

• skills/i-have-adhd/SKILL.md — Contains the five cognitive facts (lines 25–29) and the eight formatting rules they generate
• .opencode/command/i-have-adhd.md — Declares the /i-have-adhd command that activates the skill for a session
• AGENTS.md — Maps the skill to various runtime adapters (Claude, Codex, Pi, etc.)
• README.md — Provides high-level project context and cites the adult ADHD toolkit inspiration

Summary

The i-have-adhd framework reduces cognitive friction by aligning AI output with ADHD neurological constraints:

• Working memory limitations require all information to appear on-screen
• The knowing-doing gap mandates concrete, actionable steps over abstract explanations
• Initiation friction requires the first line of every response to be an executable action
• Time perception differences enforce concrete units (minutes/hours) instead of vague qualifiers
• Dopamine scarcity demands visible wins and explicit progress markers in every response

Frequently Asked Questions

How does the i-have-adhd skill differ from standard prompting techniques?

Standard AI prompting often relies on summarization, abstraction, and multi-turn context retention. The i-have-adhd skill explicitly rejects these patterns because they conflict with ADHD working memory and initiation constraints. Instead, it enforces single-turn completeness, executable first steps, and concrete timeboxing as documented in skills/i-have-adhd/SKILL.md.

Why are vague time estimates prohibited in the rules?

Because of the fourth ADHD cognitive fact: time estimates feel uniform to the ADHD brain. Phrases like "soon" or "a while" fail to trigger appropriate planning responses. By requiring estimates in minutes or hours (line 28 of SKILL.md), the skill enables accurate effort calibration and reduces anxiety about hidden time sinks.

Can these ADHD cognitive facts be applied to non-technical writing?

Yes. While the repository implements these rules for code assistance, the five facts apply to any instructional content. Documentation, email, project management, and educational materials all benefit from on-screen completeness, obvious first actions, concrete time estimates, and visible progress markers when the audience includes ADHD readers.

Where are the eight concrete rules defined that derive from these facts?

The eight formatting rules—such as "lead with the next action" and "number multi-step tasks"—immediately follow the five cognitive facts in skills/i-have-adhd/SKILL.md. They operationalize the abstract principles into specific requirements for response structure, including the prohibition of multi-turn memory and the mandate for explicit win statements.

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