#1296 Hold the lede to a fixed budget and say what to cut first - #1298
Closed
williamthorsen wants to merge 4 commits into
Closed
#1296 Hold the lede to a fixed budget and say what to cut first#1298williamthorsen wants to merge 4 commits into
williamthorsen wants to merge 4 commits into
Conversation
The lede's budget is now fixed at one to three sentences regardless of how large the change is, and `lede-voice.md` says what gives way when it binds: a list that no longer fits is replaced by what the change amounts to, and what remains goes to the fact that summary does not imply. Mechanism is the first detail the budget cuts, except where the operation is itself what the change amounts to, as in a `refactor`.
The `Highlights` item in the voice checklist now tests whether the draft allocated its budget -- what the lede spent its sentences on and what it deferred to `## Details` -- rather than whether its first fact was the right one, which a catalog passes. A detail earns its place by being one the opening does not already imply, not by being large.
Changes the kept-detail test in `lede-voice.md` and `voice-checklist.md` from implication to noteworthiness: the detail worth a spare sentence is one a reader given the upshot could not have predicted, so an unimplied but ordinary fact no longer qualifies. The cut rule's worked example is now the `readyup` regroup, whose spare sentence went to a new lint rule rather than to the import churn every regroup entails, in place of a grocery analogy whose implied and unimplied items could each be read the other way. The surrounding additions are tightened: `Mechanism is substance` states its exception as the fact the lede keeps instead of an undefined "surviving fact" and cross-references the budget, `Punch the highlights` folds the nothing-is-lost assurance into the allocation question, and the checklist's Highlights item requires a deferral only from a change that outgrew the budget, so a small draft with nothing to defer passes.
Reconciles the fixed budget with `## Form`'s paragraph allowances in `lede-voice.md`: a lede is one to three sentences per concern, a second concern's paragraph is held to the same budget, a facet of the main change does not qualify as one, and only a second concern or migration info earns a further paragraph, never size. The checklist's Highlights item carries the same per-concern bound, so a compliant two-concern draft passes audit. Separately, the cut rule's handle is renamed from "Noteworthiness, not size, is the test" to "Unpredictability, not size, is the test", so the handle read alone names the prediction operation instead of re-asking the importance question the budget forbids.
Dependency auditProduction dependency audit passed. |
Owner
Author
|
Shelved unmerged. Superseded by #1299. |
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.
What
Sets an explicit sentence budget to improve the quality of ledes:
lede-voice.mdnow caps a lede at one to three sentences, and directs how to summarize when that length would be exceeded. Mere factual accuracy no longer justifies inclusion.voice-checklist.mdis revised to select highlights rather than listing every important fact, and that guidance reachessummarize-change,merge-pr, andcommit.Why
Nothing in the guidance said the budget was fixed or what to cut once it bound, so the length of a lede tracked the size of the diff: a large change got an entry reciting each mechanism it touched, with what the change amounted to buried inside it. The audit could not catch that, because its test passed on any lede whose first fact was correctly chosen, catalog or not.
Details
🐛 Bug fixes
## Detailsand the diff is what makes that question askable: without it, cutting reads as losing and every keep finds a justification.readyupregroup works both steps: six dispersed modules become "one level belowsrc/", and the spare sentence goes to a new lint rule banningutils/directories rather than to the import churn every regroup entails. The rule is floored against "Cut detail, not meaning" -- an upshot the reader cannot restate the change from has been abstracted past its job.refactoror aninternalrestructuring. That carve-out keeps the qualification from licensing a mechanism-free refactor lede.## Formscopes the budget per concern and closes the paragraph allowances as a growth path: a second concern's paragraph is held to the same budget, a facet of the main change does not qualify as a second concern, and only a second concern or migration info earns a further paragraph, never size._partials/voice-checklist.md's Highlights item tests the per-concern budget, whether anything was deferred, and whether each detail is unpredictable from the opening. Editing the partial reachessummarize-change,merge-pr, andcommitbyte-identically at install time, so no consumer skill is edited.Closes #1296