How to Report Bugs in the i-have-adhd Project: A Step-by-Step Guide

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.

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, 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 (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, 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 (lines 90-99).

Required Labels for i-have-adhd Bug Reports

The 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:

## Summary

<!-- A short, clear description of the bug (e.g., "The skill stops after the first numbered step.") -->

## 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

<!-- Paste any console output or screenshots here. -->

## 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):

{
  "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 – Defines the contribution workflow, required labels, and PR checklist (lines 19-24 and 90-99)
• 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 – Describes entry points for various runtimes where integration bugs may surface
• README.md – Contains user-facing overview and quick-start instructions useful for reproducing installation-related bugs
• 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 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 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 and are mandatory for proper triage.

Where is the bug reporting workflow documented?

The complete bug reporting workflow is documented in the 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. For installation issues, reference 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, including the appropriate labels and completion of the PR checklist.

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