# How to Report Bugs in the i-have-adhd Project: A Step-by-Step Guide > Learn how to report bugs effectively for the i-have-adhd project. Follow our guide to create clear GitHub issues and help improve the project. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: how-to-guide - Published: 2026-08-30 --- **To report bugs in the i-have-adhd project, search existing issues first, then create a new GitHub issue with the `bug` label, a Target label (e.g., `Target:Rules`), and an Author label, including detailed reproduction steps and referencing affected files like [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md).** The **i-have-adhd** repository maintains a structured contribution workflow designed to ensure every defect is tracked, labeled, and triaged consistently. According to the source code in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md), the project requires specific labels and detailed information for all bug reports to help maintainers route problems to the right subsystem efficiently. ## The i-have-adhd Bug Reporting Workflow ### Search Existing Issues Before opening a new issue, check the existing issue list to verify whether the bug has already been reported. This prevents duplicate work and helps maintainers focus on unreported problems. ### Create a New Issue If the bug is not present, click the **"New issue"** button on the repository's GitHub page. Use the default *Bug report* template if available, or start with a markdown skeleton that includes sections for summary, reproduction steps, environment details, and affected files. ### Apply Required Labels According to the workflow defined in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) (lines 19-24), every issue must have one label from the **Workflow** group. For defects, apply the **`bug`** label. You must also add: - A **Target** label (`Target:Rules` for skill-rule problems or `Target:Docs` for documentation errors) - An **Author** label indicating who will author the fix (`Author:Human`, `Author:Hybrid`, or `Author:AI`) These labels help maintainers route the problem to the correct subsystem immediately upon submission. ### Document Reproduction Steps The issue body must contain specific details to enable quick verification: - A concise summary of the defect - Exact steps to reproduce, including commands and file paths - Expected versus actual behavior - Environment details (OS, Node version, plugin version) - Relevant log output or screenshots ### Reference Affected Files If you know which source files are involved, link to them directly in the issue description. For example, a bug in the skill definition should reference [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), the canonical skill file that drives the plugin's behavior. Referencing specific file paths allows maintainers to locate the relevant code quickly without searching the entire codebase. ### Submit and Follow Up After filling in the template and adding the required labels, click **"Submit new issue."** The issue will appear in the tracker for triage. If you can provide a fix, open a pull request (PR) that references the issue (e.g., `Fixes #123`). The PR must follow the contribution guidelines regarding authorship disclosure and verification steps as documented in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) (lines 90-99). ## Required Labels for i-have-adhd Bug Reports The [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) file defines a mandatory labeling system that categorizes every issue: - **`bug`** – Required for all defect reports (Workflow category) - **`Target:Rules`** – Use when the bug relates to skill-rule enforcement or logic errors - **`Target:Docs`** – Use for documentation errors or inaccuracies - **`Author:Human`** – Indicates a human contributor will author the fix - **`Author:Hybrid`** – Indicates a combination of human and AI contribution - **`Author:AI`** – Indicates an AI-generated fix requiring human review Applying these labels correctly ensures your issue is routed to the appropriate maintainers and processed according to the project's triage priorities. ## Bug Report Template Copy and paste the following markdown template into your new GitHub issue: ```markdown ## Summary ## Steps to Reproduce 1. Run `claude plugin install i-have-adhd@i-have-adhd`. 2. Invoke the skill with `/i-have-adhd` and ask it to "Explain how to set up a new repo". 3. Observe that the response stops after the first numbered step. ## Expected Result The skill should continue enumerating all steps until the task is complete. ## Actual Result The response is truncated after step 1. ## Environment - OS: macOS 14.2 - Node: v20.11.0 - Plugin version: `i-have-adhd@main` ## Logs / Screenshots ## Affected Files - [SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) – rule around "Number multi-step tasks". ``` If you prefer to create issues programmatically via the GitHub REST API, use this JSON payload structure (omitting authentication tokens): ```json { "title": "Skill stops after the first numbered step", "body": "## Summary\nThe skill truncates the output after the first step.\n\n## Steps to Reproduce\n1. Run `claude plugin install i-have-adhd@i-have-adhd`.\n2. Invoke `/i-have-adhd` with a multi-step request.\n3. Observe the truncation.\n\n## Expected Result\nAll steps should be listed.\n\n## Actual Result\nOnly the first step appears.\n\n## Environment\n- OS: macOS 14.2\n- Node: v20.11.0\n- Plugin version: i-have-adhd@main\n\n## Affected Files\n- [SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)", "labels": ["bug", "Target:Rules", "Author:Human"] } ``` ## Key Files Related to Bug Reporting - **[`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md)** – Defines the contribution workflow, required labels, and PR checklist (lines 19-24 and 90-99) - **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** – Canonical definition of the i-have-adhd skill; most bugs relate to rule enforcement in this file - **[`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md)** – Describes entry points for various runtimes where integration bugs may surface - **[`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md)** – Contains user-facing overview and quick-start instructions useful for reproducing installation-related bugs - **[`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md)** – Detailed installation steps for each platform; common source of environment-specific bug reports ## Summary - Search existing issues before creating new ones to avoid duplicates in the i-have-adhd project - Apply three required label categories: Workflow (`bug`), Target (`Target:Rules` or `Target:Docs`), and Author (`Author:Human`, `Author:Hybrid`, or `Author:AI`) - Reference specific file paths like [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) when reporting bugs related to skill behavior - Include environment details and exact reproduction steps to enable maintainers to verify issues quickly - Follow the PR checklist in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) if submitting a fix alongside your bug report ## Frequently Asked Questions ### What labels are required when reporting a bug in i-have-adhd? Every bug report must include the `bug` label from the Workflow category, plus one Target label (such as `Target:Rules` or `Target:Docs`) and one Author label (`Author:Human`, `Author:Hybrid`, or `Author:AI`). These labels are defined in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) and are mandatory for proper triage. ### Where is the bug reporting workflow documented? The complete bug reporting workflow is documented in the [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) file at the repository root, specifically in the "Workflow" section (lines 19-24) for label definitions and lines 90-99 for the PR checklist requirements. ### Should I reference specific files when reporting bugs? Yes, you should reference specific files when possible. For skill-related bugs, link to [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). For installation issues, reference [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md). Providing direct file links helps maintainers locate the affected code immediately without searching the codebase. ### Can I submit a fix alongside my bug report? Yes, after submitting the issue, you can open a pull request that references the issue number (e.g., `Fixes #123`). The PR must adhere to the authorship disclosure and verification steps outlined in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md), including the appropriate labels and completion of the PR checklist.