Skip to content

Do not use second person when writing lede #1069

Description

@williamthorsen

Problem

Changelog and release-notes ledes — the ## What section of a PR body — drift into second-person address. The KB records seven occurrences across two repositories since mid-June, two rated high impact.

lede-voice.md models third-person register in every worked example but states no rule about grammatical person, so changelog-writer self-audits clean. One capture records the subagent reading Rule 1's outcome test ("what the reader will experience, see, or be able to do") as licensing direct address.

Proposed solution

Add a fourth rule to lede-voice.md, under "The rules":

Rule 4: No second person

Do not use the second person.

Under "The rules" rather than the "Voice" section: grammatical person is mechanically checkable in a way register and jargon are not, and "The rules" is the numbered set that voice-checklist.md mirrors and changelog-writer's audit output is keyed to.

One sentence, with no rationale paragraph and no Bad/Good pair — the doctrine's existing examples already model the register.

lede-voice.md and nothing else. Mirroring the rule into voice-checklist.md (reaching commit and merge-pr), adding a Rule 4: line to changelog-writer's audit-output template, and constraining the person of summarize-change's outcome: dispatch field are all deliberately deferred, so a later round can tell whether the single-surface change sufficed.

Acceptance criteria

Must have

  • lede-voice.md states an explicit prohibition on second-person address, placed under "The rules".
  • The rule is one sentence, with no added examples or rationale.
  • The change touches lede-voice.md and no other file.

Metadata

Metadata

Labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions