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

> Discover how i-have-adhd uses three output rules to guarantee readers understand actions and results. Explore the source code breakdown to see this clarity in action.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: internals
- Published: 2026-08-04

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```python
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:

```yaml

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** – Defines all 10 rules, including the three core mechanisms that enforce knowledge of what happened.
- **[`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml)** – Provides example configuration for invoking the skill through OpenAI-based agents.
- **[`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and enforced through the `format_response` helper and [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), with the skill being registered through [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.