What is wrong
The README is 418 lines and reads as a paper. It is accurate, hedged in the right places, and almost nobody who lands on it from a link will reach the part that would make them install it.
Concretely, in reading order a first-time visitor gets: hero, badges, four language links, the thesis in the abstract ("inherit the judgment"), install instructions for two paths, a compatibility link, a demo, three dense evidence sections with their caveats in bold, and only then — around line 152 — the concrete before/after that actually shows the pain:
calculatePrice(input, { isAdminPreview: true, skipCoupon: true });
The reviewer writes "we already rejected this" for the second time.
That paragraph is the product. It is below three sections whose job is to stop a skeptic, addressed to a skeptic who has not arrived yet.
Why it matters now
Distribution is the binding constraint, not evidence. This repository already has more measured evidence than most tools its age. What it does not have is a reader who gets to it.
What to change
- The concrete before/after moves above the evidence sections
- Caveats stay, one layer down, in
docs/evidence.md where they already live
- The 10-second question — what breaks without this, and what does installing it cost me — gets answered before any table
What not to change
The honesty. **This measures delivery, not effect.** stays a sentence this project writes about its own numbers; it just does not need to be the third thing a stranger reads.
Constraint
test/readme.test.ts owns the READMEs' claims and test/compatibility-matrix.test.ts pins one pointer line per README. Four language READMEs must stay consistent.
What is wrong
The README is 418 lines and reads as a paper. It is accurate, hedged in the right places, and almost nobody who lands on it from a link will reach the part that would make them install it.
Concretely, in reading order a first-time visitor gets: hero, badges, four language links, the thesis in the abstract ("inherit the judgment"), install instructions for two paths, a compatibility link, a demo, three dense evidence sections with their caveats in bold, and only then — around line 152 — the concrete before/after that actually shows the pain:
That paragraph is the product. It is below three sections whose job is to stop a skeptic, addressed to a skeptic who has not arrived yet.
Why it matters now
Distribution is the binding constraint, not evidence. This repository already has more measured evidence than most tools its age. What it does not have is a reader who gets to it.
What to change
docs/evidence.mdwhere they already liveWhat not to change
The honesty.
**This measures delivery, not effect.**stays a sentence this project writes about its own numbers; it just does not need to be the third thing a stranger reads.Constraint
test/readme.test.tsowns the READMEs' claims andtest/compatibility-matrix.test.tspins one pointer line per README. Four language READMEs must stay consistent.