i-have-adhd: When an AI Answer Becomes an Action
ayghri/i-have-adhd is a response-style skill and plugin for coding assistants. Its subject is not ADHD treatment; it is the design of assistant output for a reader who may lose momentum when an answer is buried under context, branching options, or vague status. This opening asks a practical question: how can an AI answer become easier to act on without becoming shorter at the expense of safety, completeness, or truth? The answer requires looking at the repository as a whole—its canonical rules, runtime adapters, session behavior, tests, and recorded evaluations.
A response style built for the gap between knowing and doing
Most technical answers fail in a way that is easy to miss. They can be correct and still leave the reader with no obvious starting point. A paragraph may identify several moving parts, suggest a likely fix, mention a test, and end with an invitation to investigate further. Nothing in it is necessarily false. Yet the reader must perform another task before work begins: extract the first action from the explanation.
The repository’s example makes that contrast concrete. Its “before” answer discusses an authentication flow, an older library interface, and possible follow-up work. Its “after” answer begins with a command, names the file to edit, gives three numbered actions, and ends by asking for the first failing line if verification does not pass. The important change is not that the second answer contains fewer technical ideas. It changes their order and their relationship to action.
That distinction defines the project. i-have-adhd says an ADHD-friendly response is not merely brief; it is shaped so a reader can act. A command, path, or code snippet belongs at the front when it is the useful starting point. A multi-step task becomes a sequence of bounded actions. The response closes with one next move rather than several open possibilities. Explanation remains available, but it no longer blocks the first step.
This is a small interface change with a larger consequence. An assistant does not only transfer information. In a coding task, it also helps the reader cross a boundary from understanding to execution. The project treats that boundary as part of the response design rather than as the reader’s private problem.
The design assumptions behind the name
The canonical skill describes five assumptions that drive its rules. It treats working memory as limited, so information that has left the screen is harder to recover. It separates knowing an answer from doing the answer, locating failure in the friction between those states. It treats starting as especially difficult, which makes the first action important. It rejects vague effort signals such as “this will take a bit,” because they do not give the reader a usable time boundary. Finally, it treats visible progress as important: a completed change that is buried inside a long explanation may not register as progress at all.
These statements explain why the project focuses on ordering, boundedness, continuity, and visible state. They are not interchangeable slogans. Each points to a different failure in a technical conversation.
If the main problem is retrieval, the response should keep the relevant state on the screen. If the problem is initiation, it should lower the cost of the first move. If the problem is hidden branching, it should expose a small sequence instead of presenting an undifferentiated set of possibilities. If the problem is uncertainty about effort, it should use a concrete estimate. If the problem is invisible feedback, it should say what now works and what remains.
That model also clarifies what the project does not claim. The repository presents these as design assumptions for shaping output, not as an independently validated clinical account of how every person with ADHD reads or works. Its title does not diagnose the reader. Its rules cannot establish that someone has ADHD, and the skill is not a treatment or a substitute for professional care. A careful description is therefore “the project is designed around these forms of friction,” not “these rules are medically proven to work for everyone.”
The distinction matters because accessibility patterns can become overconfident when their labels sound clinical. A useful response format can be adopted by people who do not identify with the label at all; the README even frames the goal as “No ADHD diagnosis needed!” At the same time, a reader’s preference for action-first output is not evidence of a diagnosis. The repository keeps the design target and the medical boundary separate.
The five assumptions are also not a demand for permanent compression. Later rules allow a full explanation when the reader requests one, require confirmation before destructive work, and ask a concise question when a request is genuinely ambiguous. The design is therefore better understood as friction-aware ordering: remove avoidable obstacles, but do not remove substance that the task needs.
One policy, several runtimes, and an evidence layer
The response rules are only one part of i-have-adhd. The repository also has to make those rules available inside different coding assistants, each with its own way of loading skills, registering commands, storing session state, or transforming context. This is why the project is organized around one canonical policy and several adapters rather than a single universal integration.
The canonical skill defines the behavior. Platform-specific metadata and adapters make that behavior discoverable and controllable. Some hosts support an explicit slash command. Some can load a context file. Some provide a startup hook for an opt-in always-on mode. Others expose an extension API that can save a session choice, show a status indicator, and reinsert rules after compaction. The project’s installation documentation covers these different routes, but the important relationship is architectural: the policy should remain recognizable while its lifecycle follows the host.
That separation protects user control. Installing a plugin should not silently change every response. The documented default is generally on-demand invocation, with always-on behavior requiring a separate opt-in such as a flag file or an explicit configuration choice. Turning the mode off also belongs to the interaction: “stop adhd mode” or “normal mode” ends the session behavior described by the skill. Installation, activation, and persistence are related decisions, not one indistinguishable switch.
The repository’s runtime map can be read as a chain:
The chain is also a warning against a superficial reading of portability. A list of supported hosts does not, by itself, prove that every host behaves identically. A manifest can point to a skill, while a hook controls when that skill is injected. An extension can preserve a saved choice across reloads, while another integration may rebuild the system prompt on every turn. Those mechanisms carry different risks and costs.
The repository addresses some of those risks directly. Its hooks are opt-in and designed to fail open: if the user has not created the always-on flag, if the skill file cannot be found, or if an optional hook operation fails, startup should continue without the extra rules. Its tests compare native Node, shell, and PowerShell hook behavior and check that frontmatter is removed before the rules enter the prompt. The richer Pi/OMP extension separates saved mode, visible status, and rules actually present in context, using ordered markers so a later disable can cancel an earlier injection. The OpenCode adapter solves a different problem by registering the skill path and command while optionally appending the rules to the system prompt each turn.
These choices reveal the project’s central trade-off. Lowering execution friction is valuable only if the mechanism remains controllable, sufficiently complete, and honest about uncertainty. A style that always cuts explanation can fail a requested walkthrough. A cause-first error format can pressure an assistant to name a cause that the evidence does not establish. A repeated system transformation may simplify lifecycle handling while adding prompt overhead. The repository’s own exceptions and tests are part of the answer because they define where the style must yield.
The evidence layer makes that boundary visible. The project includes cases for direct answers, debugging, explanations, destructive actions, ambiguity, progress, partial success, and medical boundaries. Its recorded run reported a higher weighted score for the candidate style than for the baseline, with the largest gains in actionability, concision, and state-reporting cases. But the same record says the release gate failed: the candidate still had blockers, one case required repository edits that the tool-less runner could not perform, and a partial-success response asserted a specific cause without enough evidence. Three trials and a same-family judge are useful signals, not a general efficacy study.
That is the right starting point for reading i-have-adhd. It is a compact policy for making assistant output easier to enter and continue, wrapped in a deliberately more complicated system of activation, state, portability, and verification. Its strongest promise is practical: put the next action, current state, and necessary boundaries where the reader can see them. Its strongest limitation is equally practical: no formatting rule can replace missing evidence, user consent, requested depth, or a reliable runtime contract. The rest of this series follows those dependencies to see how the project turns that promise into a working system.