Why Restating State Every Turn Is Critical for ADHD-Friendly AI Interactions

Restating state every turn compensates for limited working memory in ADHD by explicitly anchoring the current progress in every message, eliminating the need for users to track hidden context across conversation turns.

The ayghri/i-have-adhd repository defines a specialized skill set for creating AI interactions that accommodate the cognitive profile of users with ADHD. At the heart of this system lies the architectural rule of restating state every turn, which addresses the working memory limitations that make multi-step task tracking difficult for this user group. This design choice transforms implicit conversation context into explicit, actionable progress markers.

The Cognitive Basis: Working Memory Limitations in ADHD

Why Implicit State Fails

People with ADHD often experience reduced working memory capacity, making it difficult to hold contextual information like "we are on step 3 of 5" between discrete messages. When an assistant assumes the user remembers prior context, it creates cognitive friction that can derail task completion. The i-have-adhd skill treats this not as a user limitation but as an interface design requirement.

How the Rule Is Implemented in the Codebase

According to the ayghri/i-have-adhd source code, this rule is codified in skills/i-have-adhd/SKILL.md at lines 73-77, which explicitly states that the reader "cannot hold 'we are on step 3 of 5' between messages" and therefore requires explicit restatement each turn.

The rule propagates across runtime implementations to ensure consistency:

• GEMINI.md – Imports the skill definition for Gemini runtime compatibility
• .opencode/command/i-have-adhd.md – Enforces the behavior for OpenCode sessions
• AGENTS.md – Guides agents to locate skill definitions for consistent enforcement across Claude, Codex, Pi, and OMP runtimes

This distributed enforcement ensures that regardless of which AI runtime processes the request, the state restatement behavior remains invariant.

Practical Examples of State Restatement

The following patterns demonstrate how multi-step interactions explicitly surface progress information on every turn, satisfying the rule from SKILL.md:

Initial state establishment:

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

Step 1 of 3 done: file opened. Next: edit the function as shown.

After user confirms completion:

Step 2 of 3 done: function updated. Next: run the test suite.

Final completion state:

All 3 steps completed. Login now works with the updated token logic. Try `npm run dev` and visit `/login`.

Benefits of Restating State Every Turn

By making the current step explicit in every response, the assistant achieves three critical ergonomic improvements:

• Keeps the user oriented – No hidden "where-we-are" context that might be lost during interruptions or context switches
• Enables rapid resumption – If the conversation is interrupted, the next message already contains the needed progress cue without requiring the user to scroll through history
• Reduces cognitive friction – The user can focus on the next concrete action rather than re-reading prior messages to infer status or decode implicit context

Summary

• Restating state every turn is architecturally defined in skills/i-have-adhd/SKILL.md lines 73-77 as a core response rule
• The rule compensates for ADHD-related working memory limitations by making progress explicit in every message rather than relying on conversational memory
• Implementation spans multiple runtime files including GEMINI.md and .opencode/command/i-have-adhd.md to ensure consistency across AI platforms
• Concrete benefits include improved spatial orientation within tasks, rapid recovery from interruptions, and reduced cognitive load during multi-step workflows

Frequently Asked Questions

What does "restating state every turn" mean in practice?

It means that every response from the assistant must explicitly mention the current progress (e.g., "Step 2 of 5 complete") and the next required action, rather than assuming the user remembers where they are in a multi-step workflow. As defined in the repository's skill files, the assistant must treat each message as potentially the first one the user is reading.

Why can't users with ADHD remember the state between messages?

Many individuals with ADHD experience working memory constraints that make it difficult to hold abstract positional information across separate conversation turns. The SKILL.md file explicitly notes that users "cannot hold 'we are on step 3 of 5' between messages," requiring the interface to externalize this tracking.

Which files in the repository enforce this rule?

The primary definition resides in skills/i-have-adhd/SKILL.md at lines 73-77, with runtime-specific reinforcement in GEMINI.md for Gemini compatibility and .opencode/command/i-have-adhd.md for OpenCode command definitions. The AGENTS.md file provides guidance for ensuring consistent enforcement across all supported runtimes.

Does this technique help users without ADHD?

Yes. While designed specifically for ADHD cognitive profiles, explicit state restatement improves usability for all users by reducing scrollback requirements and providing clear progress markers during complex multi-step operations. The technique follows universal design principles where accommodations for specific needs create better experiences broadly.

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