---
name: human-validated-prs
description: >-
  Add, review, or apply an open-source contribution policy for AI-assisted pull
  requests that requires personal human testing and human readiness approval.
  Use when creating or updating CONTRIBUTING.md, AGENTS.md, a pull request
  template, repository contribution rules, AI contribution guidance, or a
  neutral automated-draft hold notice. Allows agents to prepare work while
  reserving final PR submission and review readiness for a human.
metadata:
  internal: "false"
---

# Human-Validated Pull Requests

Create a transparent open-source contribution workflow in which agents may help prepare changes, but a human personally validates the result and owns the final request for review.

The policy is about accountable testing, not performative review. Do not require contributors to claim they inspected every line. Do not use embarrassing traps, false confessions, or punitive PR text.

## Establish the repository policy

Before editing, inspect the repository's existing `CONTRIBUTING.md`, `AGENTS.md`, `.github/pull_request_template.md`, issue or PR templates, test instructions, and release rules. Preserve compatible project-specific guidance and terminology.

For a new policy, establish these boundaries:

1. AI-assisted contributions are allowed unless the owner says otherwise.
2. A human must personally test or otherwise validate the change before requesting review.
3. The PR description must state what the human validated and how.
4. An agent may prepare changes, commits, and draft PR text.
5. A human must provide the final description and mark the PR ready for review.
6. Creating a branch, pushing, or opening a PR is a public/external action and still requires explicit user approval immediately before it occurs.

Do not add an AI-disclosure requirement unless the repository owner requests one. Human accountability and validation are the default requirement.

## Files and ownership

Use the repository's existing layout when present. The usual split is:

- `CONTRIBUTING.md` — public contributor policy and validation expectations.
- `AGENTS.md` — operational instructions for coding agents.
- `.github/pull_request_template.md` — concise human-validation checklist and a place to report evidence.

Keep all three consistent. Do not hide a policy in `AGENTS.md` that contradicts the public contribution rules.

Adapt the templates in [`references/templates.md`](references/templates.md) rather than replacing substantial existing documents wholesale.

## Human validation standard

Require validation appropriate to the change:

- Application or library code: personally run relevant automated tests and/or manually exercise the changed behavior.
- UI changes: personally inspect the affected interface in addition to relevant automated checks.
- Documentation: personally check rendering, links, examples, and formatting as applicable.
- Configuration or packaging: personally exercise the relevant validation, build, install, or dry-run path where practical.

The human should report the commands run and/or behavior checked. Do not claim a human performed a check unless they explicitly confirm it.

If required validation cannot be performed, leave the PR as a draft and say what remains unverified. Do not present automated agent execution alone as personal human testing.

## Agent behavior when asked to create a PR

1. Prepare the changes, validation summary, and proposed PR description.
2. Explain that repository policy reserves the final description and readiness decision for a human.
3. Ask the user to review, personally test, and publish or mark the PR ready.
4. Do not push or create a PR without explicit approval for that specific external action.

If the user explicitly insists that the agent create the PR after the policy is explained:

- create **only a draft PR**;
- use the neutral automated-draft hold notice from the template;
- include useful implementation and automated-validation details below the notice when appropriate;
- do not check human-validation attestations;
- do not mark the PR ready for review;
- tell the user they must personally test the change, replace the notice, complete the validation section, and mark it ready.

The hold notice is a workflow state, not a joke or punishment. It must remain truthful. If the human has already supplied and approved the final description and personally confirmed validation, do not claim that they have not.

## Review an existing policy

Check for these failure modes:

- requiring an unverifiable claim that every line was reviewed;
- treating agent-run tests as personal human validation;
- allowing an agent to mark its own PR ready;
- hidden instructions that publicly embarrass contributors;
- false or misleading PR metadata;
- contradictory rules across contribution, agent, and PR-template files;
- no accommodation for documentation-only or otherwise non-runtime changes;
- no clear path when testing cannot be completed.

Recommend the smallest edits that make the policy transparent and consistent.

## Completion report

Report:

- files created or updated;
- the human validation requirement;
- what agents may prepare;
- which actions remain human-controlled;
- the draft fallback behavior and exact hold notice;
- any project-specific test commands still needing confirmation.