How i-have-adhd Handles Explanation Requests vs Action Requests: Rule-Based Output Shaping

The i-have-adhd skill employs a conditional rule engine that enforces concise, action-first responses for standard queries, but automatically disables these ADHD-friendly constraints when a user explicitly requests an explanation or walkthrough.

The i-have-adhd repository by ayghri implements a specialized AI skill architecture designed to combat executive dysfunction through strict output formatting. Understanding how this system differentiates between explanation requests versus action requests reveals a stateful filter mechanism that prioritizes cognitive accessibility while preserving detailed educational capabilities when explicitly requested.

The Default Action-First Protocol

For the majority of interactions, the skill applies aggressive formatting constraints that prioritize immediate actionability over comprehensive exposition. These rules ensure that users with ADHD receive outputs that minimize cognitive load and decision paralysis.

Core Rules for Action Requests

The default behavior follows a rigid three-part structure defined in the skill's configuration:

1. Lead with the next action – The first line must be a concrete command, file path, or code snippet that the user can execute immediately.
2. Number multi-step work – Complex tasks are broken into bounded, sequential steps with clear numbering.
3. End with one concrete next action – Every response terminates with a specific, single instruction that tells the reader exactly what to do next.

These constraints are enforced universally unless specific override conditions are met. According to the source code, the system maintains a "no preamble/closer" policy as a baseline, eliminating introductory fluff and closing pleasantries that might distract from the task at hand.

Example: Action Request Response

When a user submits an action-oriented request, the response follows the constrained format:

User: "Add JWT verification to my auth middleware."

System Output:

Run `npm install jsonwebtoken` then edit `src/auth.ts:42`.
1. Open `src/auth.ts`.
2. Insert the JWT verification snippet below.
3. Run `npm test -- auth.spec.ts`.
Next: run `npm test` and paste the first failing line.

Notice the immediate executable command in line one, the numbered sequence for the procedure, and the explicit "Next" directive that closes the response.

The Explanation Override Mechanism

The architecture recognizes that educational content requires different formatting than procedural instructions. When the system detects specific trigger phrases in the user input, it enters an explanation mode that relaxes the length constraints while maintaining structural clarity.

Trigger Conditions for Verbose Mode

In skills/i-have-adhd/SKILL.md at lines 121-122, the repository defines the specific condition for breaking default rules:

"User asks to 'explain' or 'walk me through.' Explain fully. Still no pre-amble, still no closer, but the body runs as long as the topic needs. Add headers so the reader can skim back."

This override is also documented in skills/i-have-adhd/agents/gemini.toml at lines 21-22:

"Break these rules only when: the reader asks you to 'explain' or 'walk through' …"

When these triggers are detected, the system disables the ADHD-shaping filters, allowing multi-paragraph explanations, descriptive headers, and extended content that would otherwise violate the conciseness constraints.

Example: Explanation Request Response

When the trigger condition is met, the output format changes significantly:

User: "Can you explain how the OAuth flow works?"

System Output:

# OAuth Flow Overview

1️⃣ **Client obtains authorization** – The user is directed to the auth server …
2️⃣ **Server issues token** – After consent, the server returns an access token …
3️⃣ **Client accesses resources** – The client includes the token in API calls …
...

The response includes markdown headers for structural navigation and detailed explanatory paragraphs, permissible only because the "explain" intent triggered the override.

Technical Implementation in SKILL.md and gemini.toml

The distinction between explanation and action handling is hardcoded in the repository's core configuration files. The SKILL.md file serves as the primary rulebook, containing the explicit exception clause that permits verbose output during explanation requests. This file establishes the stateful behavior where the input parser checks user intent against the trigger phrases before applying formatting constraints.

The gemini.toml file in the agents directory mirrors this logic for Gemini CLI integrations, ensuring consistent behavior across different deployment targets. Both files maintain the same conditional structure: default to ADHD-friendly constraints unless the explanation trigger is present.

Summary

• Action requests trigger strict ADHD-friendly formatting: immediate actionable commands, numbered steps, and no preamble or closing text.
• Explanation requests bypass length constraints when users explicitly ask to "explain" or "walk me through," allowing headers and multi-paragraph content.
• Trigger detection occurs in the input parsing phase, implemented in SKILL.md (lines 121-122) and gemini.toml (lines 21-22).
• Consistency is maintained across both modes by preserving the "no preamble, no closer" rule even in explanation mode, ensuring responses remain scannable.

Frequently Asked Questions

What specific phrases trigger the explanation override in i-have-adhd?

The system activates explanation mode when the user input contains the exact phrases "explain" or "walk me through" (or "walk through"). These triggers are hardcoded in skills/i-have-adhd/SKILL.md and skills/i-have-adhd/agents/gemini.toml as the sole exceptions to the action-first constraints.

Does the explanation mode remove all ADHD-friendly formatting?

No, explanation mode maintains two core constraints even while allowing extended content: no preamble and no closer. The system still eliminates introductory fluff and closing pleasantries. However, it permits markdown headers and multi-paragraph bodies to facilitate complex topic explanation, with the requirement that headers help users skim back to specific sections.

Where are the differentiation rules defined in the repository?

The primary rule definition resides in skills/i-have-adhd/SKILL.md at lines 121-122, which contains the "When to break the rules" section. This logic is duplicated for CLI implementations in skills/i-have-adhd/agents/gemini.toml at lines 21-22, ensuring consistent behavior across different interfaces that consume the skill.

Can developers customize the action-first rules for specific use cases?

While the provided configuration files show fixed rules, the architecture uses a stateful rule engine that checks user intent before applying filters. Developers could theoretically extend the trigger conditions in SKILL.md or modify the constraint logic, though the repository as published treats these rules as invariant defaults to maintain the ADHD-accessible design philosophy.

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