10 Rules for ADHD-Friendly Output in Coding Agents

ADHD-friendly output in coding agents requires strict structural rules—lead with executable actions, number every step, restate state each turn, and eliminate conversational filler—to reduce working-memory load for readers with ADHD.

The ayghri/i-have-adhd open-source skill provides a deterministic framework that shapes every response from a coding assistant to support users with ADHD. Defined in the canonical skills/i-have-adhd/SKILL.md, these ten input-output (IO) rules prioritize cognitive accessibility by making progress visible and actions explicit.

The 10 Rules for ADHD-Friendly Output

1. Lead with the Next Action

The first line of any reply must be a concrete, immediately executable action such as a command, file path, or code snippet. No preamble or background context is allowed before the action. According to the source code in skills/i-have-adhd/SKILL.md (lines 33‑36), the response must start with the answer, not with phrases like "Sure, I can help."

Run `npm install jsonwebtoken@latest`, then edit `src/auth.ts:42`.

2. Number Multi-Step Tasks

When a solution requires more than one step, present a numbered list where each item represents a single bounded action. As implemented in ayghri/i-have-adhd (lines 42‑46), this format prevents the reader from losing track of sequential dependencies.

1. Open `src/auth.ts`
2. Replace `verifyToken` (lines 42‑58) with the snippet below
3. Run `npm test -- auth.spec.ts`

3. End with One Concrete Next Step

If any work remains, the final line must state a single, short-duration next action that takes under two minutes to complete. This rule (lines 57‑62) ensures the reader never faces an ambiguous "what now" moment at the end of a turn.

Next: run `npm test` and paste the first failing line.

4. Suppress Tangents

The assistant must finish addressing the current issue before mentioning any secondary issues. Secondary items should be offered as separate questions rather than mid-response digressions (lines 64‑70). This prevents context-switching fatigue common in ADHD workflows.

5. Restate State Every Turn

Because readers cannot reliably retain "step 3 of 5" across conversation turns, the assistant repeats the current progress and the next action in every response (lines 73‑78). This State Restatement principle compensates for working-memory limitations by making the conversation state explicit at each interaction.

6. Give Specific Time Estimates

All time estimates must use concrete units—minutes or hours—rather than vague phrases like "a while" or "soon" (lines 82‑86). Specificity reduces anxiety and helps users allocate attention resources effectively.

7. Make Completed Work Visible

When a change succeeds, display the visible result (e.g., a runnable command or file diff) instead of a hidden internal recap (lines 89‑94). Visibility confirms progress without requiring the reader to infer success from absence of error.

8. Matter-of-Fact Tone for Errors

Error messages must omit emotive language such as "uh-oh," "oops," or "unfortunately." Instead, state the cause and fix directly (lines 96‑101). This tonal discipline prevents emotional distraction and keeps focus on resolution.

Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request.

9. Cap Lists to Five Items

Long enumerations are trimmed to five visible items; additional items are retained internally or shown only on request (lines 103‑107). This constraint prevents decision paralysis and cognitive overload from excessive options.

10. No Preamble, Recap, or Closing Pleasantries

Responses start with the answer and end when the answer is complete. Eliminate phrases such as "great question," "hope this helps," or "let me know if you need anything else" (lines 109‑115). This Hard Boundary rule prevents the dilution of actionable content.

When to Override the Rules

The skill permits temporary overrides only in specific circumstances: explanatory asides, safety confirmations, diagnostic dead-ends, clarification questions, or when a rule would prevent delivering the answer itself (lines 121‑128 in SKILL.md). These exceptions are narrowly scoped to ensure the ADHD-friendly format remains the default mode of operation.

Implementation Examples

The following patterns demonstrate compliant output for common coding agent scenarios:

Single-step action:

Run `npm install jsonwebtoken@latest`, then edit `src/auth.ts:42`.

Multi-step workflow:

1. Open `src/auth.ts`
2. Replace `verifyToken` (lines 42‑58) with the snippet below
3. Run `npm test -- auth.spec.ts`

Error handling:

Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request.

Implementation files for various runtimes include:

• skills/i-have-adhd/SKILL.md — Canonical source of truth
• .cursor/skills/i-have-adhd/SKILL.md — Cursor-compatible copy
• AGENTS.md — Runtime mappings and entry points
• INSTALL.md — Integration instructions for coding assistants

Summary

• ADHD-friendly output in coding agents follows ten deterministic IO rules defined in ayghri/i-have-adhd.
• Always lead with executable actions, number multi-step tasks, and end with a concrete next step under two minutes.
• Restate progress every turn to compensate for working-memory limitations.
• Suppress emotional language in errors and cap lists at five items to prevent cognitive overload.
• Keep responses free of preambles, recaps, and pleasantries to maximize information density.

Frequently Asked Questions

What is the source of truth for the ADHD-friendly output rules?

The canonical definitions reside in skills/i-have-adhd/SKILL.md within the ayghri/i-have-adhd repository. This file specifies the ten rules with line-level precision, including the constraint that responses must start with executable actions (lines 33‑36) and end without pleasantries (lines 109‑115).

When should a coding agent break the ADHD-friendly output rules?

Override the rules only for safety confirmations, diagnostic dead-ends, necessary explanations, clarification questions, or when a rule would prevent delivering the answer itself. These exceptions are documented in SKILL.md (lines 121‑128) and should remain temporary deviations rather than default behavior.

How does restating state every turn help users with ADHD?

Rule 5 requires repeating the current progress and next action in every response because readers with ADHD often cannot retain "step 3 of 5" across conversation turns. This State Restatement reduces working-memory load by making the conversation context explicit at each interaction point.

Where can I install this skill for my coding assistant?

Installation instructions are provided in INSTALL.md in the repository root. The skill supports multiple runtimes, with specific entry points mapped in AGENTS.md and a Cursor-specific copy maintained at .cursor/skills/i-have-adhd/SKILL.md for compatibility with the Cursor editor.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}