The Five Facts About ADHD Driving i-have-adhd Rules: A Technical Breakdown

The i-have-adhd skill bases every output rule on five cognitive facts about ADHD—working memory limitations, the knowing-doing gap, initiation difficulty, uniform time perception, and dopamine scarcity—to transform documentation from passive reading into actionable tasks.

The ayghri/i-have-adhd repository provides a specialized framework for ADHD-friendly communication that moves beyond generic accessibility advice. Central to this system is skills/i-have-adhd/SKILL.md, which explicitly defines five facts about ADHD that drive formatting decisions ranging from sentence structure to list capping. These cognitive principles ensure content bridges the gap between comprehension and execution for readers with ADHD.

The Five Cognitive Foundations

The skill definition anchors all rules to these specific neurological and behavioral realities of ADHD.

1. Working Memory Is Small

Anything not visible on screen is effectively forgotten. This constraint drives the prohibition against asking readers to "keep in mind" information across sections. Instead, each instruction must be self-contained and immediately visible, eliminating the need to hold context in working memory.

2. Knowing the Answer Is Not Doing the Answer

Comprehension does not guarantee execution. This fact addresses the common ADHD gap between understanding a concept and implementing it. Content must include immediate, concrete next steps rather than assuming that knowledge alone translates to behavior.

3. Starting Is the Hardest Step

Initiation inertia represents the primary barrier to task completion. The first action presented must be obvious, small, and doable right now to overcome the neurological resistance to beginning. Vague entry points cause immediate abandonment.

4. Time Estimates Feel Uniform

ADHD affects temporal perception, rendering vague durations useless. Concrete time estimates—such as "≈ 15 minutes"—are required because "a bit of work" feels indistinguishable from "hours of work." Precise estimates provide the scaffolding necessary to initiate and sustain effort.

5. Dopamine Is Scarce

Visible progress is neurologically necessary for continued engagement. Finished pieces must be explicitly highlighted so readers can register achievement and generate the dopamine required to continue. Without explicit wins, the brain struggles to maintain motivation.

How the Facts Drive Formatting Rules in SKILL.md

In skills/i-have-adhd/SKILL.md, these five facts are explicitly declared in a dedicated section before the rules list. The configuration anchors each formatting requirement—lead-with-action, numbered steps only, concrete time estimates, suppressing tangents, and capping lists at five items—to specific cognitive limitations derived from the facts.

The following excerpt shows exactly where these principles are defined in the source:

# skills/i-have-adhd/SKILL.md (excerpt)

---
name: i-have-adhd
description: 'Shape output for a reader with ADHD…'
---
...

## What ADHD changes about reading

Five facts drive every rule below:

1. Working memory is small. Anything not on screen is forgotten…
2. Knowing the answer is not doing the answer…
3. Starting is the hardest step…
4. Time estimates feel uniform…
5. Dopamine is scarce…
...

Programmatic Implementation

Developers can reference these five facts programmatically to build ADHD-compatible interfaces or content generators. The repository demonstrates this approach by treating the facts as heuristics that guide automated formatting decisions.

ADHD_FACTS = [
    "Working memory is small.",
    "Knowing the answer is not doing the answer.",
    "Starting is the hardest step.",
    "Time estimates feel uniform.",
    "Dopamine is scarce."
]

def format_for_adhd(content: str) -> str:
    # prepend the first actionable line, then add concrete time estimate, etc.

    # using the five facts as guiding heuristics

    ...

Supporting Documentation

While SKILL.md contains the core five facts and rule definitions, additional context appears in related files:

• README.md – Provides an overview of the repository’s ADHD-friendly output style and use cases.
• GEMINI.md – Demonstrates practical application of the five-fact framework when generating Gemini-style responses.

Both files reference the cognitive principles established in SKILL.md, ensuring consistent implementation across different output contexts.

Summary

• Working memory constraints require all information to be visible and self-contained, prohibiting references to "previous steps."
• The knowing-doing gap necessitates immediate actionable instructions rather than explanatory text alone.
• Initiation difficulty demands that the first step be small, obvious, and immediately executable.
• Time blindness requires concrete temporal estimates (e.g., "5 minutes") instead of vague qualifiers.
• Dopamine scarcity mandates explicit visual highlighting of completed work to maintain motivation.

Frequently Asked Questions

What file contains the five ADHD facts in the repository?

The five facts are defined in skills/i-have-adhd/SKILL.md within the section titled "What ADHD changes about reading." This file serves as the central configuration for the i-have-adhd skill and maps each cognitive fact to specific formatting rules.

How do the five facts affect list formatting?

According to the SKILL.md implementation, lists must be capped at five items to respect working memory limitations. Additionally, lists must use numbered steps rather than bullets to provide clear progression, satisfying the dopamine scarcity fact by making progress visually explicit.

Why does the skill emphasize concrete time estimates?

Time estimates feel uniform to ADHD readers due to differences in temporal processing. Vague phrases like "soon" or "a while" fail to provide the necessary scaffolding for task initiation. Concrete estimates (e.g., "≈ 15 minutes") function as external executive function support, helping readers budget mental resources and overcome starting inertia.

Can these rules be applied outside of documentation?

Yes. The five facts provide a generalizable framework for any interface or communication requiring user action. The repository’s GEMINI.md demonstrates application to conversational AI responses, while the Python implementation pattern shows how to integrate these heuristics into custom applications, dashboards, or notification systems.

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