#1055 Replace the lede doctrine with corpus-derived guidance and retire the changelog-writer - #1286
Merged
Conversation
Replaces the content of `lede-voice.md`. The guidance now makes the change itself the lede's subject and treats mechanism as substance, where before it framed every lede as a user-facing outcome and screened drafts through three subtractive rules. Per-type sections direct what each kind of change reports -- feat and perf, fix, sec, refactor, internal, docs, ai, deps, tests, tooling and ci, drop and deprecate, revert -- each anchored by an exemplar drawn from the lede-decision corpus. The filename is unchanged, so `capture-lede-decision` fingerprints the replacement as a new doctrine generation with no code change.
Replaces the three-rule checklist with six checks that test a draft against the replacement doctrine: subject, per-type section, names, highlights, claims, and cuts. The checks no longer reproduce whole rules, and they no longer point at the `Voice` and `Jargon at the lede` sections, which the replacement does not carry. `commit` and `merge-pr` reach the doctrine only through this partial, so both pick up the new checks without an edit of their own.
`summarize-change` now composes `## What` itself, last, after `## Why` and `## Details`, reading `lede-voice.md` in full and applying the per-type section for the change's work type. The `changelog-writer` dispatch it went through is gone, along with the mechanism-free `outcome` seed the dispatch required and the delete-only rule that capped what the caller could change in the returned draft. The tier resolution that fed the dispatch goes with it, since the replacement doctrine carries register in its per-type sections. `work-types.json` tier order still orders the `## Details` subsections.
Removes the `changelog-writer` subagent. `summarize-change` composes `## What` itself under `lede-voice.md`, so nothing dispatches it. A declaration naming `changelog-writer` no longer resolves; drop the entry.
The pointer to title guidance named a `Title application` section that the replacement doctrine does not carry, and summarized it as outcome-not-mechanism, which the replacement inverts. It now links to the doctrine's `Titles` section and names what that section covers.
The doctrine's stance now directs the opening to name the artifact or subsystem changed -- the package, command, file, or rule -- before the reader takes in what the change did to it, and anchors the rule in a corpus lede that does so in four words. The two sanctioned openings previously left a scenario clause free to reach the name late.
`summarize-change` now audits the `## What` it composes before saving it, through the same `voice-checklist` partial `commit` and `merge-pr` include at their compose sites; the retired subagent's mandatory self-audit had left with it. The skill's newspaper-style note and `merge-pr`'s fresh-composition instruction no longer describe the lede as a reader-facing outcome, the frame the replacement doctrine retires. The doctrine now says where the release-notes register comes from: a change reaches release notes when its work type sits in the public tier of `work-types.json`. The `revert` bullet records that a revert carries the work type of the change it undoes, since `revert` is not itself a key there. The checklist drops its own fact count, which contradicted the doctrine at both ends.
Adds a clause to `_partials/README.md` recording that an include directive's leading whitespace governs recognition alone: injected lines keep the partial's own indentation, so a directive cannot sit inside a list item.
Dependency auditProduction dependency audit passed. |
williamthorsen
marked this pull request as ready for review
August 11, 2026 09:00
8 tasks
williamthorsen
added a commit
that referenced
this pull request
Aug 13, 2026
…e-v0.3.0 codeassembly-v0.9.0 factory-v0.2.6 codeassembly-mcp-v0.2.5 codeassembly-v0.9.0 - #1288 feat: State mutability and name the lede reader at the artifact type lists (#1303) - #1285 fix: Require plain bullets for checklists on both update-jira-ticket paths (#1302) - deps: Upgrade all deps to latest version - #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301) - #1294 feat: Specify artifact mutability and its sanctioned exceptions (#1297) - #1293 fix: Present and classify discretionary findings as actionable (#1295) - #1289 tooling: Remove shelled nmr calls from package manifests (#1291) - #1280 feat: Add a refresh path that edits an existing AGENTS.md instead of redrafting it (#1287) - #1055 feat: Replace the lede doctrine with corpus-derived guidance and retire the changelog-writer (#1286) - deps: Upgrade all deps to latest version - #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284) - #1263 refactor: Retire the deferred-lint mechanism and adopt toolbelt.errors in agents (#1279) - #1262 refactor: Hoist unreadable for-of expressions and promote the lint rule to an error (#1276) - #1267 fix: Extend the no-hard-wrapping instruction to every GitHub composer (#1275) - #1177 fix: Rewrite links, tokens, and template variables in a Markdown file support entry (#1273) - #1176 feat: Add a ticketing-preferences hook to the skills that split and create tickets (#1268) - #1252 fix: Keep a skill's own sections out of injected guidance (#1266) - #1260 refactor: Fix lint and retire rule deferrals (#1265) - #1247 feat: Add a personal tooling-preferences rulebook (#1257) - #1251 feat: Let a rulebook declare that a guidance hook is how it is reached (#1259) - #1246 feat: Guard home-domain writes and record their provenance (#1254) - #1175 feat: Link new tickets to their blockers and parents (#1249) factory-v0.2.6 - deps: Upgrade all deps to latest version - #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301) - deps: Upgrade all deps to latest version - deps: Upgrade all deps to latest version - #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284) kb-v0.6.0 - deps: Upgrade all deps to latest version - #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301) - #1289 tooling: Remove shelled nmr calls from package manifests (#1291) - #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284) - #1261 feat: Attach causes to kb's loader errors and retire its lint deferral (#1272) - #1260 refactor: Fix lint and retire rule deferrals (#1265) codeassembly-lifecycle-v0.4.0 - #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301) - #1289 tooling: Remove shelled nmr calls from package manifests (#1291) - #1261 feat: Attach causes to kb's loader errors and retire its lint deferral (#1272) - #1260 refactor: Fix lint and retire rule deferrals (#1265) codeassembly-mcp-v0.2.5 - deps: Upgrade all deps to latest version - #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301) - #1289 tooling: Remove shelled nmr calls from package manifests (#1291) - #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284) codeassembly-run-core-v0.3.0 - deps: Upgrade all deps to latest version - #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301) - #1289 tooling: Remove shelled nmr calls from package manifests (#1291) - #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284) - #1261 feat: Attach causes to kb's loader errors and retire its lint deferral (#1272) - #1260 refactor: Fix lint and retire rule deferrals (#1265)
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
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
Replaces the lede doctrine in
lede-voice.mdwith corpus-derived guidance: The change is the subject of a lede, mechanism is substance rather than detail to route away, and 11 per-type sections, most anchored by an author-approved exemplar, take the place of four general rules.The
changelog-writersubagent is removed.summarize-changenow composes the## Whatsection inline from the diff, andvoice-checklist,commit, andmerge-prreach the doctrine by reference.Why
Nearly every agent-written lede was rewritten by hand before merge: the lede-decision corpus records 167 revised decisions against 25 accepted, and the author comments name the guidance itself as the cause. The doctrine's user-facing-outcome frame fit
featandfixalone, its rules were cut-screens that an unreadable draft could fully satisfy, and the dispatch pipeline required a mechanism-free seed that deleted the substance of refactor, docs, tooling, and deps changes before composition began.Details
🎉 Features
lede-voice.mddrops from 245 lines to 73. The four numbered rules, the identifier ban, and the jargon section give way to a stance (the change is the subject; every sentence reports an effect of the diff; mechanism is substance; name things; punch the highlights; claims match the diff), a form section, eleven per-type sections, aDon'tlist of corpus-attested failure modes, an over-cutting counterweight, and distilled title rules.work-types.jsonis reachable. Eight carry an exemplar drawn from the corpus.summarize-changecomposes## Whatas its last step, from the branch diff and the## Whyand## Detailssections written before it, and audits the draft againstvoice-checklistbefore saving.voice-checklistbecomes a six-item pre-save audit over subject, type, names, highlights, claims, and cuts, pointing at the doctrine for the substance rather than restating its rules.🪦 Removed
changelog-writersubagent is removed, along with itswrite/rewrite/auditmodes and theoutcome-seed dispatch contract that fed it. Lede composition moves intosummarize-change; thetriagecollection drops the member.🐛 Bug fixes
commitpoints at the doctrine'sTitlessection by anchor instead of the retired "Title application" heading.merge-pr's fresh-composition path andsummarize-change's newspaper-style note no longer instruct the retired outcome frame.🧪 Tests
create-prclosure test drops its assertion on the retired subagent.📚 Documentation
_partials/README.mdrecords that an include directive's leading whitespace governs recognition alone, so a directive cannot sit inside a list item.Closes #1055