# How to Debug Issues in i-have-adhd: A Complete Troubleshooting Guide

> Troubleshoot i-have-adhd issues with this guide. Learn to debug by checking the always-on flag, synchronizing SKILL.md files, and running the Python test suite.

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

---

**Debugging i-have-adhd requires verifying the always-on flag at `$XDG_CONFIG_HOME/opencode/.i-have-adhd-always`, ensuring [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) files remain synchronized across runtime directories, and running the Python test suite to isolate plugin failures.**

The **i-have-adhd** repository provides an ADHD-friendly coding assistant skill that injects formatted response rules into multiple LLM backends including OpenCode, Claude, Codex, and Gemini. When the plugin fails to activate or produces malformed output, systematic debugging involves checking the filesystem flag, validating skill file consistency, and executing the comprehensive test suite located in the `tests/` directory.

## Understanding the i-have-adhd Architecture

The project separates **skill definitions** from **runtime plugins**, creating multiple potential failure points during execution.

### Skill Definition and Runtime Plugins

The canonical behavior rules live in **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)**, which serves as the source of truth for how the assistant formats output (leading with next actions, numbering steps, providing concrete time estimates). This content is mirrored at **[`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)** for Cursor IDE compatibility. When editing the skill, you must keep both files synchronized.

Each runtime loads a specific plugin entry point: **`.opencode/plugins/i-have-adhd.mjs`** for OpenCode, **[`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)** for Claude, **[`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json)** for Codex, and **[`.agents/plugins/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.agents/plugins/marketplace.json)** for Pi and other agents. These plugins read the skill file, strip YAML front-matter when the always-on flag is active, and inject the transformed text into the LLM response pipeline.

### The Always-On Flag Mechanism

The **always-on flag** determines whether the plugin processes the skill or returns an empty string. The system checks for the existence of **`$XDG_CONFIG_HOME/opencode/.i-have-adhd-always`**. When this file is present, the plugin becomes active; when absent, it silently passes through without modification.

## Checking the Always-On Flag Configuration

If the plugin returns empty responses or behaves as though uninstalled, first verify the flag file exists and is readable:

```bash
if [ -f "$XDG_CONFIG_HOME/opencode/.i-have-adhd-always" ]; then
  echo "Flag is set - plugin should be active"
else
  echo "Flag missing - plugin will return empty string"
fi

```

The repository provides **always-on hooks** to manage this flag for the current session:

- **`hooks/always-on.mjs`** – Node.js script for setting the flag
- **[`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh)** – Bash implementation for Unix systems  
- **`hooks/always-on.ps1`** – PowerShell script for Windows environments

If you suspect the plugin is not triggering, confirm that one of these scripts executed successfully and created the flag file. The behavior is explicitly tested in **[`tests/test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_always_on_hooks.py)** and **[`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py)**.

## Validating Skill File Synchronization

Symptoms where skill content appears unchanged after editing typically indicate the mirror file is outdated. The repository maintains two copies of the skill definition:

1. **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** – Primary source of truth
2. **[`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)** – Cursor-specific mirror

After editing the primary file, verify synchronization by running:

```bash
git diff .cursor/skills/i-have-adhd/SKILL.md

```

If differences appear, copy the updated content to the Cursor directory to ensure consistent behavior across IDEs.

## Running the Test Suite

The repository ships with comprehensive unit tests that validate flag handling, front-matter stripping, and runtime compatibility. Execute the full suite with:

```bash
python3 -m unittest discover -s tests -v

```

The test suite specifically validates:

- Correct handling of the always-on flag presence and absence
- Proper front-matter stripping, including edge cases with unclosed fences or trailing whitespace
- OpenCode plugin compatibility via the driver script **`tests/opencode_plugin_driver.mjs`**

To manually invoke the OpenCode plugin driver for reproducing CI failures:

```bash
node tests/opencode_plugin_driver.mjs .opencode/plugins/i-have-adhd.mjs

```

For testing specific skill processing without the full framework, create a minimal skill file and inspect the plugin output:

```python
from pathlib import Path
skill_path = Path('skills/i-have-adhd/SKILL.md')
skill_path.write_text('---\nname: test\n---\nTest body.')

# Now run the plugin as shown in the test_opencode_plugin.py implementation

```

## Common Debugging Scenarios

Use the following diagnostic approach when encountering specific failure modes:

**Empty Response from Plugin**
- **Likely cause:** The always-on flag file is missing or unreadable
- **Debug step:** Verify `$XDG_CONFIG_HOME/opencode/.i-have-adhd-always` exists using the bash check shown above

**Skill Content Not Updating**
- **Likely cause:** The Cursor mirror file is out of sync with the primary skill definition
- **Debug step:** Run `git diff` between [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) to identify discrepancies

**Front-Matter Not Stripped**
- **Likely cause:** Malformed YAML fences or extra whitespace in the skill file
- **Debug step:** Run the plugin directly with a test skill (referencing the `test_strips_frontmatter_with_trailing_whitespace` test case) and inspect the transformed output

**Runtime Crashes on Load**
- **Likely cause:** Missing Node.js dependency for the OpenCode plugin
- **Debug step:** Check if tests skip with `shutil.which("node")` returning None; install Node if required

**Unexpected Logs in CI Pipelines**
- **Likely cause:** Hook scripts failing to set the flag in the CI environment
- **Debug step:** Examine **[`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml)** and **[`.github/workflows/pi-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/pi-load-check.yml)** to verify environment setup steps are creating the flag file before test execution

## Summary

- **The always-on flag** at `$XDG_CONFIG_HOME/opencode/.i-have-adhd-always` controls plugin activation; verify its existence first when debugging silent failures.
- **Skill files** must remain synchronized between [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) to ensure consistent behavior across runtimes.
- **Run the test suite** using `python3 -m unittest discover -s tests -v` to validate flag handling, front-matter stripping, and plugin functionality.
- **Hook scripts** in the `hooks/` directory manage flag creation for different shells and environments.
- **Manual debugging** can utilize the `tests/opencode_plugin_driver.mjs` script to isolate runtime-specific issues without the full test framework overhead.

## Frequently Asked Questions

### Why does the i-have-adhd plugin return an empty response?

The plugin returns an empty string when the **always-on flag** is missing. Verify that **`$XDG_CONFIG_HOME/opencode/.i-have-adhd-always`** exists and is readable by the process. If running in a fresh terminal session, ensure you executed one of the hook scripts ([`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh), `hooks/always-on.mjs`, or `hooks/always-on.ps1`) to create the flag.

### How do I test if the skill file is being processed correctly?

Run the Python test suite to verify processing: `python3 -m unittest discover -s tests -v`. For manual inspection, use the Node.js driver at **`tests/opencode_plugin_driver.mjs`** to pass a test skill file through the plugin and observe the output. This bypasses IDE integration and isolates the transformation logic.

### What causes front-matter stripping to fail?

Front-matter stripping fails when YAML fences are malformed, contain unclosed delimiters, or include unexpected trailing whitespace. The test case `test_strips_frontmatter_with_trailing_whitespace` in **[`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py)** specifically covers these edge cases. Ensure your [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) uses clean `---` delimiters without extra characters on the fence lines.

### Why do changes to SKILL.md not appear in my Cursor IDE?

Cursor reads from **[`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)**, not the primary `skills/` directory. After editing the main skill file, copy the updated content to the Cursor mirror location and verify with `git diff .cursor/skills/i-have-adhd/SKILL.md` to ensure both files match byte-for-byte.