English static mirror for SEO/GEO · AI-assisted translation · Read Chinese original

i-have-adhd: How 143 Lines of Markdown and ADHD Neuroscience Cured AI's Rambling (9,200+ GitHub Stars)

Forum topic · ✨步子哥 · 2026-07-26

Summary

i-have-adhd is a viral GitHub project that reached over 9,200 stars in two months using only 143 lines of Markdown and zero code. Created by an ML PhD, it works as a skill file for AI coding assistants, restructuring their outputs based on ADHD cognitive neuroscience. The skill derives ten rules from five facts about the ADHD brain—limited working memory, the knowing-doing gap, difficult task initiation, poor time estimation, and scarce dopamine reward. Rules include leading with the next action, numbering multi-step tasks, ending with one concrete next step, capping lists at five items, and eliminating all preamble, recap, and filler phrases like Great question. Its centerpiece is a pre-send checklist: delete opening announcements, closing pleasantries, tangents, and vague adverbs, then verify the first and last lines alone convey the next action and current state. Grounded in Ramsay and Rostain's CBT-based Adult ADHD Tool Kit, the project reframes AI output quality as environmental design: matching output shape to how ADHD brains process information, prioritizing actionability over brevity. Critics note a trade-off—stripped context reduces users' ability to independently judge AI advice. The author positions it as a low-cost, output-layer alignment intervention compared to RLHF retraining, demonstrating community-driven alignment from the bottom up.

The Pain Every AI Coding User Knows

Ask Claude: "My auth flow is erroring, token verification fails." Typical response:

> Great question! Let me think about this. Your auth flow has a few moving pieces: the middleware, the token verification, and the cookie handling... One approach would be to update the package and rewrite that function... By the way, you might also want to look at your dependency versions overall. Hope this helps!

The actual answer is buried in sentence seven. Everything before it is greeting, restatement, and setup; everything after is filler.

This is the problem i-have-adhd solves. An ML PhD built it with 143 lines of Markdown and 0 lines of code, earning 9,236 stars in two months. It is a "skill" file that teaches AI coding assistants how to format their output. After installing it, the same question gets:

> 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.

First line: the next action. Numbered steps. One concrete next step at the end. No "Great question," no "Hope this helps."

Why It Went Viral

9,236 stars in two months for 143 lines of Markdown is an abnormal ratio. Comparable projects—stop-slop took three months to reach 2,000 stars; llama.cpp took two years for 50,000. The growth curve is nearly vertical.

The reason is not technical novelty—de-slop skills existed before. The reason is the pain point is universal. Every AI coding user has been exhausted by "Great question!" and has hunted for the actual instruction inside a wall of prose. But nobody built this—"make AI less verbose" sounded too simple to be worth doing. The author did, and made one smart choice: the rules are derived from ADHD neuroscience, not personal preference.

Five Facts About the Brain

The SKILL.md opens not with rules but with five facts about the ADHD brain, from which every rule is derived:

1. Working memory is small. Anything off-screen is forgotten. → Rule: *lead with the next action*. 2. Knowing the answer is not doing the answer. The core difficulty is initiation, not knowledge. → Rule: *number multi-step tasks*; the first step must be doable now. 3. Starting is the hardest step. → Rule: *end with one concrete next step*. 4. Time estimates feel uniform. "A bit of work" and "hours" register identically. → Rule: *specific time estimates* in minutes, not "a moment." 5. Dopamine is scarce. Visible progress matters; buried wins don't register. → Rule: *make wins visible*.

These come from the consensus of ADHD cognitive neuroscience (working memory deficits, executive dysfunction, dopaminergic reward shortfall). The README cites *The Adult ADHD Tool Kit* by J. Russell Ramsay and Anthony L. Rostain—a CBT-based adult ADHD coping guide.

Designing from neuroscience rather than preference is what separates i-have-adhd from all prior de-slop skills.

The Ten Rules

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 deserves a highlight: AI loves saying "Oops, the test failed, let's see what happened." No drama needed—just: "auth.spec.ts line 23 failed, expected true, got false."

These rules aren't arbitrary; each maps to an ADHD cognitive trait. Neurotypical users don't need them, but they don't hurt. Designing for the most vulnerable users often benefits everyone—universal design, practiced unintentionally.

The Pre-Send Check

The best part of SKILL.md is the Pre-send check at the end—four deletion rules and one verification:

Delete: 1. The first sentence, if it announces what you're about to do 2. The last sentence, if it asks "anything else?" or recaps 3. Any "by the way" asides 4. Any vague adverbs that add no information ("maybe," "possibly," "roughly")

Keep: hedging that carries real uncertainty—deleting it manufactures false confidence.

Replace: idioms and metaphors ("circle back," "kick off the ball," "get in sync") with literal actions.

Verify: if the reader reads only the first and last lines, do they know (a) what to do next and (b) what just happened? If yes, send.

This is a linter for AI output—not ten rules to memorize, but a checklist to run before sending.

Deeper Insight: CBT for LLMs

CBT's core logic: don't change your ability—change your environment to compensate. ADHD patients don't need to "try harder." They need keys by the door and pills next to the toothbrush. Environment design compensates for cognitive differences.

i-have-adhd does the same thing with the object reversed: instead of changing the ADHD user's environment, it changes the AI's output environment. Default AI output is designed for neurotypicals—preamble, context-building, closing pleasantries. Mildly annoying for them; work-death for ADHD users. This is not "make AI more concise"—it's "make AI's output shape match how the ADHD brain processes."

Shape matching. Not shorter—more actionable.

The Controversy: The Cost of Deleting Context

The sharpest criticism: i-have-adhd removes the context that helps you judge for yourself. When the AI only tells you *what* to do, not *why*:

  • You lose the context to judge whether the advice is correct
  • You lose the chance to learn the domain knowledge
  • You lose the ability to detect AI errors
This is a real trade-off: action speed vs. independent judgment. i-have-adhd bets on speed. For ADHD users—who lack the working memory independent judgment requires—this may be right. For neurotypical users, it risks turning them into "AI's executor" rather than "AI's collaborator."

A five-dimension scoring framework discussed alongside the project makes this explicit: correctness 35%, autonomy 25%, actionability 20%, and two more. "Good output" is not one-dimensional. i-have-adhd scores full marks on actionability but likely loses points on autonomy.

Connection to Sycophancy Research: Output-Layer Alignment

i-have-adhd is a third kind of intervention: no RLHF changes, no training data changes—just shaping output at the output layer via a skill file.

| Intervention layer | Example | Cost | Effect | |---|---|---|---| | Training | RLHF reward adjustment | Very high (retraining) | Global | | Inference | Prompt frameworks | Medium (prompt engineering) | Scenario-specific | | Output | i-have-adhd skill | Very low (143 lines of Markdown) | Output shape |

i-have-adhd proves output-layer intervention has extreme ROI. 143 lines of Markdown reshape the output of a 744B-parameter model without retraining. This is community-driven alignment—bottom-up, not top-down from OpenAI or Anthropic.

A Philosophical Observation: The Knowing-Doing Gap

The second of the five facts is the deepest: Knowing the answer is not doing the answer. The friction between knowing and doing is where work dies.

This isn't just ADHD. It's a fundamental problem of human cognition. You know you should exercise, write that paper, reply to that email—and you don't. The width of that gap is determined by environment design.

If the running shoes are by the door, you run. If the answer is in the first line, you act. If the answer is in the seventh sentence, maybe you don't.

AI's output shape determines whether the user can cross the knowing-doing gap. Not whether the answer is correct, but whether its shape makes action possible. This applies to everyone who struggles between knowing and doing—which is everyone.

Concept Lineage: Output Shape as an Alignment Dimension

Within the author's tracked lineage of "solve the problem at a different layer" (octopus RNA editing, slime mold externalized memory, bird quantum magnetoreception, SOPHIA division of labor, EvoThink atomic reasoning, Möbius RoPE topology intervention, mantis shrimp phononic shields), i-have-adhd adds a new dimension—the level of alignment intervention:

1. RLHF—training layer, change reward functions 2. Epanorthosis calibration—inference layer, change prompts 3. Beyond Sycophancy framework—inference layer, change interaction structure 4. i-have-adhd—output layer, change output shape

Four levels: decreasing cost, increasing customizability. Alignment doesn't always require retraining a model. Sometimes a skill file is enough.

---

Project: ayghri/i-have-adhd (MIT, 9,236 stars) SKILL.md: skills/i-have-adhd/SKILL.md Theoretical basis: *The Adult ADHD Tool Kit* by Ramsay & Rostain (CBT for adult ADHD) Related project: stop-slop Author's blog: ayghri.me

Tags

#ai-coding-assistants#adhd#prompt-engineering#llm-alignment#developer-tools#github-projects#cognitive-science#output-design

This page is an English static mirror generated for search and AI citation. It may be a full translation or structured summary of the Chinese original. Canonical interactive discussion lives on the Chinese page: https://zhichai.net/topic/178503693