# Troubleshooting Guide: Debugging the i-have-adhd Plugin When It Fails to Load

> Debug i-have-adhd plugin loading errors. Learn to troubleshoot five architectural layers from extension entry point to command handling for swift resolution.

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

---

**When the i-have-adhd plugin fails to load, the root cause typically stems from five architectural layers: the extension entry point, rule file access, session state restoration, context synchronization, or command handling, each producing distinct error symptoms that require specific diagnostic steps.**

The *i-have-adhd* plugin is a Pi-Coding-Agent extension that injects ADHD-friendly response rules into the model's context. When troubleshooting loading failures in the `ayghri/i-have-adhd` repository, you must trace execution through the extension's registration flow, file system access, and session management logic to identify exactly where initialization breaks down.

## Understanding the Plugin Architecture

The plugin operates across three core components defined in the source code. The **extension entry point** ([`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)) registers the `/i-have-adhd` command and loads the rule file. The **rule file** ([`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)) contains the ten ADHD-friendly rules in Markdown format. Finally, **session state management** persists the enabled/disabled flag across conversation turns using `getSavedState()` and `restoreState()`.

When any layer fails, the plugin either silently ignores the `--adhd` flag, throws file system errors, or fails to persist user preferences across session compactions.

## Common Failure Points and Diagnostic Steps

### Extension Entry Point Failures (extensions/i-have-adhd.ts)

The extension initializes in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) by calling `loadRules()` (lines 46-63) to read the skill file. If the plugin reports "Unable to load i-have-adhd rules" or the `/i-have-adhd` command is ignored, verify the `SKILL_PATH` constant correctly points to [`../skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/../skills/i-have-adhd/SKILL.md).

Insert diagnostic logging immediately after the `readFileSync` call to confirm file access:

```typescript
// In extensions/i-have-adhd.ts
function loadRules(): string {
  console.log("[i-have-adhd] Attempting to read rule file:", SKILL_PATH);
  const content = readFileSync(SKILL_PATH, "utf8");
  console.log("[i-have-adhd] Rule file size:", content.length);
  return stripFrontmatter(content);
}

```

If the console remains silent, the extension was not discovered by Pi—check that [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) correctly lists the entry point under the "pi" configuration.

### Rule File Access Errors (SKILL.md)

The [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) file must be readable and non-empty. When `readFileSync` throws `ENOENT` or returns an empty string, the extension triggers "The i-have-adhd rules file is empty" errors.

Check three specific conditions:
- The repository contains the file at the exact relative path from the extension's execution context
- The file contains actual rule content and not just YAML front-matter that the `stripFrontmatter` regex fails to remove
- File system permissions allow the agent's user to read the markdown file

### Session State Restoration Issues

The plugin uses `getSavedState()` (lines 69-78) to read the `i-have-adhd-state` entry from the session manager. If the plugin always starts disabled despite the `--adhd` flag, inspect the `sessionManager.getBranch()` loop for correct type checking against `customType === STATE_ENTRY_TYPE`.

Confirm the extension registers the flag properly:

```typescript
// Lines 63-67 in extensions/i-have-adhd.ts
pi.registerFlag("adhd", {
  description: "Enable ADHD-friendly response mode",
  default: false
});

```

If `getSavedState()` returns `undefined` consistently, verify `STATE_ENTRY_TYPE` is not misspelled in either the storage or retrieval logic.

### Context Synchronization Problems

The `syncContext()` function ensures rule messages appear exactly once in the conversation context using `latestMarkerIsActive` from [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts). When rules duplicate after injections or disappear after session compaction, check that `RULES_MESSAGE_TYPE` and `DISABLED_MESSAGE_TYPE` constants are used consistently throughout the synchronization logic.

### Command Handling Failures

The `/i-have-adhd` command handler (lines 69-91) toggles the mode on/off. If the command produces "Usage: /i-have-adhd [on|off]" errors when typed correctly, or the UI fails to show the "● ADHD ON" badge, examine the `handler` logic:

```typescript
// Verify in extensions/i-have-adhd.ts
const arg = args.trim().toLowerCase();
if (arg === "on") {
  await setEnabled(true);
  ctx.ui.notify("ADHD mode enabled", "success");
}

```

Ensure `setEnabled` calls both `pi.appendEntry` to persist state and `ctx.ui.notify` to update the interface.

## Step-by-Step Debugging Procedure

Follow this systematic approach to isolate the failure layer:

1. **Verify extension loading** by adding `console.log("i-have-adhd extension loaded")` at the top of [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts). If the message does not appear in the agent's console, the extension entry point is not registered.

2. **Check rule-file loading** by logging the output of `loadRules()`. If exceptions occur, adjust `SKILL_PATH` or restore the missing [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file.

3. **Confirm UI status updates** by adding debug output in `updateStatus` to print the `enabled` boolean after toggling the mode with `/i-have-adhd on`.

4. **Inspect session persistence** by logging the output of `getSavedState(ctx)`. If always `undefined`, the custom entry type constant is likely inconsistent between save and load operations.

5. **Validate context markers** using the helper from [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts):

```typescript
const present = rulesAreInContext(ctx);
console.log("Rules currently in context?", present);

```

If `present` toggles unexpectedly after compaction, `latestMarkerIsActive` may mis-identify the newest marker.

6. **Run minimal reproduction** by creating a fresh session, enabling the mode, issuing a request, then triggering `session_compact` to observe if rules persist through the compaction event.

## Diagnostic Code Snippets

**Manually Trigger Context Sync**

```typescript
// In a test script or REPL
await pi.sendMessage(
  { customType: "i-have-adhd-sync", content: "", display: false },
  { triggerTurn: false }
);

```

**Verify UI Badge Rendering**

```typescript
// After enabling the mode
pi.sendMessage(
  { customType: "i-have-adhd-test", content: "test", display: false },
  { triggerTurn: false }
);
// Expected: Green "● ADHD ON" appears in status bar

```

**Check Session Entry Type**

```typescript
// Debug state restoration
const saved = getSavedState(ctx);
console.log("Restored saved state:", saved);
console.log("Entry type constant:", STATE_ENTRY_TYPE);

```

## Summary

- **Extension loading failures** indicate missing entry point registration or incorrect [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) configuration in `ayghri/i-have-adhd`.
- **Rule file errors** trace to `SKILL_PATH` misconfiguration, missing [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), or front-matter stripping failures in `loadRules()`.
- **State persistence issues** stem from `STATE_ENTRY_TYPE` inconsistencies between `getSavedState()` and the session manager.
- **Context duplication** results from improper `latestMarkerIsActive` logic or mismatched `RULES_MESSAGE_TYPE` constants.
- **Command failures** occur when `args` parsing or `setEnabled` implementation lacks proper trimming, lowercasing, or UI notification calls.

## Frequently Asked Questions

### Why does the i-have-adhd plugin report "Unable to load i-have-adhd rules" on startup?

This error originates in the `loadRules()` function (lines 46-63) in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) when `readFileSync` cannot locate [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) at the relative path defined by `SKILL_PATH`. Verify the file exists at [`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's execution directory, and ensure the path separator syntax matches your operating system.

### Why does the plugin disable itself after session compaction?

The `syncContext()` function relies on `latestMarkerIsActive` in [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) to determine if rules are present. If rules disappear after compaction, the marker detection logic may fail to identify the most recent context entry, causing the extension to believe the rules are absent. Check that `RULES_MESSAGE_TYPE` matches exactly between the injection and detection code.

### Why does the `/i-have-adhd on` command show usage instructions instead of enabling the mode?

The command handler (lines 69-91) validates arguments by trimming and lowercasing the input before comparison. If the argument parsing fails, the handler falls back to usage instructions. Ensure no invisible characters or extra whitespace precede your command, and verify that `args.trim().toLowerCase()` is being called before the equality check against `"on"` or `"off"`.

### How do I verify the plugin is actually loading without visible errors?

Add `console.log("[i-have-adhd] Extension initialized")` at the top level of [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) immediately after imports. If this log does not appear when the agent starts, Pi has not discovered the extension—check your [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) "pi" entry points array to confirm the file path is registered correctly.