The Cognitive Facts Behind the i-have-adhd Rules: How ADHD Science Shapes AI Interaction

The i-have-adhd skill applies five evidence-based cognitive principles—small working memory, the knowing-doing gap, initiation difficulty, time blindness, and dopamine scarcity—to structure AI responses that are immediately actionable, memorable, and motivating for users with ADHD.

The ayghri/i-have-adhd repository implements a specialized AI interaction model grounded in cognitive psychology research. By encoding specific cognitive facts about ADHD into deterministic formatting rules, the skill ensures every output accommodates working memory limitations and execution barriers. These cognitive facts behind the i-have-adhd rules are explicitly documented in skills/i-have-adhd/SKILL.md between lines 23-30, creating a rigid framework for ADHD-friendly communication.

The Five Cognitive Facts Driving the Rules

1. Working Memory Constraints Require Constant Visibility

Working memory is small—anything not displayed on the screen is quickly forgotten. This cognitive limitation directly informs Rule 1 ("Lead with the next action") and Rule 5 ("Restate state every turn"), which keep the crucial next step visible at all times. The skill never assumes the user remembers context from previous turns, ensuring critical information remains in the immediate visual field.

2. The Knowing-Doing Gap Stalls Execution

Knowing the answer is not doing the answer—the gap between "got it" and "did it" is where work stalls for individuals with ADHD. To bridge this executive dysfunction, Rule 3 ("End with one concrete next action") forces every response to conclude with a concrete, doable step. This eliminates the ambiguity that prevents task initiation.

3. Initiation Difficulty Demands Obvious Starting Points

Starting is the hardest step—the first action must be obvious, tiny, and doable now. Rule 1 and Rule 2 ("Number multi-step tasks") make the opening step explicit and break complex work into bounded, numbered actions. By reducing the cognitive load required to begin, the skill circumvents the paralysis associated with vague or multi-layered instructions.

4. Time Blindness Requires Concrete Estimates

Time estimates feel uniform—phrases like "a bit" and "a few hours" are perceived identically by ADHD cognition, leading to avoidance. Rule 6 ("Give specific time estimates") compels numeric time frames in minutes (e.g., "About 15 minutes"), allowing accurate effort gauging. This specificity counters time blindness by anchoring tasks to measurable units.

5. Dopamine Scarcity Requires Visible Wins

Dopamine is scarce—visible progress is required for motivation, while buried wins never register. Rule 7 ("Make completed work visible") surfaces immediate accomplishments to reinforce continued engagement. The skill explicitly highlights what has been finished to trigger the dopaminergic reward loops necessary for sustained attention.

How the Rules Are Implemented in the Codebase

The architectural flow enforces these cognitive facts through persistent session management and strict output formatting. When a user invokes /i-have-adhd, the skill loads the rule set from skills/i-have-adhd/SKILL.md and persists it for the session using extensions/i-have-adhd.ts and hooks/always-on.mjs.

During Input Processing, the model receives the user query plus the complete rule set as system-prompt context. This guarantees that every generated reply respects the five cognitive facts. The Output Generation phase requires the model to produce responses that:

• Begin with an actionable line (Facts 1 and 3)
• Number steps if needed (Fact 3)
• End with a single next-action (Fact 2)
• Show any completed work (Fact 5)
• Include a concrete time estimate (Fact 4)

If any rule conflicts with higher-priority user requests (e.g., safety), the request overrides the rule, but the shape of the answer remains compliant where possible.

Practical Examples of ADHD-Optimized Output

Invoking the Skill

# Install the skill (once)

curl -L https://github.com/ayghri/i-have-adhd/raw/main/INSTALL.md | sh

# Activate ADHD-friendly mode

/i-have-adhd

Typical Response Structure

Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`.
1. Open `src/auth.ts`
2. Replace `verifyToken` with the new snippet
3. Run `npm test -- auth.spec.ts`
About 15 minutes if tests already exist.
Login now works with magic links. Try: `npm run dev`, open `/login`.

This example demonstrates the cognitive principles in action: the first line provides the immediate action (Facts 1 and 3), steps are numbered (Fact 3), a concrete time estimate is given (Fact 4), and the win is highlighted (Fact 5).

Key Implementation Files

File	Purpose
skills/i-have-adhd/SKILL.md	Canonical rule definition and cognitive facts (lines 23-30)
extensions/i-have-adhd.ts	TypeScript entry point wiring the skill into the runtime
hooks/always-on.mjs	Hook maintaining skill persistence across sessions
tests/test_opencode_plugin.py	Test suite ensuring compliance with cognitive rules

Summary

• Working memory limitations necessitate leading with actions and restating state (Rules 1 and 5)
• The knowing-doing gap requires ending every response with one concrete next action (Rule 3)
• Initiation difficulty demands numbered steps and explicit starting points (Rules 1 and 2)
• Time blindness is countered by specific numeric time estimates in minutes (Rule 6)
• Dopamine scarcity requires making completed work visible to maintain motivation (Rule 7)

The skill creates a tight feedback loop between cognitive science and AI output formatting, ensuring every interaction aligns with empirically-supported ADHD cognition patterns.

Frequently Asked Questions

Where are the cognitive facts documented in the repository?

The five cognitive facts are explicitly listed in skills/i-have-adhd/SKILL.md between lines 23-30, where each fact is mapped to its corresponding behavioral rule.

How does the skill maintain ADHD-friendly formatting across multiple turns?

The skill uses hooks/always-on.mjs to persist the rule set for the active session, ensuring that every turn restates the current state and maintains the single-next-action format required by Facts 1 and 5.

Why must responses end with exactly one concrete action?

This requirement addresses Fact 2 (knowing is not doing) and Fact 3 (starting is hardest). By forcing a single, microscopic next step, the skill eliminates the executive function burden of deciding what to do next, which is the primary friction point for ADHD task execution.

Can users override these formatting rules?

Yes. According to the architectural logic in extensions/i-have-adhd.ts, higher-priority user requests (such as safety instructions) override the standard rules, though the system attempts to maintain ADHD-compliant formatting where possible even when overriding.

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