Pull Request Verification Steps for i-have-adhd: The Complete Contributor Checklist

Before submitting a pull request to the ayghri/i-have-adhd repository, contributors must complete an 8-step verification workflow that combines automated testing, behavioral evaluation, plugin isolation checks, and explicit human verification documentation.

The i-have-adhd project enforces rigorous validation standards to prevent regressions in skill behavior and plugin compatibility. According to the repository’s contribution guidelines, every PR must demonstrate that changes have been safely validated through specific automated commands and manual verification steps before maintainers will review the code.

Automated Testing Requirements

Run the Full Unit Test Suite

All contributions must pass the existing Python test suite to ensure no regressions in core functionality. In CONTRIBUTING.md (lines 77-84), the project requires executing the unittest discovery command against the entire test tree:

python3 -m unittest discover -s tests -v

This command validates the tests/ directory and ensures that modifications to the skill logic or utility functions do not break established behaviors.

Execute the Evaluation Harness

For any changes affecting evaluation code or test cases, contributors must run the repository’s validation script. As specified in CONTRIBUTING.md (lines 81-84), use the following command to verify eval integrity:

python3 scripts/run_evals.py validate

This script checks the release-gate criteria and confirms that evaluation fixtures produce consistent results.

Behavioral and Plugin Validation

Validate Behavior Changes with Eval Cases

When modifications alter skill output or behavioral logic, contributors must create representative evaluation fixtures and perform a baseline versus candidate comparison. According to the behavior changes section in CONTRIBUTING.md, you must verify that the release-gate passes before submitting.

If your changes affect evaluation logic, add or update the corresponding eval cases in the appropriate test directories, then run the evaluation validator to confirm compatibility.

Test Plugin Loading in Isolated Environments

Changes to plugins or hooks require isolated loading verification to confirm clean startup without errors. For hook or plugin changes, the CONTRIBUTING.md specifies loading the altered component in a temporary configuration directory:

OPENCODE_CONFIG_DIR=$(mktemp -d)
opencode load --config "$OPENCODE_CONFIG_DIR" plugins/i-have-adhd.mjs

This applies to files in the hooks/ directory (such as always-on.mjs) and any plugins referenced in scripts/check_context_compat.ts.

Documentation Synchronization

Synchronize the Canonical Skill File

When editing SKILL.md, contributors must maintain parity with the Cursor-compatible mirror. Per CONTRIBUTING.md (lines 68-74), copy the canonical skill file to the mirrored location and verify byte-for-byte equality:

cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md
cmp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

The cmp command ensures that skills/i-have-adhd/SKILL.md and .cursor/skills/i-have-adhd/SKILL.md remain identical, preventing documentation drift between environments.

Human Verification Protocol

Document Testing Evidence in the PR Template

Every pull request must populate the Human verification field in the PR description. According to .github/pull_request_template.md (line 15), contributors must include a explicit statement of what commands were executed and what was manually inspected:

**Human verification:** I ran `python3 -m unittest discover -s tests -v` and `python3 scripts/run_evals.py validate`; both commands completed without errors. I also manually triggered the plugin load in a temporary directory.

Address Omitted Verification Steps

If a particular verification check cannot be performed, CONTRIBUTING.md requires explicitly stating why and noting the missing evidence in the PR description. This transparency allows maintainers to assess risk when automated testing is impossible for specific edge cases.

Complete the Final Checklist

The PR description must cover five critical components outlined in CONTRIBUTING.md (lines 31-38):

1. What changed — Specific files and functions modified
2. Why — The motivation for the change
3. Observable before/after behavior — Expected differences in output or performance
4. Safety/compatibility considerations — Potential risks and mitigation strategies
5. Exact verification performed — Concrete commands run and results observed

Summary

• Unit testing is mandatory via python3 -m unittest discover -s tests -v to prevent regressions in the tests/ directory
• Behavioral validation requires running python3 scripts/run_evals.py validate and confirming the release-gate passes for any skill output modifications
• Plugin verification demands isolated loading in temporary directories using the opencode load command with a custom OPENCODE_CONFIG_DIR
• Documentation sync necessitates copying skills/i-have-adhd/SKILL.md to .cursor/skills/i-have-adhd/SKILL.md and verifying with cmp
• Human verification fields must be completed in .github/pull_request_template.md with explicit evidence of testing
• Transparency requirements mandate documenting any skipped checks with justification to avoid PR closure for "lack of verification"

Frequently Asked Questions

What happens if I submit a pull request without completing all verification steps?

Maintainers may close the PR immediately for "lack of verification" if the Human verification field is empty or if required tests (unit tests, eval validation, or plugin loading checks) are missing from the description. The project treats verification documentation as a hard requirement, not merely a suggestion.

How do I handle verification when modifying plugin hooks specifically?

For hook changes in the hooks/ directory (such as always-on.mjs), you must load the altered hook in an isolated configuration directory as described in CONTRIBUTING.md. Use scripts/check_context_compat.ts to ensure context-compatibility code builds correctly, and document the temporary directory testing in your human verification statement.

Why is the SKILL.md file mirrored to the .cursor directory instead of using symlinks?

The repository maintains a hard copy at .cursor/skills/i-have-adhd/SKILL.md to ensure Cursor IDE compatibility without filesystem dependency on symlinks. The cp and cmp workflow guarantees that the canonical definition in skills/i-have-adhd/SKILL.md remains the source of truth while keeping the Cursor-specific path synchronized for users of that editor.

Can I submit a PR if one unit test fails but I explain the failure in the description?

No. According to the verification standards in CONTRIBUTING.md, all verification steps must pass before submission. If a test fails, you must fix the underlying issue or document explicitly why the check was omitted with detailed justification. Simply explaining failures without resolution violates the safety and quality standards required for the release-gate process.

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