Tighten README — cut redundant sections, fix stale copy#62
Merged
Conversation
The README had three structural redundancies and a couple of stale claims that snuck through the api / inquirer drops. This pass tightens it from ~287 lines to ~204 (-29%) without losing substance. Structural cleanup: the "Four things you'll actually use this for" section restated "How Draftwise helps" in different words — merged into one JTBD-flavored section that names the moment AND the concrete command. The "What you get from each command" bullet section restated the Commands table — dropped. The Roadmap section's "v1 commands shipped on npm as of 0.0.1; next published release will be 0.1.0 after end-to-end smoke testing" claim was stale (we're on 0.2.1) and the checked-box list added no signal — dropped entirely. Killed a duplicated "🗺️ Explains" heading at the top of "How Draftwise helps" (one had a body, one was an empty stub). Copy fixes: scaffold.json provenance was "written by init in greenfield mode" — that's wrong post-api-drop; init prints a handoff and the host coding agent writes scaffold.json. Updated to "structured stack data for draftwise scaffold" without attributing the writer. The `draftwise scaffold` command line in the table also drops the now-stale "confirms before writing" wording — `--yes` is required upfront. The slash-commands install paragraph was a dense block; collapsed the marketplace alternative under a `<details>` and led with the recommended `skills install` snippet. Tone: kept the empathetic "The problem" framing but compressed six emoji-headed sections to three tight paragraphs that say the same thing without padding. Philosophy block, spec template details, and shields row stayed verbatim.
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
Pass over README.md applying clarity principles: cut redundancy, fix stale claims, tighten copy. Net delta: 287 → 204 lines (-29%) without losing substance.
🗺️ Explainsheading had no body; the next one did)as of 0.0.1; next release will be 0.1.0was stale (we're on 0.2.1) and the checked-box list added no signalinit--yesis required upfront, not "confirms before writing"<details>; led with the recommendedskills installsnippetTest plan
<details>collapsibles render correctly