How the i-have-adhd Rules Bridge the Knowing-vs-Doing Gap in ADHD

The i-have-adhd skill eliminates the knowing-vs-doing gap by converting abstract information into structured, executable workflows using ten specific formatting rules defined in the source code.

The knowing-vs-doing gap—the paralysis between understanding a concept and actually executing it—represents a critical breakdown point for individuals with ADHD. According to the ayghri/i-have-adhd repository, this friction is where work stagnates. The skill framework defined in skills/i-have-adhd/SKILL.md systematically restructures how language models present information to transform static knowledge into immediate action.

The Friction Point Defined in SKILL.md

The source code explicitly identifies the core problem at line 26:

"Knowing the answer is not doing the answer. The friction between 'got it' and 'done it' is where work dies."

This declaration anchors the entire rule set. The ten rules that follow function as a translation layer, converting explanatory content into guided execution protocols that remove the mental overhead of deciding what to do next.

Rule 1: Lead with the Next Action

The first rule mandates that every response must begin with a concrete, immediate instruction. Lines 33-41 of SKILL.md demonstrate this principle with the example:

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

By placing the executable step at the very beginning, the rule eliminates the cognitive load of parsing through context to find the starting point. The user receives a direct command that requires no translation from abstract concept to concrete behavior.

Rule 2: Number Multi-Step Tasks

When tasks require multiple actions, the second rule requires discrete numbering to create bounded, achievable units. Lines 42-55 of SKILL.md illustrate this with a three-step sequence that isolates opening a file, swapping code, and running tests into separate, digestible actions.

This segmentation prevents the overwhelm of monolithic tasks. Each number represents a concrete finish line, allowing the reader to experience discrete completion states that maintain dopamine regulation and forward momentum.

Rule 3: End with One Concrete Next Action

Every explanation must conclude with a single, short-duration action that the reader can initiate immediately. Lines 57-63 of SKILL.md provide the template:

Next: run `npm test` and paste the first failing line.

This "under 2 minute" constraint ensures that the user never faces an ambiguous transition between reading and doing. The action is specific, time-bounded, and requires no additional planning or decision-making.

Rules 4-7: Sustaining Execution Momentum

The middle tier of rules addresses the environmental and cognitive factors that derail execution:

• Suppress Tangents (Rule 4): Postpones secondary issues to prevent attention fragmentation. The main fix completes before any "separately, there is a stale dependency" notifications appear.

• Restate State Every Turn (Rule 5): Maintains visible context of "where-am-I-in-the-process" so the reader does not need to hold progress in working memory. This compensates for ADHD-related working memory limitations.

• Give Specific Time Estimates (Rule 6): Provides concrete durations such as "about 15 minutes" to calibrate effort expectations and prevent the illusion that a task is "just a little work."

• Make Completed Work Visible (Rule 7): Delivers immediate feedback like "Login now works with magic links" to create tangible reinforcement that the action produced a result, boosting the dopamine response necessary for task continuation.

Rules 8-10: Formatting Constraints for Focus

The final rules enforce matter-of-fact tone, cap list lengths, and eliminate fluff. These constraints reduce cognitive load by removing emotional processing requirements and preventing the paralysis caused by excessive options or verbose explanations.

Technical Implementation Architecture

The rule set is implemented across several key files in the repository:

• skills/i-have-adhd/SKILL.md: Defines the ten rules and behavioral constraints that directly target the knowing-vs-doing gap.
• AGENTS.md: Maps the skill to runtime adapters for Claude, Codex, Pi, and other AI systems, ensuring consistent application across environments.
• opencode.json: Declares the OpenCode plugin entry point that activates the skill in compatible runtimes.
• INSTALL.md: Provides setup instructions for various execution contexts.

This architecture ensures that the bridge between knowledge and action is maintained regardless of the specific AI interface being used.

Practical Code Examples

The following templates demonstrate how the rules manifest in actual output:

Example 1: Package Installation Workflow

1. Run `npm install jsonwebtoken`.
2. Open `src/auth.ts` and replace the `verifyToken` implementation with the snippet below.
3. Run `npm test -- auth.spec.ts` to confirm the change.

*Next action (under 2 min):* Open `src/auth.ts` at line 42.

Example 2: Visible Success Confirmation

Login now works with magic links. Try it:

```bash
npm run dev

# Then open http://localhost:3000/login in the browser

Time estimate: About 5 minutes if the dev server is already running.

**Example 3: Tangential Issue Management**

```markdown
The main fix is completed. Separately, there is a stale dependency (`lodash`). Would you like to update it now? (Yes/No)

*Next action:* Reply "Yes" to start the update.

These examples illustrate Rule 1 (immediate action), Rule 2 (numbered steps), Rule 3 (concrete next action), Rule 6 (time estimates), and Rule 7 (visible success criteria).

Summary

• The knowing-vs-doing gap is explicitly defined in skills/i-have-adhd/SKILL.md line 26 as the friction between comprehension and execution.
• Rule 1 (lines 33-41) requires leading with the immediate next action, such as specific file edits or commands.
• Rule 2 (lines 42-55) mandates numbering multi-step tasks to create discrete, completable units.
• Rule 3 (lines 57-63) enforces ending every interaction with a single, sub-two-minute actionable step.
• Rules 4-7 address tangent suppression, state restatement, time estimation, and visible completion to sustain dopamine-driven momentum.
• The repository's architecture (AGENTS.md, opencode.json, INSTALL.md) ensures these rules apply consistently across different AI runtimes.

Frequently Asked Questions

How does the knowing-vs-doing gap specifically affect people with ADHD?

The knowing-vs-doing gap creates a paralysis point where individuals understand what needs to be done but cannot initiate the action due to executive dysfunction. For people with ADHD, this gap is exacerbated by working memory limitations and dopamine regulation issues, making the translation from "I understand" to "I am doing" cognitively expensive. The rules in skills/i-have-adhd/SKILL.md explicitly remove the decision-making and planning steps that typically stall execution.

Can these rules be applied outside of AI interactions?

Yes, the ten rules function as a general communication framework. The principles of leading with actions, numbering steps, bounding time estimates, and suppressing tangents apply to technical documentation, project management, and instructional design. The repository's INSTALL.md describes how to adapt these patterns for various runtime environments beyond AI chatbots.

Why is the "under 2 minutes" constraint critical for Rule 3?

The two-minute threshold aligns with behavioral psychology principles for overcoming initiation inertia. By guaranteeing that the next action requires less than 120 seconds, the rule bypasses the ADHD-related resistance to large, undefined tasks. Line 63 of SKILL.md enforces this constraint to ensure the user can start immediately without extensive planning or time commitment.

How does Rule 5 (Restate State) compensate for ADHD symptoms?

Rule 5 requires restating the current progress at every turn, which directly addresses working memory limitations common in ADHD. By externalizing the "where-am-I-in-the-process" context into the visible text, the rule prevents the user from losing their place or needing to re-read previous sections to reorient themselves, maintaining continuity across attention shifts.

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