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

> Troubleshoot i-have-adhd plugin loading failures. Inspect error traces, validate skill paths, run compatibility tests, and verify entry-point registration for a complete guide.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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](https://github.com/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) (lines 50‑55) throws when [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/../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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)) exports a default function that registers with `pi.registerFlag()` and `pi.registerCommand()` (lines 63‑71)
- Verify [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/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

```ts
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

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), confirm these registrations exist (around lines 63‑71):

```ts
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

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/plugin-load-check.yml) and [`pi-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/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

```ts
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

```ts
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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) | Main implementation: loads rules, registers flag/command, syncs context state |
| [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts) | Abstraction over Pi/OMP session managers (`contextMessages`, `latestMarkerIsActive`) |
| [`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts) | Standalone verification that compatibility helpers behave correctly |
| [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) (lines 50‑55) throws this when [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) (lines 32‑40).