From b43170752af1fc1b5a0d31c5cfc59ebc2f31e130 Mon Sep 17 00:00:00 2001 From: Hongsheng Liu Date: Mon, 12 Oct 2026 07:00:39 +0800 Subject: [PATCH 1/2] docs: require human contributor intent before implementation and PR submission --- .claude/skills/precheck-pr/SKILL.md | 43 +++++++++++++++++++++++++++++ CONTRIBUTING.md | 7 +++++ 2 files changed, 50 insertions(+) diff --git a/.claude/skills/precheck-pr/SKILL.md b/.claude/skills/precheck-pr/SKILL.md index f53d57c..e124042 100644 --- a/.claude/skills/precheck-pr/SKILL.md +++ b/.claude/skills/precheck-pr/SKILL.md @@ -11,6 +11,49 @@ including "just tests" and "just docs" PRs; three of the five findings in #102's pass were in a test-only diff, one of them introduced by the pass itself and caught only by the re-run gate (step 6). +## Human contributor-intent gate + +Apply this gate to contributor planning, implementation, and author self-review +before PR submission. It does not block an independent read-only review or +change automated reviewer selection. + +Before implementation, have the human contributor explicitly answer: + +1. What outcome are you trying to achieve? +2. What is the highest-leverage variable for that outcome? +3. How will this proposed work move that variable, rather than merely create + activity or busywork? +4. Who is the customer or user, and what do they actually need? + +Reuse explicit human answers already present in the request, issue, or +discussion, citing their source. Ask only for missing or ambiguous answers and +wait for the human's response before proceeding with implementation or +submission. Do not invent answers, silently infer intent from a diff, or +complete this gate on the human's behalf. + +After those answers are clear, ask the human: **Is a PR needed at all?** +Consider whether an existing capability, a usage/configuration change, an +answer, or an investigation already meets the need. Reuse an explicit, +traceable human decision if one already exists; otherwise wait for it. If the +answer is no or remains unresolved, stop PR-bound work and report the next +step for the human to choose. + +For a bugfix, link evidence of an actual observed failure: a reproducible case, +failing test output, logs, or an issue/report describing what happened and what +was expected. Label evidence that has not been reproduced locally. A +hypothetical risk is not observed failure evidence; ask for the missing +evidence rather than manufacture it. + +At pre-PR self-review, confirm that the final diff still serves the recorded +outcome, variable, customer need, and PR decision. If intent or scope materially +changed, return only the changed or missing decisions to the human and wait. +Include a concise source-linked record in the existing issue or PR description; +do not create a duplicate planning artifact or copy private discussion into a +public PR. This gate supplements all existing validation and authorization +requirements. + +Contributor guide: [CONTRIBUTING.md](../../../CONTRIBUTING.md). + ## Step 1: Freeze the diff ```bash diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f3f7c4..b5308b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,6 +66,13 @@ python -m unittest tests.tts.test_stream_loop # one file at a time in prac past it means re-verifying every vendored function against the new source (an adaptation PR, not a version bump). +## Before implementation: contributor intent + +Complete the human [contributor-intent gate](.claude/skills/precheck-pr/SKILL.md#human-contributor-intent-gate) +before implementation and recheck it before PR submission. Reuse explicit, +traceable human answers; ask only missing questions and wait. The gate applies +to contributor work, not independent read-only review or reviewer selection. + ## Before you open the PR: the precheck (must) Run the repo's author-side self-check before declaring a PR ready — From 8ff0083ef282724d57a865092975e3db847a54f5 Mon Sep 17 00:00:00 2001 From: Hongsheng Liu Date: Mon, 12 Oct 2026 07:19:17 +0800 Subject: [PATCH 2/2] docs: require human intent answers in the PR template --- .claude/skills/precheck-pr/SKILL.md | 9 ++++++++ .github/pull_request_template.md | 33 +++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.claude/skills/precheck-pr/SKILL.md b/.claude/skills/precheck-pr/SKILL.md index e124042..865d4f8 100644 --- a/.claude/skills/precheck-pr/SKILL.md +++ b/.claude/skills/precheck-pr/SKILL.md @@ -52,6 +52,15 @@ do not create a duplicate planning artifact or copy private discussion into a public PR. This gate supplements all existing validation and authorization requirements. +Before submission, inspect the actual PR description against the +[PR template](../../../.github/pull_request_template.md). All four required human +answers and the PR-necessity decision must be complete, with observed failure +evidence for a bugfix. Blank fields, placeholders, agent-invented answers, and +unresolved source references are blockers: ask the human only for what is +missing and wait. Reuse explicit, traceable answers instead of asking again. +This is a contributor workflow constraint; the Markdown template does not +provide server-side enforcement. + Contributor guide: [CONTRIBUTING.md](../../../CONTRIBUTING.md). ## Step 1: Freeze the diff diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..21e75ab --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,33 @@ +# Pull request + +## Required human contributor answers + +The human contributor must answer all four questions before PR submission. +An explicit answer already recorded elsewhere may be referenced with a precise, +accessible source; a bare link without an identifiable answer is insufficient. +Agents must not invent or fill in the human's answers. Blank, placeholder, or +unresolved answers do not complete this gate. See the +[contributor-intent gate](../.claude/skills/precheck-pr/SKILL.md#human-contributor-intent-gate) +and [contributing guide](../CONTRIBUTING.md). + +### 1. What outcome are you trying to achieve? + +### 2. What is the highest-leverage variable for that outcome? + +### 3. How will this work move that variable rather than create busywork? + +### 4. Who is the customer or user, and what do they actually need? + +### PR necessity and bugfix evidence + +After answering the four questions, explicitly state whether a PR is needed +at all and why. Reuse a traceable human decision if already recorded; otherwise +wait for the human to decide. For a bugfix, link the actual observed failure +(reproducer, failing test output, logs, or issue/report with expected versus +actual behavior); state whether it was reproduced locally. + +## Summary + +## Validation + +Describe checks run, results, skips, and remaining validation gaps.