Stop the README claiming more than the table below it - #398
Merged
Conversation
CommitLore — record lintTrailers: clean — 0 commits in Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR. |
An external review found three sentences that the same file refutes. The hero said no fresh agent "can recover" the constraints, rejected alternatives, warnings and verification gaps. Sixty lines down, this README publishes a measurement in which ordinary `git log` recovers 42.0% of them at the same budget and 94.4% unbounded. The claim was not merely strong, it was one our own evidence section contradicts on the same page. What is actually true is narrower and survives the table: an agent inherits the implementation and does not inherit the judgment, because judgment does not travel with code unless something carries it. Two more were agent-behaviour claims this project has said, repeatedly and in this same file, that it cannot make. The pricing scene ended "the review never happens, because the decision was already there" -- an outcome no run here has observed. The demo caption said a fresh agent "still knows why", where what was demonstrated is that it is handed why. Both now say what was measured: the decision is in front of the agent before the edit rather than in a review comment after, and whether it acts on that is the open question M5 is running to answer. This is the failure mode the delivery paragraph was written to prevent, appearing three times above it. Publishing 81.7% beside "delivery, not effect" and then narrating an effect in the scene is worse than doing either alone, because a reader who notices stops trusting the careful paragraph too. Record-Id: r-claimsmatch Limit: this fixes the sentences an external reviewer found; no systematic pass was made over every claim in the four files against every published measurement Ruled-out: Softening the delivery paragraph instead | it is the accurate one, and the scene was the sentence out of step with it Ruled-out: Deleting the pricing scene | it is the clearest illustration in the README of what a record contains, and the defect was its last sentence rather than the scene Certainty: firm Blast: local Undo: easy Verified: readme, readme-order, readme-numbers, readme-positioning and compatibility-matrix pass at 83 across all four language files; check-readme-numbers.mjs exit 0 with the BENCH block byte-identical; spec/verify.sh OK at 26 fixtures; the beautify skill's audit reports no issues; the 42.0% and 94.4% figures were read out of this README's own evidence section rather than recalled Unverified: whether any comparable overstatement remains in docs/, which this change did not read
MongLong0214
force-pushed
the
docs-claims-match-evidence
branch
from
August 2, 2026 03:04
70dd2ed to
506ada4
Compare
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
1 participant
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.
An external review found three sentences the same file refutes. All three are live on
dev; a fourth item it raised — the hero image still showing the old positioning — was already fixed in #384 and is not part of this change.1. The hero contradicted our own measurement
Sixty lines below, this README publishes a table in which ordinary
git logrecovers 42.0% of them at the same budget and 94.4% unbounded. Not merely a strong claim — one our own evidence section refutes on the same page.What survives the table is narrower and true: an agent inherits the implementation and does not inherit the judgment, because judgment does not travel with code unless something carries it.
2 and 3. Two agent-behaviour claims we have said we cannot make
The first narrates an outcome no run here has observed. The second claims knowledge where what was demonstrated is delivery.
Why this mattered more than three sentences
This is exactly the failure the delivery paragraph was written to prevent, appearing three times above it. Publishing 81.7% beside "this measures delivery, not effect" and then narrating an effect in the scene is worse than doing either alone — a reader who notices stops trusting the careful paragraph too.
Applied to all four language files.
Verified
readme,readme-order,readme-numbers,readme-positioning,compatibility-matrixcheck-readme-numbers.mjsspec/verify.shbeautify-github-readmeauditStated limit: this fixes the sentences the reviewer found. No systematic pass was made over every claim in the four files against every published measurement.