From d57b1796bbfc45d535fea94c0f98c24321d63dda Mon Sep 17 00:00:00 2001 From: Sinabina Date: Tue, 21 Jul 2026 15:03:02 -0700 Subject: [PATCH] docs: add anti-slop evidence bar to contribution guidelines Add a strict "evidence bar" section to CONTRIBUTING.md and a PR template that force every contribution to prove a human exercised the change: a human-written why, a live before/after evidence block, DCO sign-off, and a scope statement. Enumerate auto-closed categories (ETHOS edits, voice/YC cleanup, generated-file-only diffs, blind-AI-sweep PRs). CI enforcement (changeset-required, DCO check, generated-file guard) is documented as the next step tied to the Changesets migration rather than built speculatively. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/PULL_REQUEST_TEMPLATE.md | 36 +++++++++++++++++++ CONTRIBUTING.md | 62 ++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..17a8bcb75 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,36 @@ + + +## Why (in your own words) + + + +## Live evidence + + + +``` +# what you ran + what it produced +``` + +## Scope + +- **Changed:** +- **Verified live by:** +- **Did NOT test:** + +## Checklist + +- [ ] Commits are signed off (`git commit -s`) — DCO +- [ ] This is not a generated-file-only diff (I edited the source/template and regenerated) +- [ ] No ETHOS.md edits, and no changes to voice / founder perspective / YC references +- [ ] New public command / external service / host adapter has an accepted issue linked (or N/A) +- [ ] Linked issue or reproduction: # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff7a9292c..88891443b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,6 +73,68 @@ Host-specific generation and dev symlinking are not the canonical GStack 2 installation path. On this branch, `./setup` installs only the optional managed runtime; it no longer places host skills or accepts legacy setup flags. +## The evidence bar: prove a human ran this + +gstack is AI-coded and proud of it. That is exactly why the bar for a +contribution is **evidence of real use**, not lines of code. We close +plausible-looking changes that have no proof behind them, no matter how clean +they read. "I think this improves X" is not evidence. "Here is the command I +ran and the output before and after" is. + +**Every PR must show a human exercised the change.** Attach one of: + +- the reproduction for the bug you fixed (the failing state, then the fixed + state); +- the failing test you made pass; +- the actual session transcript or `claude -p` output showing the new skill + behavior; or +- for anything visual, before/after screenshots. + +A PR we cannot trace to a real reproduction, a real failing test, or a real +workflow you personally hit gets closed. This is the same standard CLAUDE.md +holds us to internally: **prove it or don't say it.** "Pre-existing failure," +"this obviously helps," and "should work" are not evidence. + +### Required on every PR + +1. **A human-written "why."** One paragraph in your own words: what breaks for + a user today, and what your change does about it. Generated boilerplate that + restates the diff is not a why. +2. **A live-evidence block.** The command(s) you ran and their real output — the + before, the after. Not `bun test` alone; the actual behavior you changed. +3. **`Signed-off-by` (DCO).** Commit with `git commit -s`. This is you + personally attesting you wrote or reviewed the change and have the right to + submit it. Unsigned commits do not merge. +4. **A scope statement.** Three lines: what changed, how you verified it *live*, + what you did not test. + +### Auto-closed, no discussion + +- **No ETHOS.md edits.** Ever. It is Garry's builder philosophy, not up for + contribution. +- **No "cleanup" of voice, founder perspective, or YC references.** These are + intentional. PRs framing them as "unprofessional," "too promotional," or + "unnecessary" are closed on sight. +- **No generated-file-only diffs.** If your PR only touches a generated file + (`*/SKILL.md`, `skills/*/references/legacy/`, `compat/`, `evals/parity/`), + you edited the output, not the source. Edit the template/input and regenerate. +- **No blind-AI-sweep PRs.** We are AI-coded, but a broad "I asked an AI to + improve the repo" change with no human-verified reproduction is slop. Show the + reproduction or it is closed. +- **New public command / external service / first-party host adapter without an + accepted issue linked first.** + +### What gets fast-tracked + +A linked issue you are fixing, a failing test you make pass, a live transcript +showing the improvement, a tight scope statement, and a signed commit. That PR +gets reviewed the same day. + +> **Coming with the Changesets migration:** the four requirements above will be +> enforced in CI — a required changeset (carrying the human "why"), a DCO check, +> and a generated-file-only-diff guard. Until then they are reviewer-enforced, +> and reviewers will hold the line. + ## Quick start For GStack 2 source work: