How to Debug When the i‑have‑adhd Plugin Fails to Load: A Complete Troubleshooting Guide

When the i‑have‑adhd plugin fails to load, start by inspecting the error stack trace for the exact failure point, then systematically validate the skill file path, run the built‑in compatibility tests, and verify the runtime entry‑point registration.

The ayghri/i-have-adhd repository provides a context‑aware productivity plugin for AI coding assistants. If the plugin crashes during startup or fails to inject its rules, this debugging guide walks through the exact diagnostics implemented in the source code.

---

Primary Failure Areas for i‑have‑adhd Plugin Loading Failures

Plugin load failures cluster into three distinct areas. Each has recognizable symptoms and targeted diagnostics.

Skill File Loading Errors

The loadRules() function in extensions/i-have-adhd.ts (lines 50‑55) throws when SKILL.md is unreadable or empty.

Typical symptom: Error message containing Unable to load i-have-adhd rules.

Diagnostic approach:

• Verify SKILL_PATH resolves to ../skills/i-have-adhd/SKILL.md relative to the extension
• Confirm the file contains non‑empty content after front‑matter stripping

Context Compatibility Mismatches

The plugin relies on contextMessages and latestMarkerIsActive helpers to determine if rules are already present.

Typical symptom: Rules never appear, or they vanish after session compaction.

Diagnostic approach:

• Run the standalone compatibility test: bun scripts/check_context_compat.ts
• This script asserts correct behavior of the context abstraction layer across Pi and OMP runtimes

Entry‑Point Registration Problems

The wrong entry file or missing registration calls prevent the plugin from initializing.

Typical symptom: No adhd flag or i-have-adhd command appears in the runtime.

Diagnostic approach:

• Confirm the extension file (extensions/i-have-adhd.ts) exports a default function that registers with pi.registerFlag() and pi.registerCommand() (lines 63‑71)
• Verify package.json references the correct extension path

---

Step‑by‑Step Debugging Workflow for i‑have‑adhd Plugin Load Issues

Follow this sequence to isolate the root cause efficiently.

1. Capture and Inspect the Thrown Error

The error object includes the absolute path that failed. Check ${SKILL_PATH} in the stack trace.

2. Validate the Skill File Exists and Contains Data

import { existsSync } from "node:fs";

const SKILL_PATH = "../skills/i-have-adhd/SKILL.md";

console.log("Skill file present:", existsSync(SKILL_PATH));

If missing, restore from the repository or adjust the SKILL_PATH definition.

3. Run the Compatibility Test Suite

bun scripts/check_context_compat.ts

Success output: Pi/OMP context compatibility checks passed

Failure indicates a broken contextMessages implementation or mismatched custom marker type.

4. Verify Runtime Registration Calls

In extensions/i-have-adhd.ts, confirm these registrations exist (around lines 63‑71):

pi.registerFlag("adhd", {
  default: true,
  description: "Enable ADHD productivity rules"
});

pi.registerCommand("i-have-adhd", {
  description: "Toggle ADHD rules for this session"
});

5. Examine Session State Restoration

Check that restoreState correctly reads saved state via pi.getFlag("adhd"). Silent failures here leave the plugin disabled without error messages.

6. Execute the Full Unit Test Suite

python3 -m unittest discover -s tests -v

This catches regressions across runtime environments.

7. Review CI Logs for Load Failures

GitHub Actions workflows plugin-load-check.yml and pi-load-check.yml surface loading failures in automated environments.

---

Diagnostic Code Examples from the i‑have‑adhd Source

Safely Loading the Skill File with Explicit Diagnostics

import { existsSync, readFileSync } from "node:fs";

const SKILL_PATH = "../skills/i-have-adhd/SKILL.md";

function stripFrontmatter(raw: string): string {
  // Removes YAML frontmatter between --- delimiters
  return raw.replace(/^---[\s\S]*?---/, "").trim();
}

function loadRules(): string {
  if (!existsSync(SKILL_PATH)) {
    throw new Error(`SKILL file not found at ${SKILL_PATH}`);
  }
  
  try {
    const raw = readFileSync(SKILL_PATH, "utf8");
    const stripped = stripFrontmatter(raw);
    
    if (!stripped) {
      throw new Error("SKILL.md is empty after stripping front‑matter");
    }
    return stripped;
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    throw new Error(`Failed to load i‑have‑adhd rules: ${msg}`);
  }
}

This mirrors the actual loadRules() implementation and adds path diagnostics.

Runtime Context Debugging with Compatibility Helpers

import { contextMessages, latestMarkerIsActive } from "./context-compat";

function debugContext(sessionMgr: unknown): void {
  const msgs = contextMessages(sessionMgr);
  console.log("Context messages:", msgs);
  
  const active = latestMarkerIsActive(
    msgs,
    "i-have-adhd-rules",
    "i-have-adhd-disabled"
  );
  console.log("ADHD rules active?", active);
}

Use this to trace why rules appear or disappear during session operations.

---

Key Files for Debugging i‑have‑adhd Plugin Loading

File	Role in Load Process
extensions/i-have-adhd.ts	Main implementation: loads rules, registers flag/command, syncs context state
extensions/context-compat.ts	Abstraction over Pi/OMP session managers (contextMessages, latestMarkerIsActive)
scripts/check_context_compat.ts	Standalone verification that compatibility helpers behave correctly
AGENTS.md	Documentation of runtime entry points and debugging recommendations (lines 32‑40)

---

Summary

• Skill file errors produce explicit throw statements—check SKILL_PATH validity first
• Context compatibility issues are caught by running bun scripts/check_context_compat.ts
• Entry‑point failures require verifying registerFlag() and registerCommand() calls in extensions/i-have-adhd.ts
• Silent disables often trace to restoreState misreading pi.getFlag("adhd")
• CI workflows provide early detection of load regressions

---

Frequently Asked Questions

Why does the i‑have‑adhd plugin throw Unable to load i-have-adhd rules on startup?

The loadRules() function in extensions/i-have-adhd.ts (lines 50‑55) throws this when SKILL.md is missing, unreadable, or empty after front‑matter stripping. Verify the file exists at the resolved SKILL_PATH and contains valid content.

How do I test if my runtime environment supports the plugin's context features?

Run bun scripts/check_context_compat.ts. This standalone script validates that contextMessages and latestMarkerIsActive behave correctly for your Pi or OMP session manager. Failures indicate an incompatible runtime version.

The plugin loads but rules disappear after session compaction—what's wrong?

This indicates a context compatibility failure. The latestMarkerIsActive helper cannot determine if rules are already present. Run the compatibility test and examine contextMessages output to trace marker detection.

Where should I start debugging if no adhd flag or command appears?

Check extensions/i-have-adhd.ts lines 63‑71 for pi.registerFlag("adhd", …) and pi.registerCommand("i-have-adhd", …). Confirm your runtime uses the correct entry point documented in AGENTS.md (lines 32‑40).

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