The Strategy for Making the First Step Obvious in i-have-adhd

The i-have-adhd repository implements a strict ADHD-friendly communication protocol that requires every AI-generated response to begin with a concrete, executable action, eliminating introductory context and reducing cognitive barriers to task initiation.

The ayghri/i-have-adhd project is an open-source framework designed to optimize AI outputs for ADHD users by restructuring how instructions are presented. The strategy for making the first step obvious is architecturally enforced through a single skill definition file that dictates exactly how responses must be formatted to minimize activation energy.

The Three Architectural Rules

According to the source code in skills/i-have-adhd/SKILL.md, the strategy relies on three strict constraints that govern the first line of every output.

Lead with the Next Action

Lines 33-40 of SKILL.md mandate that the very first line must be a concrete, executable action rather than background context or explanations. This ensures the reader sees immediately what they can do right now without parsing through situational descriptions.

Make the Action Small and Doable Now

The strategy requires that initial actions be tiny, self-contained tasks completable in a couple of minutes (lines 27-28). This satisfies the "starting is the hardest step" principle by lowering activation energy to the absolute minimum.

Avoid Preambles

Any opening sentence that merely describes the situation is explicitly prohibited (lines 10-12). This rule strips away throat-clearing text so the reader's attention is drawn straight to the actionable item.

Implementation Across the Repository

While skills/i-have-adhd/SKILL.md serves as the source of truth, the strategy propagates through several key files:

• AGENTS.md – Maps the agent architecture and points to the skill file for runtime behavior
• hooks/always-on.mjs – Implements always-on behavior that respects the persistent rules from the skill file
• extensions/i-have-adhd.ts – TypeScript extension integrating the skill into supported runtimes
• README.md – Provides repository overview and navigation to the skill definition

Practical Examples

These examples demonstrate how the strategy for making the first step obvious transforms typical AI outputs into ADHD-friendly instructions.

Example 1: Code Review Comment

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

This line starts with a direct command (Run …), specifies the exact command to execute, and points to the precise file and line requiring modification.

Example 2: Guiding a Test Fix

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

Even when multiple steps are required, the very first step remains a single, obvious action ("Open …") rather than explanatory context.

Example 3: Prompt for a New Feature

Create a new file `src/utils/slugify.ts` and export a `slugify` function.

The request begins with an imperative verb (Create) and specifies the exact file and function to implement, making the initial work immediately clear.

Summary

• The strategy for making the first step obvious is architecturally defined in skills/i-have-adhd/SKILL.md through three strict formatting rules
• Every response must lead with a concrete, executable action in the first line (lines 33-40)
• Actions must be small enough to complete in minutes to minimize activation energy (lines 27-28)
• Preambles and background context are explicitly prohibited to reduce cognitive load (lines 10-12)
• The system integrates across AGENTS.md, hooks/always-on.mjs, and extensions/i-have-adhd.ts to enforce these constraints at runtime

Frequently Asked Questions

What file contains the strategy for making the first step obvious?

The core strategy is defined in skills/i-have-adhd/SKILL.md. This file specifies the architectural rules requiring AI outputs to lead with executable actions, keep tasks small, and eliminate preambles.

How does i-have-adhd enforce the "first step obvious" rule at runtime?

The rule is enforced through the skill definition file (lines 33-40) and implemented via hooks/always-on.mjs and extensions/i-have-adhd.ts. These components integrate the constraints into the AI's response generation pipeline, ensuring all outputs comply with the ADHD-friendly format.

Why does the strategy eliminate preambles and background context?

According to lines 10-12 of SKILL.md, preambles force readers to parse through explanatory text before finding actionable instructions. Removing them directs attention immediately to the executable step, which is critical for ADHD users who struggle with task initiation.

Can this strategy be applied outside of AI-generated responses?

Yes. While ayghri/i-have-adhd implements this for AI outputs, the pattern of leading with concrete, small actions and eliminating introductory fluff applies to any technical documentation, code review comments, or task management systems designed for ADHD-friendly workflows.

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