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

> Complete the 8-step pull request verification checklist for i-have-adhd. Ensure your contributions pass automated tests, behavioral evaluation, and human review before submitting.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: best-practices
- Published: 2026-08-29

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) (lines 77-84), the project requires executing the unittest discovery command against the entire test tree:

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) (lines 81-84), use the following command to verify eval integrity:

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) specifies loading the altered component in a temporary configuration directory:

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts).

## Documentation Synchronization

### Synchronize the Canonical Skill File

When editing [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), contributors must maintain parity with the Cursor-compatible mirror. Per [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) (lines 68-74), copy the canonical skill file to the mirrored location and verify byte-for-byte equality:

```bash
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`](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) 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`](https://github.com/ayghri/i-have-adhd/blob/main/.github/pull_request_template.md) (line 15), contributors must include a explicit statement of what commands were executed and what was manually inspected:

```markdown
**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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) to [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) and verifying with `cmp`
- **Human verification** fields must be completed in [`.github/pull_request_template.md`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md). Use [`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.