How Does i-have-adhd Ensure the Reader Knows What Happened? Source Code Breakdown

The i-have-adhd skill guarantees the reader knows what happened by enforcing three strict output rules—restate state every turn, make completed work visible, and apply a pre-send check—that eliminate ambiguity between actions and results.

The open-source repository ayghri/i-have-adhd provides a structured skill framework designed to solve a critical LLM usability problem: ensuring the reader always understands what action was taken and what result was achieved. By implementing explicit formatting constraints defined in skills/i-have-adhd/SKILL.md, this system creates an unambiguous feedback loop that prevents confusion about task progress and current state.

The Three Mechanisms That Guarantee Transparency

Restate State Every Turn

According to the source code in skills/i-have-adhd/SKILL.md (line 75), the skill requires the model to restate the current progress after each step. This forced restatement ensures the output explicitly reminds the reader what has already been accomplished and what requires immediate focus. For example, the model must output concrete progress indicators like "Step 3 of 5 done: schema updated" rather than vague confirmations that leave the reader guessing about overall status.

Make Completed Work Visible

The second rule, documented at line 91 of SKILL.md, mandates that wins are announced in concrete terms immediately upon completion. Instead of burying achievements in lengthy explanations or deferring them to final recaps, the model must surface the new functional state directly—such as "Login now works with magic links. Try..."—so the reader never has to infer what changed from context clues or later summaries.

Enforce the Pre-Send Check

The "Pre-send check" mechanism (line 30 of SKILL.md) acts as a final filter that removes introductory or concluding fluff before the response reaches the reader. This check explicitly requires the first line to present the next concrete action and the last line to state the outcome, ensuring the reader can read only those two lines and still know exactly what to do and what just happened.

Implementation and Code Examples

The skill implements these rules through deterministic formatting functions and strict output structures. The format_response helper function structures outputs to comply with the three-mechanism architecture:

def format_response(action, step, result, next_action):
    """
    Helper used by the skill to enforce the i‑have‑adhd style.
    """
    return f"{action}\n\nStep {step} done.\n{result}\n\nNext: {next_action}"

A compliant response following the pre-send check and visibility rules follows this YAML structure:

# Example of a response that follows the rules

- "Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`."
- "Step 1 of 3 done: jsonwebtoken updated."
- "Login now works with magic links. Try: `npm run dev`, open `/login`."
- "Next: run the test suite (`npm test`)."

Key Files and Configuration

The repository structure supports these guarantees through several critical files:

• skills/i-have-adhd/SKILL.md – Defines all 10 rules, including the three core mechanisms that enforce knowledge of what happened.
• plugin.json – Registers the skill with Claude Code/Codex so the rules are applied automatically to every response.
• skills/i-have-adhd/agents/openai.yaml – Provides example configuration for invoking the skill through OpenAI-based agents.
• README.md – Contains the general description and high-level overview of the skill's architecture.

Summary

• The i-have-adhd skill eliminates ambiguity by forcing the model to restate the current state after every turn, as defined at line 75 of SKILL.md.
• Completed work must be announced immediately in concrete, functional terms rather than buried in narrative text or deferred to later recaps.
• The pre-send check removes fluff and enforces a strict structure: first line shows the next action, last line shows the outcome.
• These mechanisms are implemented in skills/i-have-adhd/SKILL.md and enforced through the format_response helper and plugin.json configuration.

Frequently Asked Questions

What is the primary purpose of the i-have-adhd skill?

The i-have-adhd skill is designed to shape every LLM response so the reader can instantly see both the action taken and the result of that action. This prevents the confusion that often occurs when models generate verbose, unstructured outputs that obscure what actually changed.

How does the pre-send check prevent ambiguous responses?

The pre-send check, defined at line 30 of skills/i-have-adhd/SKILL.md, explicitly strips introductory and concluding fluff, requiring the first line to contain the next concrete action and the last line to state the outcome. This ensures the reader can understand the full context by reading just two lines.

Where are the formatting rules for i-have-adhd defined?

All formatting rules, including "Restate state every turn" and "Make completed work visible," are defined in skills/i-have-adhd/SKILL.md, with the skill being registered through plugin.json for automatic application in Claude Code and Codex environments.

Can the i-have-adhd rules be applied to OpenAI-based agents?

Yes, the repository includes skills/i-have-adhd/agents/openai.yaml, which provides the necessary configuration to invoke the skill and enforce its state-visibility rules through OpenAI-based agents.

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