Keep learning with the companion guide.
Open this simple resource in a new tab, then use it at your own pace.
Open the free guide →A coding agent can be technically correct and still make the work harder to begin.
It may open with three paragraphs of context, introduce several side issues, repeat what you already know, and place the one command you need near the bottom. The answer contains the solution—but the solution is buried.
The open-source project i-have-adhd was created to change that output pattern. Its purpose is direct: shape a coding assistant’s responses so the next action appears first, multi-step work is numbered, progress stays visible, and unnecessary preambles disappear.
That idea is useful beyond one diagnosis, one coding tool, or one kind of brain. It raises a larger question for every AI builder:
**Is the system merely producing information, or is it helping a person take the next safe action?**
From a health-education perspective, that distinction matters. Attention-deficit/hyperactivity disorder is a neurodevelopmental condition that may involve persistent difficulty with attention, organization, task completion, restlessness, or impulsivity. Adults experience those challenges differently, and an output format is not a diagnosis or treatment. Still, communication design can either add friction or remove it.
This article looks at the skill as an accessibility and workflow tool—not as medical care.
01 — Put the action before the explanation
The central rule in the project is simple:
**Lead with the answer or the next action.**
When the useful response is a command, file path, setting, or code snippet, it should appear first.
Before
Your authentication flow includes several moving pieces. Before we change anything, it may help to think through the relationship between the middleware, token library, route configuration, and environment variables...
The reader may still be searching for the first thing to do.
After
`bash
npm install jsonwebtoken
`
Then edit src/auth.ts:42.
The explanation can follow when it is needed. This structure reduces what I call entry friction: the mental work required before the real work can begin.
For some adults with ADHD, starting, organizing, and sustaining attention can be difficult. The National Institute of Mental Health and the Centers for Disease Control and Prevention describe ADHD as a developmental or neurodevelopmental disorder that can affect attention, organization, and daily functioning. Clearer instructions do not treat ADHD, but they can make a task environment easier to navigate.
The same design can help: A founder switching between several business roles; A tired developer responding to an incident; A new employee learning an unfamiliar system; A person reading on a phone; A team member working in a second language; Anyone who needs the answer without a long runway.
That is why action-first writing should be treated as an inclusive option, not a label applied to every user.
The first action should be small
“Fix the application” is not a useful first action. “Open src/auth.ts and find line 42” is.
A strong first action is: Specific; Visible; Safe; Small enough to begin now; Connected to a clear result.
The skill’s guidance emphasizes a next action that can be completed in roughly two minutes. That does not mean the entire project takes two minutes. It means the reader can cross the gap between understanding and starting.
**Dr. Torrey’s note:** “A good instruction lowers the distance between intention and action. It does not shame the person for needing a clearer path.”
02 — Number the path and make progress visible
The repository does more than remove preambles. It provides a compact set of output rules designed to keep work bounded and visible.
1. Lead with the answer or next action Put the command, path, snippet, or decision first.
2. Number multi-step work Each step should contain one bounded action. A list such as 'update the package, inspect the environment, change the route, run tests, check the logs, and deploy' is not one step. It is a stack of hidden decisions.
3. End with one next action The response should not finish with several optional directions. It should leave one obvious move.
4. Finish the current issue before introducing another AI systems often notice adjacent problems. That can be useful, but raising every possible improvement can derail the task that brought the user there. Complete the current issue. Record the tangent. Return to it later.
5. Restate visible progress Examples: Step 2 of 4 complete; The test now passes; The file was created; Two items remain. Visible progress reduces the need to hold the entire state in working memory.
6. Use concrete time estimates 'A little while' is vague. 'About 10 minutes to update the configuration and 5 minutes to run the test' is more useful. Time estimates should be presented as estimates, not promises.
7. Show what now works After a change, say what improved. Do not only say, 'Done.' Say: 'The login route now returns a token, and the authentication test passes.'
8. Format errors as location, cause, and fix A calm error response might be: Location: `src/auth.ts:42`; Cause: the secret variable is missing; Fix: add `JWT_SECRET` to the local environment file and restart the server. This replaces drama with a repair path.
9. Keep lists short The skill recommends limiting lists to five items when possible. Longer material can be split into stages or sections.
10. Remove filler No automatic 'Great question.' No repeated recap after every answer. No 'Hope this helps' when the user still needs to act. The goal is not cold communication. It is **usable communication**.
What this approach does not mean
ADHD-friendly output should not become a reason to oversimplify everything. People may still want: Detailed explanations; Alternative options; Design reasoning; Risk analysis; Background context; Full documentation. The project itself includes exceptions for situations where the user asks for explanation, an action is destructive, repeated fixes fail, or the request is ambiguous. The better system is adjustable.
03 — Install carefully and customize for the person
The project is distributed under the MIT license and includes installation paths for several coding-agent environments, including Claude Code, Codex, Hermes, Gemini CLI, GitHub Copilot, Cursor, OpenCode, Pi, Zed, and other tools that read agent skills.
The safest adoption path
1. Read the skill file. Review what instructions it adds, whether it activates automatically, and how long rules remain active. 2. Install it in one test environment. Pick Hermes, Codex, or Claude Code using sample data. 3. Invoke it on demand. On-demand activation makes the behavior easy to compare. 4. Run the same task twice. Compare default output vs action-first output. 5. Customize before making it persistent. Add rules for destructive actions, file paths, and step limits.
Dr. Torrey’s ten-question review
1. Does the first line tell the user what to do? 2. Is each step one action? 3. Can the user see what is already complete? 4. Are time estimates concrete and honest? 5. Are side issues being contained? 6. Does the response explain risk before destructive action? 7. Can the user request more detail? 8. Can the mode be disabled easily? 9. Has the skill been tested with the actual user? 10. Is the tool supporting the person rather than defining the person?
How Lux Automaton can use the idea
This project fits naturally into several Lux systems:
- LANA: Offers an Action-First Mode that opens with the next move, limits active steps, and stores tangents separately. - Hermes: Loads the skill for selected users, projects, or sessions. - Lux Codex: Combines the style with current-step tracking, files changed, tests run, and approval state. - Workshops: Teaches participants how to request output formats matching how they work best.
The takeaway
An ADHD-friendly coding-agent skill does not diagnose, treat, or manage ADHD. It changes the communication layer. It puts the action before the preamble. It turns a wall of text into bounded steps. It makes progress visible. And it reminds AI builders that accessibility is about how the system helps a real person begin.
**“Smart tools should reduce friction without reducing the person.” — Dr. Torrey Dooley** **Learn AI. Build Tomorrow. Change the World. — LANA**
Your next action
Open the Action-First AI Output Planner included with this article. Choose one agent, one user, and one repeated task. Test the default output and the action-first output side by side. Keep the style only when the user says it helps.