docs: lead with the one check nothing else does, and cut the install to one option - #188
Merged
Merged
Conversation
…to one option The README opened with "AI coding tools open pull requests faster than anyone can read them", which is a claim about the world rather than about the reader. Then it told a made-up story lifted from the demo fixture, and the first thing it asked anyone to do was run a demo of a synthetic pull request. Nobody runs a demo of a tool they have not yet decided they need. What people who actually receive pull requests want is for the queue to shrink. peakoss/anti-slop has 751 stars for "automatically closes low-quality and AI slop PRs", written by a Coolify maintainer taking 120+ of them a month. MergeWarden refuses to close anything, on purpose. Rewriting the README does not close that gap and this commit does not claim to. What it does do is put first the one thing that appears to be uncontested: a pull request that edits the files instructing your coding agents. anti-slop's 34 rules do not cover it, and a search for repositories doing the same turned up nothing above 30 stars. Verified before writing the copy rather than after. A pull request titled "docs: tidy up the contributor notes", whose entire diff is one added line in CLAUDE.md, produces exactly the comment the README quotes: sjh9714/agent-gate-install-smoke-20260617#22 That run also reports "Agent detected: no", so the check does not depend on the pull request being agent-authored. The 3.9% figure stays in. It is not a daily event and pretending otherwise would repeat the mistake this project has already made once. Install drops from four options to one. Three were doing nothing: github-token action.yml already defaults it to ${{ github.token }} mode: warn schema.ts:431 already defaults to "warn" fail-on-block run.ts:523 only fires on decision === "block", which warn mode never produces templates/mergewarden-observe.yml loses its `with:` block entirely for the same reason. comment's default is left alone: making `auto` the default would warn on any workflow granting only pull-requests: read, which is the trap fixed in #180. triage's token requirement moves above the command instead of below it, with a link to create one and the fact that no scopes are needed. The Chinese README gets the new opening and an explicit note that the rest of it is still the older structure.
sjh9714
added a commit
that referenced
this pull request
Aug 6, 2026
… for its own failures (#189) npm still serves 0.10.1, where running the command this project tells people to run first, on a public repository, with no token, prints: 20 open pull request(s) read. 14 have something a maintainer checks by hand. #10586 gci-fun-1 could not be read ... and exits 0. Nine of those fourteen were GitHub refusing the request after 60 unauthenticated calls an hour, not pull requests needing attention. The fix merged in #187 and has not reached anybody. Also ships the README rewrite from #188: it leads with the check nothing else appears to make, and install drops from four options to one because three of them were doing nothing. Verified in the order the last release taught. `pnpm audit` with no severity filter was run before the tag, not after: 0.10.0 was tagged and then rejected by the release gate for two moderate advisories, which is how a tag ends up pointing at something that never shipped. Checked against the packed tarballs rather than the source tree, since the source has always worked and that is exactly what hid this: cold install into an empty directory reports 0.10.2 and triages a real repository. No workspace:* and no private runtime dependency; 190 KB and 92 KB compressed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was wrong
The README opened with a claim about the world (
AI coding tools open pull requests faster than anyone can read them) rather than about the reader. Itthen told a story lifted from the demo fixture, and the first action it asked
for was running a demo of a synthetic pull request. Nobody runs a demo of a
tool they have not decided they need.
What people receiving pull requests actually want
They want the queue to shrink.
peakoss/anti-slophas 751 stars for "detects and automatically closes low-quality and AI slop
PRs", written by a Coolify maintainer taking 120+ a month.
Its own users then file: #19
closed pull requests cannot be reopened, #16
the spam-username rule flags legitimate people, #13
the failure message does not say which check failed.
So the order is removal first, accuracy and reasons second. MergeWarden
refuses removal on purpose and only does the second. This pull request does not
close that gap and does not claim to.
What it does instead
It puts first the one thing that appears uncontested: a pull request that edits
the files instructing your coding agents. anti-slop's 34 rules do not cover it,
and searching for repositories doing the same turned up nothing above 30 stars.
Verified before the copy was written, not after. A pull request titled
"docs: tidy up the contributor notes", whose entire diff is one added line in
CLAUDE.md, produces exactly the comment the README quotes:That run also reports
Agent detected: no, so the check does not depend on thepull request being agent-authored. The README says so.
The 3.9% figure stays in the README. It is not a daily event, and inflating
it would repeat a mistake this project has already made.
Install: four options to one
Three were doing nothing at all:
github-tokenaction.ymlalready defaults it to${{ github.token }}mode: warnpackages/core/src/config/schema.ts:431already defaults to"warn"fail-on-block: falsepackages/action/src/run.ts:523only fires ondecision === "block", which warn mode never producestemplates/mergewarden-observe.ymlloses itswith:block entirely.comment's default is deliberately not changed. Makingautothe defaultwould warn on any workflow granting only
pull-requests: read, which is thetrap fixed in #180.
The reduced snippet is the one that produced the run linked above, so it is
verified rather than assumed.
Also
triage's token requirement moves above the command, with a link to createone and the fact that no scopes are needed.
README.zh-CN.mdgets the new opening plus an explicit note that the rest isstill the older structure.
documentation.test.tsasserted the old heading order, so it asserts the newone. The 300-line and 1,500-word limits are unchanged: 190 lines, 1,093 words.
Verification
pnpm build && pnpm test && pnpm typecheck && pnpm lint && pnpm format:check,all green (461 tests). No em-dashes in any user-facing document.