The Friction Model Behind the Rules
The key design problem in i-have-adhd is not how to make an assistant say less. It is how to reduce the distance between a correct answer and a reader who can actually begin, continue, and finish the work. This chapter examines the five assumptions the project uses to define that distance, then turns them into tests for judging an assistant response. The result is a design model, not a clinical theory: it explains the shape of the repository’s rules while leaving their broader medical and behavioral claims appropriately limited.
Why correct information can still be hard to use
Imagine a coding answer that diagnoses a problem accurately. It names the relevant files, explains three possible causes, recommends a likely fix, mentions a related dependency, and suggests several tests. For an experienced reader with plenty of time, that may be useful. For a reader who is already struggling to start, it creates a second problem: the answer itself must be organized before the technical work can begin.
The project treats that extra organization as execution friction. Its canonical skill describes five conditions that shape the reader’s experience. They are best understood as connected points in a process, not as five statements about a person.
The first is limited working memory. The skill says that anything not on screen is easily forgotten and warns against asking the reader to keep an important fact in mind. In a conversation, this means that a state such as “the schema is already updated, but the backfill has not run” should not be left as an implicit conclusion from several earlier turns. If the current state matters to the next action, the response should put it where the reader can see it.
The second is the gap between knowing and doing. An answer can make sense without making a task startable. “Update the authentication flow and run the tests” communicates an intention, but it leaves the reader to decide which file to open, what to change first, and which test provides the quickest feedback. The project therefore treats the first action as part of the answer, not as a trivial detail that the reader will infer.
The third is startup friction. The skill calls starting the hardest step. Whether or not that description applies equally to every reader, it gives the project a clear design target: reduce the cost of the first move. A command at the top of a response, a named path, or one small bounded action can do that more directly than an introductory paragraph about why the task is important.
The fourth is vague time signaling. The skill says that “a bit of work” and “a few hours” can register as if they were the same when the estimate has no concrete boundary. Its answer is not a promise of precise duration. It asks for a useful estimate in minutes or hours, with conditions when necessary. “About 15 minutes if the tests already cover this; longer if the missing coverage must be added” gives the reader a way to size the next commitment. It does not pretend to know the exact duration of work the assistant cannot observe.
The fifth is invisible progress. The project treats dopamine as scarce and argues that buried wins may not register. In response design, this becomes a visibility problem. If a change has been made, the assistant should say what now works. If a check has passed while another has failed, the status should show both. The reader should not have to search a long reply to discover that one part of the task is complete.
These conditions interact. Limited working memory makes state restatement useful. The gap between knowing and doing makes a first action useful. Startup friction makes that first action need to be small and obvious. Concrete estimates help the reader decide whether to begin now. Visible progress supplies feedback after beginning. A response that addresses only one point can still fail at the next transition: a numbered list may be clear but too long; a direct command may start the task but leave the reader unsure what passed; a concise status may hide a safety condition.
That is why the repository’s opening claim rejects “brief” as a sufficient description. Brevity measures how much text is present. The project is concerned with whether the text has the right shape for movement through a task. Sometimes the shortest answer is a number. Sometimes it is a command. Sometimes it is a careful explanation with enough context to prevent a dangerous mistake. The relevant question is not “How few words can be used?” but “Which information must be visible at this point for the reader to act correctly?”
The answer also depends on the work. A one-line calculation may need no numbered sequence. A database migration needs checkpoints and rollback conditions even when the reader prefers compact output. A requested walkthrough needs enough explanation to build a mental model. The friction model can guide the order and grouping of information, but it cannot erase task requirements.
From friction assumptions to response tests
The five assumptions become useful when they are translated into observable questions. An assistant response shaped by i-have-adhd can be tested at several boundaries.
First, can the reader identify the next action without extracting it from a preamble? This tests the gap between knowing and doing. If the answer concerns a file edit, the file or command should appear early. If it concerns a decision, the response can state the recommended first check or the one fact that blocks a safe choice. “Here are several considerations” is not automatically wrong, but it should not force the reader to construct the first move from scratch.
Second, can the reader tell how many actions are required and what each action contains? This tests working memory and hidden branching. The project’s numbered-step rule says that each step should be bounded and that a multi-step task should use the fewest steps that still work. A bounded step has an observable end: open a file, replace a function, run a named test, inspect the first failing line. A step that says “review the whole system and fix anything related” is not bounded simply because it appears as one bullet.
Third, can the reader estimate the immediate commitment? This tests time signaling. The estimate should be concrete enough to distinguish a quick check from a larger change, but it should remain conditional when the assistant lacks information. A specific estimate is not a license to invent confidence. If the repository has no test coverage, the response should say that the estimate assumes coverage exists or explain the additional work that changes it.
Fourth, can the reader see what has already changed and what remains uncertain? This tests visible progress and state retention. A useful status line might say, “The schema change is complete; the new column is still empty; next, run the backfill.” It does three jobs without a recap: records a completed state, identifies the remaining state, and points to the transition. An error report can do the same when its cause is established: name the location, state the cause, give the smallest fix, and name the verification.
Fifth, does the response keep its working set small without removing material the task needs? This is where the project’s list cap and tangent rule matter. A response can group related items and show the most relevant ones first, while retaining the ability to surface other information when it becomes necessary. The goal is not to hide a long migration plan, a safety warning, or a requested explanation. It is to prevent peripheral concerns from competing with the issue currently being solved.
These tests expose a useful difference between cognitive lightness and operational readiness. A short answer can be cognitively light but operationally poor if it omits the file, the condition, or the verification. A longer answer can be operationally strong if it gives a clear starting point, explains the choices that matter, and keeps the current state visible. The project’s rule is therefore about structure and priority, not a fixed word count.
The diagram shows a design loop rather than a guaranteed causal chain. A response begins by addressing the point where the reader is stuck. It exposes a first action, keeps the work bounded, gives a usable estimate, and reports the outcome in a way that supports the next transition. The dashed path matters: a request for explanation or a safety-sensitive operation can change the response shape before compactness is applied.
This is also why the project treats exceptions as part of the model. The default rules favor directness, but they do not outrank the task. If the reader asks for a detailed explanation, the assistant should explain fully and use headings so the reader can return to the argument. If an action is destructive, confirmation comes first. If the request is genuinely ambiguous, one blocking question is better than a guessed path. If the last three debugging attempts have failed, the assistant should stop iterating and name the assumption that may be wrong rather than producing another confident checklist.
The exceptions preserve a distinction between avoidable friction and necessary friction. A preamble that delays a known next action is avoidable. A warning before deleting data is necessary. Repeating state that the reader cannot otherwise recover is useful; repeating a conclusion without adding information is not. Explaining a mechanism in response to an explicit request may be longer than the default, but that length serves the reader’s stated goal.
The model has an important uncertainty boundary of its own. The repository describes the five assumptions as what “drive every rule,” but it does not provide a clinical study, a sample of readers, or a comparison that isolates one rule from another. Its README credits a book as loose inspiration, not as a reported validation of the implementation. The safest interpretation is that i-have-adhd is an engineered response policy motivated by a set of plausible user-experience problems. The policy can be useful to people with many different attention and workflow preferences, but using it does not demonstrate that any reader has ADHD.
That restraint improves the engineering model. Once the assumptions are treated as design hypotheses rather than diagnoses, they can be inspected at the level the repository actually supports. Does the output make the first action visible? Does it preserve the current state? Does it distinguish a known cause from a guess? Does it remain safe when the task is destructive or the requested format is strict? These are observable questions. They are also more actionable than a broad claim that a style is universally “ADHD-friendly.”
The friction model therefore leads to bounded choices, not an ever-growing checklist. Every new instruction competes for attention. If a rule helps the reader cross a real boundary, it earns its place. If it merely repeats a nearby rule, it adds the very load the project is trying to reduce. This is the standard by which the repository’s ten rules should be read: not as decoration, and not as a promise of diagnosis, but as a compact set of interface decisions that will later have to survive activation, session state, and evaluation.