# How i-have-ADHD Handles Working Memory Limitations in AI Output

> Discover how i-have-ADHD manages working memory limits by creating self-contained AI responses that eliminate the need for user context retention across turns.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-09-11

---

**i-have-ADHD treats working memory constraints as an architectural boundary, enforcing self-contained responses that never require users to retain context across turns.**

The open-source project `ayghri/i-have-adhd` is a Claude/Codex skill designed specifically for users with ADHD. It addresses working memory limitations by treating cognitive constraints as hard engineering requirements rather than optional formatting suggestions. According to the source code, the architecture ensures every AI output is immediately actionable without requiring the reader to remember previous context or scroll back to earlier messages.

## Architectural Rules for Working Memory Constraints

The skill defines its constraints in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and enforces them through the `hooks/always-on.mjs` injection system. These rules operate on the principle that **anything not visible on the screen is forgotten** by readers with ADHD.

### Self-Contained Response Design

The foundational rule in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) explicitly forbids phrasing that relies on the user remembering previous context. The directive states: *"Working memory is small… Do not ask the reader to 'keep in mind X.'"* This architectural decision prevents the model from assuming the user can hold state between messages.

Instead, every response must restate the current position and next action. As implemented in the ruleset: *"The reader cannot hold 'we are on step 3 of 5' between messages. Restate it."* This guarantees that users never need to recall where they left off in a multi-turn interaction.

### Leading With Executable Actions

To minimize cognitive load, the first line of every response must be a concrete, executable step. The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) specification mandates: *"The first line is something the reader can do… If the answer is a command, path, or snippet, it goes first."*

This structural requirement ensures the actionable piece remains visible without scrolling. When a user receives a response, they see the immediate next step—whether it is a terminal command, file path, or code snippet—before any explanatory text.

### Bounded Enumeration and Time Estimation

When tasks require multiple steps, the skill formats them as numbered lists where each step represents a single bounded action. The rules specify: *"If the work takes more than one step, write a numbered list. Each step is one bounded action."*

Additionally, to prevent vague mental arithmetic, the system provides concrete time estimates in specific units (minutes, seconds) rather than subjective qualifiers like "a bit of work." The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file explicitly directs: *"Give specific time estimates."*

### Visual Working Set Limitations

The architecture caps visible lists at five items, with additional items held internally and revealed only on request. As noted in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md): *"Cap lists to 5 items… keep the visible working set small."* This constraint matches empirical working memory capacity limits (typically 4±1 chunks).

After completing work, the model highlights the result immediately to create a visual win that does not require recalling previous output. The rule states: *"Make completed work visible."*

## Implementation in the Codebase

The enforcement mechanism resides in `hooks/always-on.mjs`, which automatically injects the full ruleset at session start when the user enables always-on mode.

```bash

# Enable ADHD-mode for all Claude sessions

mkdir -p ~/.claude
touch ~/.claude/.i-have-adhd-always

```

When `~/.claude/.i-have-adhd-always` exists, the hook reads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), strips its YAML front-matter, and streams the entire constraint set to the LLM before the first user token. This ensures the model understands working memory limitations from the initial interaction:

```python

# From hooks/always-on.mjs (conceptual flow)

async function injectRules(session) {
    const skillMd = await readFile('skills/i-have-adhd/SKILL.md', 'utf-8');
    const rules = stripYamlFrontmatter(skillMd);
    session.systemPrompt += rules;  # Injected before generation

}

```

The response format follows a deterministic structure that transforms cognitive bottlenecks into predictable output patterns:

```json
{
  "content": "Run `npm install jsonwebtoken`.\n\n1. Open a terminal.\n2. Execute the command above.\n3. Verify the package appears in `package.json`.\n\nStep 1 of 3 done: package installed. Next: import the token verifier in `src/auth.ts`."
}

```

This example demonstrates the architectural requirements: the first line provides the immediate command, the numbered list splits work into bounded actions, and the closing sentence restates the current step and next concrete action.

## Summary

- **Never assume retained context**: The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) rules explicitly forbid asking users to "keep in mind" information from previous turns.
- **Lead with action**: Every response must start with an executable command, path, or snippet visible without scrolling.
- **Restate state continuously**: Each message repeats the current step and next action since users cannot hold "step 3 of 5" in working memory.
- **Limit visual working sets**: Lists are capped at five items to match cognitive capacity limits.
- **Automatic enforcement**: The `hooks/always-on.mjs` system injects these constraints at session start when `~/.claude/.i-have-adhd-always` is present.

## Frequently Asked Questions

### What specific working memory limitations does i-have-ADHD address?

The project addresses the limited capacity to hold information in mind when it is not visually present. According to [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), users with ADHD quickly forget anything not visible on the screen, so the architecture eliminates dependency on memory across turns and eliminates the need to scroll back to recall context.

### How does the always-on hook enforce working memory rules?

The `hooks/always-on.mjs` file checks for `~/.claude/.i-have-adhd-always` at session start. When present, it reads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and prepends the full ruleset to the system prompt. This injection happens before the model generates any tokens, ensuring compliance with working memory constraints from the first interaction.

### Can I temporarily disable ADHD mode after enabling it?

Yes. Sending the command `echo "stop adhd mode"` or simply stating "stop adhd mode" in the chat disables the rules for the current session. The model confirms deactivation in a single line and reverts to default response patterns that do not enforce the working memory constraints defined in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md).

### Why are responses limited to five items per list?

The five-item cap aligns with empirical working memory capacity (4±1 chunks). [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) explicitly states this limits the "visible working set" to prevent cognitive overload. Additional items remain available internally and are revealed only upon explicit request, ensuring the screen never presents more information than the user can actively process.