Skip to content

Commit 86f8073

Browse files
Zacclaude
andcommitted
Rewrite README opening to be human-first
Lead with the scenario and problem the tool solves, not a dry technical description. Replace feature table with narrative differentiators. Technical details preserved in the back half. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 03da27f commit 86f8073

File tree

1 file changed

+8
-16
lines changed

1 file changed

+8
-16
lines changed

README.md

Lines changed: 8 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,7 @@
66
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
77
[![GitHub release](https://img.shields.io/github/v/release/cmdrvl/rvl)](https://github.com/cmdrvl/rvl/releases)
88

9-
**Reveal the smallest set of numeric changes that explain what actually changed.**
10-
11-
No AI. No inference. Pure deterministic arithmetic.
9+
**Two files. 50,000 cells. Something changed. What?**
1210

1311
```bash
1412
brew install cmdrvl/tap/rvl
@@ -18,22 +16,16 @@ brew install cmdrvl/tap/rvl
1816

1917
---
2018

21-
## TL;DR
22-
23-
**The Problem**: Comparing CSV exports by hand is slow and noisy — Excel hell, brittle scripts, eyeballing numbers. When two files differ, you need to know *what actually changed* and whether it matters.
19+
Two CSV exports. 50,000 numeric cells. Your boss wants to know what changed and whether it matters — by end of day. You could open Excel and start scrolling. You could write a pandas script and spend the afternoon debugging edge cases. Or you could ask for the answer.
2420

25-
**The Solution**: One command, one verdict. `rvl` finds the smallest ranked set of numeric deltas that explain the change — or proves nothing changed — using deterministic arithmetic. Never probabilistic. Never ambiguous.
21+
**rvl finds the smallest set of numeric changes that explain the difference.** Three cells out of 50,000, ranked by magnitude, accounting for 95.2% of all numeric change. That's the whole answer — not a diff of every row, not a spreadsheet full of deltas, just the cells that matter. If nothing changed, rvl proves it: every cell checked, max delta below tolerance, deterministic guarantee.
2622

27-
### Why Use rvl?
23+
### What makes this different
2824

29-
| Feature | What It Does |
30-
|---------|--------------|
31-
| **Ranked explanations** | Finds the fewest cells that account for ≥95% of total numeric change |
32-
| **Three clear outcomes** | REAL CHANGE, NO REAL CHANGE, or REFUSAL — never a partial answer |
33-
| **Tolerance-aware** | Ignores floating-point noise below your threshold — no false positives |
34-
| **Machine-readable** | `--json` output for pipelines, CI gates, and automation |
35-
| **Zero config** | Auto-detects delimiters, numeric formats, currency symbols, accounting parens |
36-
| **Deterministic** | Same inputs always produce the same output — no sampling, no heuristics |
25+
- **Explanations, not diffs** — rvl doesn't show you every change. It ranks cells by `abs(delta)` and prints only the smallest prefix that reaches your coverage threshold (default 95%). Three cells explaining 95% of change is more useful than 10,000 rows of diff output.
26+
- **Refuses instead of guessing** — if the top 25 contributors can't reach the threshold, rvl refuses with `E_DIFFUSE` instead of printing a misleading partial list. If rows are reordered without a key, it refuses with `E_NEED_KEY` and suggests which column to use.
27+
- **Zero config** — auto-detects delimiters, parses currency symbols (`$1,234.56`), accounting parentheses (`(123.45)` → negative), and thousands separators. No format flags needed.
28+
- **Tolerance built in** — floating-point noise below `1e-9` (configurable) is zeroed out. No false positives from rounding differences.
3729

3830
---
3931

0 commit comments

Comments
 (0)