How i-have-adhd Makes Completed Work Visible: Rule-Driven Progress Communication

i-have-adhd makes completed work visible by enforcing a strict communication pattern where the model explicitly states what now works in concrete terms, immediately followed by a verifiable next step.

The i-have-adhd repository provides a specialized skill set for the pi-coding-agent that optimizes AI-assisted development for users with ADHD. Instead of burying achievements in lengthy recaps, the system implements Rule 7 from SKILL.md to ensure every incremental victory is announced explicitly. This approach transforms hidden wins into visible progress that reinforces dopamine and reduces cognitive ambiguity.

Rule Definition in SKILL.md

The behavioral requirement to make completed work visible is codified in Rule 7 of skills/i-have-adhd/SKILL.md (lines 91-97).

The rule mandates: "Show what now works, in concrete terms. Do not bury wins in a recap." This instruction distinguishes between two communication styles:

• Bad: "I've made some changes to the auth flow…." — Ambiguous and requires the user to dig for information.
• Good: "Login now works with magic links. Try: npm run dev, open /login." — Explicit statement of the working feature paired with an immediate verification command.

Technical Implementation: Context Injection

The extension guarantees adherence to this rule by programmatically injecting the skill definitions into the model's context. In extensions/i-have-adhd.ts (around lines 30-42), the TypeScript extension loads the rule file and strips its YAML front-matter before insertion.

Loading and Processing Rules

The extension reads the markdown file and prepares it for injection:

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 }
    );
  }
}

Silent Enforcement

By setting display: false, the extension injects the rules as a hidden custom message. This ensures the language model sees the instruction to make completed work visible on every turn, while keeping the user's interface clean of system prompts.

Practical Usage and Output Format

Activate the ADHD-friendly output mode using the toggle command:

# Enable explicit progress communication

/i-have-adhd on

Once enabled, the model reformats its responses to front-load concrete wins. After completing a step—such as fixing authentication or adding a feature—the output follows this pattern:

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

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

To disable the mode, use /i-have-adhd off.

Validation and Agent Configuration

The repository ensures compliance through automated testing and agent configuration. The scripts/run_evals.py file tracks completed_keys during evaluation, verifying that the model respects the visibility rule during automated assessments.

Additionally, skills/i-have-adhd/agents/gemini.toml lists "Make completed work visible" as a specific guideline for the Gemini agent, reinforcing the behavioral requirement across different model implementations.

Summary

• Rule 7 in SKILL.md explicitly forbids burying wins in recaps and mandates concrete progress statements.
• The TypeScript extension in i-have-adhd.ts injects these rules into the model context as hidden messages.
• Every completed task must be announced with a specific working feature and an immediate verification step.
• The system supports dopamine reinforcement by making incremental victories immediately visible and actionable.

Frequently Asked Questions

Where is the rule to make completed work visible defined?

The rule is defined in skills/i-have-adhd/SKILL.md at lines 91-97. This file contains the complete behavioral specification that the extension loads and enforces.

How does the extension enforce the communication pattern without cluttering the chat?

The extension injects the rules using pi.sendMessage() with display: false, which adds the instructions to the model's context window as a hidden custom message. This ensures the model follows the pattern while keeping the user interface clean.

What is the exact format for communicating completed work?

The required format is: What now works, followed by a concrete next step or verification command. For example: "API endpoint now returns user data. Test with: curl http://localhost:3000/api/user." The statement must be concrete and immediately verifiable.

How do I enable ADHD mode to make completed work visible?

Use the slash command /i-have-adhd on to enable the mode. When active, all model responses will follow the explicit progress communication pattern. Use /i-have-adhd off to return to standard output formatting.

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