From Request to First Move
i-have-adhd turns its friction model into a concrete response contract: put the useful action first, make multi-step work bounded, and end with one clear next move. This chapter focuses on that transformation rather than on the project’s runtime adapters. The practical test is simple: after reading a technical answer, can someone start the right task without first reorganizing the answer in their head?
Put the action where the answer starts
The repository’s clearest example concerns an authentication flow. A conventional answer may open with a friendly preamble, describe several moving parts, point out that a library API is old, suggest updating a package, and mention tests that should be run. That explanation can be technically sensible. Its weakness is positional: the reader has to search through the diagnosis to discover what to do first.
The i-have-adhd version puts the first move at the top. It tells the reader to install the relevant package, points to the file and function that need attention, gives a short numbered path, and names the test that checks the change. The example does not remove the technical context; it makes the context serve the action. The reader can begin with the command or file location and return to the explanation only when it becomes useful.
That is what “action first” means in this project. It is not an instruction to issue a command before understanding whether the command is safe or appropriate. It is an ordering rule for a case where the next action is known. If the answer is a command, path, or snippet, the project places it first. If the task is a decision, the first line may instead name the fact to check or the condition that blocks a safe choice. The form changes, but the purpose stays the same: do not make the reader extract the entry point from an essay.
This ordering helps at the boundary between knowing and doing. Consider three versions of the same technical advice:
- “The authentication flow has several moving parts, so review the middleware, token verification, and cookies.”
- “The token verification function is using an older library interface; update that function and run the auth test.”
- “Run the package update, open the authentication file, replace the verification function, and run the focused test.”
The first gives orientation but no start. The second gives a likely remedy but leaves the path partly implicit. The third makes the entry point and sequence visible. It can still be wrong if the diagnosis is wrong, but its structure makes that error easier to inspect: the reader knows which assumption the proposed change depends on and which check should provide feedback.
Action-first ordering is therefore not a substitute for correctness. It is a way to expose the handoff from an explanation to an operation. A command at the top is useful only if it is the right command, appropriate to the user’s environment, and safe under the stated conditions. The response-style rule does not outrank those requirements.
The same principle applies to a direct question. When the task asks for a calculation, the answer should not begin with a reflection on how to calculate. When it asks for a code block only, prose should not be added because the style prefers visible context. When it asks for a detailed explanation, the first useful action may be to establish the model the reader needs before recommending a change. The project’s own exception rules make this explicit: a user’s output contract and request for explanation can override the default compact path.
The first action also has a scale. “Fix the auth system” is technically an imperative, but it is not a useful starting point. “Open the authentication file and inspect the verification function” is smaller and observable. A reader can tell when that action is complete. If the next move depends on what they find, the response can say what evidence to bring back rather than pretending that the whole task has one predetermined path.
That last point matters for assistants that can inspect or modify repositories. Action-first output should not push agent-owned work back to the user. If the assistant has access to the repository and the task authorizes an edit, the assistant should do the edit and report the result. If the assistant lacks access, it should give the smallest user-executable step instead of narrating an action it cannot perform. The response shape is meant to reduce friction, not disguise a capability boundary.
Bound the path without hiding the work
Once the first action is clear, the next problem is sequence. Rule 2 of the skill says that multi-step work should be numbered, with each step representing one bounded action. The point is not visual decoration. Numbering makes order and completion visible; boundedness prevents a single line from hiding several decisions, tools, and failure conditions.
A useful step has a recognizable end. In the repository’s example, the path can be expressed as:
- Open the authentication file.
- Replace the verification function in the indicated location.
- Run the focused authentication test.
Each line is still compact, but it carries a different state transition. The first locates the work. The second changes it. The third asks the system for evidence. A reader who stops after the first step can report that state accurately; an assistant responding on the next turn does not need to guess whether the edit has happened.
A step that contains several hidden actions creates the opposite effect. “Open the file, find the function, replace it, update dependencies, run all tests, and investigate anything else that looks stale” may look like one line, but it demands a sequence of decisions and expands the task without a visible boundary. The project’s instruction to avoid repeated “and then” clauses is a simple test for this problem. When a step contains multiple transitions, split it or remove the transition the reader does not need yet.
At the same time, the project does not ask the assistant to turn every answer into a long checklist. It says to use the fewest steps that still work. That phrase carries a trade-off. Too few steps hide branching and make progress hard to report. Too many steps create a new working-memory burden and invite the reader to abandon the path before starting. The right sequence preserves the decisions and checks that affect success while folding trivial movements into the action that owns them.
Rule 9 adds a display constraint: visible lists should generally be capped at five items per group. This is not a limit on the assistant’s analysis or on the amount of information a complex task may require. Related items can be grouped, lower-priority details can wait until they matter, and safety or correctness information must not be omitted merely to hit a number. The cap controls the visible working set. It does not authorize the assistant to hide a rollback condition, a destructive side effect, or a prerequisite.
The path in the diagram has a beginning, a check, and a continuation. It also has a side condition: detail or safety can change the path before a compact sequence is offered. That side condition is essential. A response that omits necessary explanation may be easy to start but unsafe to follow. A response that asks for confirmation before a destructive command may delay action, but that delay is part of correct execution.
Verification belongs inside the path because an unverified change is not the same as a completed task. The repository’s example names a focused test rather than vaguely saying “check that it works.” A focused check shortens the feedback loop and gives the next response a concrete state to report. If it fails, the reader can provide the first failing line. If it passes, the assistant can state what now works and decide whether a broader check is justified.
The final next action closes the loop without opening five new ones. The skill asks for one concrete action that can be done in under two minutes when something remains open. That might be “run the focused test,” “open the file,” or “paste the first failing line.” The point is not that every technical task can be completed in two minutes. The point is to make the next transition small enough that the reader does not have to choose among several equally vague invitations.
This rule changes the tone of an ending. “Hope this helps. Let me know if you want to explore dependencies, update the README, review the architecture, or run more tests” leaves the reader with a menu. “Next: run the focused test and paste the first failing line” leaves them with a path. The latter is not always the right sentence—if the task is already complete, no artificial next action is needed—but when work remains, one explicit move is more useful than a collection of open doors.
The same structure scales to larger work. A migration may need more than five visible items, but it can present the immediate phase first, group related checks, and surface later phases when the current one is complete. A complex plan may require rollback points and compatibility stages; the assistant should preserve them rather than compressing the plan into a misleading three-line summary. The project’s long-form-request and complex-plan evaluation cases exist precisely to test whether the style can remain structured without suppressing necessary detail.
That is also where explicit output contracts take priority. A user who asks for “only the code block” has specified a format that the assistant must honor. Adding an action-first preamble would violate the task even if it followed the skill’s default. A user who asks to be walked through OAuth with PKCE has requested enough detail to build a mental model; a short command followed by “next” would not satisfy the request. The style should shape the explanation’s order and clarity, but it should not replace the requested medium or depth.
Safety creates a stronger override. If the next action would delete files, alter production data, force a push, or perform another destructive operation, the assistant should not make the action frictionless by skipping confirmation. The repository explicitly says to confirm first. A read-only preview can be the correct first action. In this case, a small delay protects the reader’s control over an irreversible transition.
Ambiguity creates another override. When the target, environment, or deployment mechanism is unknown, guessing a numbered path can make the answer look actionable while increasing risk. The project recommends one concise blocking question for real ambiguity. That question is not a tangent; it is the smallest action needed to make the later path valid.
The result is a practical test for an i-have-adhd response. Hide the explanation and look only at the first line: can the reader tell where to begin? Look at the numbered steps: does each have a clear boundary and an order? Look at the verification: does it produce evidence rather than reassurance? Look at the ending: is there one useful next transition, or a new list of choices? Then ask whether the answer’s compactness has removed anything the task, safety boundary, or user’s requested format requires.
An answer passes this test when it is both cognitively light and operationally complete. It does not ask the reader to reorganize the response, but it also does not pretend that every task is a short checklist. The project’s action-first rules are strongest when they expose the next real transition and leave the necessary evidence visible. Once the first move has been taken, however, a new problem appears: the reader must know what state the work is in. That is why continuity deserves its own design mechanism.