Skip to content

docs: lead with the one check nothing else does, and cut the install to one option - #188

Merged
sjh9714 merged 1 commit into
mainfrom
docs/lead-with-what-nobody-else-checks
Aug 6, 2026
Merged

docs: lead with the one check nothing else does, and cut the install to one option#188
sjh9714 merged 1 commit into
mainfrom
docs/lead-with-what-nobody-else-checks

Conversation

@sjh9714

@sjh9714 sjh9714 commented Aug 6, 2026

Copy link
Copy Markdown
Owner

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. It
then 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-slop
has 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:

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 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:

Removed Why it was inert
github-token action.yml already defaults it to ${{ github.token }}
mode: warn packages/core/src/config/schema.ts:431 already defaults to "warn"
fail-on-block: false packages/action/src/run.ts:523 only fires on decision === "block", which warn mode never produces

templates/mergewarden-observe.yml loses its with: block entirely.

comment's default is deliberately not changed. Making auto the default
would warn on any workflow granting only pull-requests: read, which is the
trap 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 create
    one and the fact that no scopes are needed.
  • README.zh-CN.md gets the new opening plus an explicit note that the rest is
    still the older structure.
  • documentation.test.ts asserted the old heading order, so it asserts the new
    one. 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.

…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
sjh9714 merged commit 37f333a into main Aug 6, 2026
8 checks passed
@sjh9714
sjh9714 deleted the docs/lead-with-what-nobody-else-checks branch August 6, 2026 07:38
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant