Skip to content

#1055 Replace the lede doctrine with corpus-derived guidance and retire the changelog-writer - #1286

Merged
williamthorsen merged 8 commits into
mainfrom
1055
Aug 11, 2026
Merged

#1055 Replace the lede doctrine with corpus-derived guidance and retire the changelog-writer#1286
williamthorsen merged 8 commits into
mainfrom
1055

Conversation

@williamthorsen

@williamthorsen williamthorsen commented Aug 11, 2026

Copy link
Copy Markdown
Owner

What

Replaces the lede doctrine in lede-voice.md with 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-writer subagent is removed. summarize-change now composes the ## What section inline from the diff, and voice-checklist, commit, and merge-pr reach 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 feat and fix alone, 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.md drops 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, a Don't list of corpus-attested failure modes, an over-cutting counterweight, and distilled title rules.
  • Each per-type section covers one work type or a group of them, so every changelog-contributing key in work-types.json is reachable. Eight carry an exemplar drawn from the corpus.
  • The stance requires the opening to name the changed artifact or subsystem before the reader absorbs what the change did to it.
  • summarize-change composes ## What as its last step, from the branch diff and the ## Why and ## Details sections written before it, and audits the draft against voice-checklist before saving.
  • voice-checklist becomes 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

  • 🚨 Breaking: The changelog-writer subagent is removed, along with its write/rewrite/audit modes and the outcome-seed dispatch contract that fed it. Lede composition moves into summarize-change; the triage collection drops the member.

🐛 Bug fixes

  • commit points at the doctrine's Titles section by anchor instead of the retired "Title application" heading.
  • merge-pr's fresh-composition path and summarize-change's newspaper-style note no longer instruct the retired outcome frame.
  • The doctrine states where the release-notes register comes from, and records that a revert carries the work type of the change it undoes.

🧪 Tests

  • The create-pr closure test drops its assertion on the retired subagent.

📚 Documentation

  • _partials/README.md records that an include directive's leading whitespace governs recognition alone, so a directive cannot sit inside a list item.

Closes #1055

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.
@williamthorsen williamthorsen added breaking Breaking API change or removal of functionality feature Added or improved external functionality scope:agents labels Aug 11, 2026
@github-actions

Copy link
Copy Markdown

Dependency audit

Production dependency audit passed.

@williamthorsen
williamthorsen marked this pull request as ready for review August 11, 2026 09:00
@williamthorsen williamthorsen self-assigned this Aug 11, 2026
@williamthorsen williamthorsen removed the breaking Breaking API change or removal of functionality label Aug 11, 2026
@williamthorsen
williamthorsen merged commit 293007f into main Aug 11, 2026
3 checks passed
@williamthorsen
williamthorsen deleted the 1055 branch August 11, 2026 09:09
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature Added or improved external functionality scope:agents

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Replace the lede doctrine with corpus-derived guidance and retire the changelog-writer

1 participant