How i-have-adhd Makes Completed Work Visible for Progress Communication

The i-have-adhd extension makes completed work visible by injecting Rule 7 into the model's context, forcing every response to explicitly state what now works in concrete terms followed by an immediate verification step.

The i-have-adhd repository is an open-source coding assistant extension designed to optimize AI interactions for neurodivergent users. To make completed work visible for progress communication, the system implements a strict rule-based architecture that eliminates ambiguous progress updates in favor of concrete, dopamine-reinforcing confirmations.

The Rule Behind Visible Progress

Rule 7 Definition in SKILL.md

The core behavior is defined in skills/i-have-adhd/SKILL.md at lines 91-97, where Rule 7 mandates a specific communication pattern. The rule states: "Show what now works, in concrete terms. Do not bury wins in a recap."

According to the source code, the implementation distinguishes between ineffective and effective communication:

• Bad pattern: "I've made some changes to the auth flow…."
• Good pattern: "Login now works with magic links. Try: npm run dev, open /login."

This rule ensures that every completed task is announced explicitly rather than being lost in verbose explanations.

Technical Implementation

Extension Architecture

The enforcement mechanism lives in extensions/i-have-adhd.ts (lines 42-30). The TypeScript extension loads the skill definition file, strips its YAML front-matter, and injects the rules as a hidden custom message into the conversation context. This guarantees the model sees the instruction for every turn while the mode is active.

Context Injection Mechanism

The extension uses the following implementation to load and inject the rules:

// Extension that injects the rule set (including Rule 7)
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";

export default function iHaveAdhdExtension(pi: ExtensionAPI) {
  const rules = readFileSync(
    join(__dirname, "..", "skills", "i-have-adhd", "SKILL.md"),
    "utf8"
  ).replace(/^---[\s\S]*?---\s*/, "");   // strip front-matter

  // When ADHD mode is active, send the rules once
  if (enabled && !rulesAlreadyInContext) {
    pi.sendMessage(
      { customType: "i-have-adhd-rules", content: rules, display: false },
      { triggerTurn: false }
    );
  }
}

This injection happens with display: false, meaning the rules guide the model's output without cluttering the user's interface.

Practical Application

Enabling the Mode

Users toggle the visibility behavior using simple slash commands:

# Toggle ADHD-friendly output (the mode that makes completed work visible)

# 1️⃣ Enable

/i-have-adhd on          # or just /i-have-adhd to toggle

# 2️⃣ Example model response (after completing a step)

Login now works with magic links. Try: `npm run dev`, open `/login`.

# 3️⃣ Disable

/i-have-adhd off

Response Pattern

When active, the model follows the strict pattern defined in Rule 7:

<What now works>, <concrete next step or verification command>

This structure appears in every response where work is completed, transforming hidden wins into visible progress that reduces ambiguity and provides clear dopamine feedback.

Supporting Infrastructure

Several files work together to maintain this behavior:

• skills/i-have-adhd/SKILL.md – Contains the human-readable rule set; Rule 7 defines the phrasing requirements for completed work.
• extensions/i-have-adhd.ts – Loads the rule file, strips front-matter, and injects the rules into the model's context.
• scripts/run_evals.py – Demonstrates how completed work is tracked (completed_keys) for evaluation, ensuring the rule is respected during automated tests.
• skills/i-have-adhd/agents/gemini.toml – Lists the rule "Make completed work visible" as a guideline for the Gemini agent configuration.

Summary

• Rule 7 in SKILL.md explicitly prohibits burying wins in recaps and mandates concrete progress statements.
• The TypeScript extension loads these rules and injects them as hidden context on every turn when ADHD mode is enabled.
• Responses follow a strict two-part pattern: what now works, followed by an immediate verification command.
• Evaluation scripts track completed_keys to verify compliance during automated testing.
• Users control the feature via /i-have-adhd toggle commands.

Frequently Asked Questions

How does the extension enforce the "make completed work visible" rule?

The extension enforces the rule by pre-pending the content of skills/i-have-adhd/SKILL.md to the model's context window as a hidden system message. Because the rules are injected with display: false but remain in the active context, every generated response must adhere to the constraints outlined in Rule 7.

What happens when ADHD mode is disabled?

When disabled via /i-have-adhd off, the extension stops injecting the rule set into the context window. The model then reverts to standard response patterns, which may include verbose explanations or bury completed tasks within general recaps.

Where are the specific phrasing examples defined?

The concrete examples of good versus bad communication patterns are defined in skills/i-have-adhd/SKILL.md at lines 91-97. This file serves as both the human-readable specification and the machine-readable instruction set that the TypeScript extension loads and injects.

How is compliance with Rule 7 tested?

Compliance is verified through scripts/run_evals.py, which tracks completed_keys during evaluation runs. This ensures that the model correctly identifies and explicitly states what has been completed rather than generating ambiguous progress updates.

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