Background: A Pain Everyone Using AI Coding Tools Knows
When developers ask an AI assistant about a token verification error, the response often buries the actual answer in conversational filler:
> "Great question! Let me think about this. Your auth flow has a few moving pieces... One approach would be to update the package and rewrite that function."
The actionable instruction appears in the seventh sentence. i-have-adhd, a GitHub project that peaked at 9,236 stars in two months, solves this exact problem. The repository contains zero code, only a 143-line SKILL.md file that instructs AI coding assistants how to format responses.
After installation, the same question produces:
> Run npm install jsonwebtoken@latest, then edit src/auth.ts:42.
> 1. Open src/auth.ts
> 2. Replace verifyToken (lines 42-58) with the snippet below
> 3. Run npm test -- auth.spec.ts
> Next: paste the first failing line if any test fails.
The first line states the next action. Steps are numbered. There is no preamble or closer.
Why It Went Viral
The growth rate is unusual: 9,236 stars in two months for a 143-line Markdown file. Compare with stop-slop, a similar anti-slop skill that took three months to reach 2,000 stars, or llama.cpp, which needed two years to reach 50,000 stars. The reason is not technical novelty. The reason is universal pain: every developer using AI assistants has wrestled with "Great question!" filler and lost context by turn three.
The author's key insight was to derive rules from ADHD cognitive neuroscience rather than personal preference.
The Five ADHD Facts Underlying the Rules
The SKILL.md begins with five facts about ADHD brains, each generating a corresponding rule:
1. Small working memory — Anything not on screen is forgotten. Rule: lead with the next action on the first line. 2. Knowing is not doing — The core ADHD difficulty is not ignorance but initiation friction. Rule: number multi-step tasks; the first step must be small enough to do now. 3. Initiation is the hardest step — End with one concrete next step so the reader does not have to decide what comes next. 4. Time feels uniform — "A little work" and "a few hours" register identically. Rule: use specific minute estimates, not "in a while." 5. Dopamine is scarce — Visible progress matters. Rule: make wins visible so the brain receives a reward signal.
These facts come from the consensus ADHD cognitive neuroscience literature. The README cites *The Adult ADHD Tool Kit* by J. Russell Ramsay and Anthony L. Rostain, a CBT-based guide for adult ADHD.
The Ten Rules
From the five facts, ten rules emerge:
1. Lead with the next action 2. Number multi-step tasks 3. End with one concrete next step 4. Suppress tangents 5. Restate state every turn 6. Specific time estimates 7. Make wins visible 8. Matter-of-fact errors 9. Cap lists at 5 items 10. No preamble, no recap, no closers
Rule 8 is notable: AI assistants tend to dramatize errors ("Oops, the test failed, let's see what happened"). The rule replaces this with a direct statement: "auth.spec.ts line 23 failed, expected true got false."
These rules incidentally apply universal design principles: designing for the most vulnerable user often benefits everyone.
Pre-Send Check: A Linter for AI Output
The most practical component is the pre-send checklist:
Delete: 1. The first sentence if it announces what you are about to do 2. The last sentence if it asks "anything else?" or recaps what happened 3. Any "by the way" asides 4. Any vague hedge adverbs ("maybe", "perhaps", "probably") that add no information
Keep: Genuine uncertainty that reflects real limitations.
Replace: Idioms or metaphors with literal actions.
Verify: If a reader sees only the first and last lines, do they know (a) what to do next and (b) what just happened? If yes, send.
This is essentially a linter that runs before output is sent.
Deeper Insight: CBT for LLMs
The source material is a CBT-based ADHD toolkit. CBT's core logic is: rather than changing your ability, change your environment to compensate for ability differences. ADHD patients put keys by the door so they cannot forget them at departure. i-have-adhd inverts this: rather than changing the ADHD user's environment, change the AI's output environment to compensate for the user's cognitive profile.
The principle is shape matching, not brevity. The output shape must match how the ADHD brain processes information.
The Trade-Off: Context vs. Action Speed
A real trade-off exists. When AI outputs only "what to do" without "why," users lose:
- Context to judge whether the suggestion is correct
- Opportunities to learn domain knowledge
- Ability to detect AI errors
- Project: ayghri/i-have-adhd (MIT, 9,236 stars)
- SKILL.md: skills/i-have-adhd/SKILL.md
- Theory base: *The Adult ADHD Tool Kit* by Ramsay & Rostain (CBT for adult ADHD)
- Related: stop-slop
- Author blog: ayghri.me
The five-dimension scoring system mentioned in the article weighs correctness (35%), autonomy (25%), and actionability (20%). i-have-adhd scores fully on actionability but may lose points on autonomy. The trade-off may favor ADHD users but turn neurotypical users into executors rather than collaborators.
Alignment Intervention Layers
i-have-adhd represents a third form of alignment intervention:
| Layer | Example | Cost | Effect | |-------|---------|------|--------| | Training | RLHF reward tuning | Very high | Global | | Inference | Prompt engineering | Medium | Scenario-specific | | Output | i-have-adhd skill file | Very low | Output shape |
A 143-line Markdown file reshapes the output of a 744B-parameter model. This demonstrates that alignment can be bottom-up, not just top-down.
The Knowing-Doing Gap
The second ADHD fact is the deepest: knowing the answer is not doing the answer. The friction between knowing and doing is where work dies. This is not unique to ADHD. It is a fundamental human cognition problem. If running shoes are by the door, you run. If they are buried in the closet, you do not. If the answer is on the first line, you act. If the answer is in the seventh sentence, you may not.
The core insight is that AI output shape determines whether users can cross the knowing-doing gap. This applies to everyone who struggles between knowing and doing, which is everyone.