chore: rewrite README to lead with the problem, not the metaphor#19
Merged
Conversation
Old README led with "offline-prep dependency context for your LLM. Run
before you fly..." — clever metaphor, but the airplane/no-wifi case is
a niche use of the tool. The actual daily pain — "Claude suggests Rails
7 syntax on a Rails 8 app, misses CVEs from the last 6 months" — was
implicit and only landed once you scrolled past Install + Usage to the
sample document.
Rewrite informed by an internal multi-perspective copy review. Universal
findings: tagline buries the problem, sample output should appear early,
"Why" needs to be explicit, audience needs to be named in customer
language. A follow-up review pass on the rewrite itself surfaced five
additional refinements — all applied.
Changes:
- Tagline rewritten as a problem statement ("Stop Claude from
hallucinating on your Gemfile") with a subtitle that names the
artifact (markdown brief), the inputs (CVEs, breaking changes,
version deltas), and the supported models (Claude, GPT, or whatever).
- Sample output moved from the middle of the README to the very top —
immediately after the tagline. Demo before pitch.
- New "Why this exists" section makes the LLM-cutoff-vs-lockfile gap
explicit in four lines instead of leaving it implicit.
- Install paragraph compressed from a 60-word installer-deep-dive into
one sentence. The deep-dive belongs in INSTALL.md or FAQ, not on the
conversion path.
- Usage now leads with the simplest single-model invocation
(`postcut --model claude-opus-4-7`) so a first-run user isn't asked
to configure a models file before seeing output. Multi-model config
is positioned as the repeat-use path.
- Modes section preface trimmed — the table speaks for itself.
- Status now mentions the bash test count (~205, CI on every PR) so
the "I use postcut daily" line stands on credibility, not just on
vibes.
- Roadmap reframed as "where I need help": each entry has an explicit
contributor signal (`adapter:node` issue tag, "I'll pair on it") so
it's an invitation, not a solo declaration.
- New Community section — issues, discussions, and feedback channels
positioned as community signals rather than buried under Status.
- New "Why I built this" footer with the Tokyo-flight story moves the
airplane reference from headline (where it confused) to evidence
(where it adds personal texture). Founder signature at the bottom.
- Section order: Status → Why I built this → Roadmap → Community →
License. Personal note builds connection before the contributor ask
and the community channels.
No code changes. Tests untouched. Documentation only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
justi
force-pushed
the
chore/readme-rewrite
branch
from
00976ee to
ef41332
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.
Summary
Why
Old README buried the problem statement. A Rails dev landing on the page had to scroll past Install + Usage + Modes to reach the sample document that demonstrated value. By that point most readers had bounced.
Rewrite informed by an internal multi-perspective copy review. Universal findings: tagline buries the real problem, sample output should appear early, "Why this exists" needs to be explicit, audience needs to be named in customer language. Follow-up review pass surfaced 5 additional refinements — all applied (subtitle now mentions GPT alongside Claude, Usage leads with single-model invocation, "in flight" motif moved to footer, ~205 test count surfaced in Status, Roadmap last paragraph trimmed, Why-I-built-this moved between Status and Roadmap).
Concrete changes
adapter:nodeissue tagStats
Test plan
markdown lint(manual eyeball — proper heading hierarchy, no broken code blocks)wc -l README.md→ 138🤖 Generated with Claude Code