Skip to content

Require outcome-first framing in commit titles #446

Description

@williamthorsen

Problem

Nothing in the skill surface requires PR, commit, or change-summary titles to describe the outcome a change delivers rather than the mechanism it uses. Agents produce titles like "Pass Markdown bodies to gh via --body-file" that satisfy every written rule but leave readers with no sense of what was fixed, added, or improved. Because commit titles feed the changelog and (for release-notes-contributing work types) release notes, a mechanism-framed title is a gap in the reader-facing surface, not just a stylistic issue.

Context

The outcome-first discipline is already taught — but only for the body, not for the title:

  • summarize-change/SKILL.md ## What section (release-notes voice, "describe the accomplishment, not the edit", cross-type bad/good examples).
  • commit/SKILL.md and _data/commit-format.md cover body voice ("Release-notes voice… 'Fixes an issue where…'").

The existing title rule in commit/SKILL.md and _data/commit-format.md addresses a different axis: "describes the code change, not what prompted it" (Bad: "Address review findings"). That rule does not distinguish a mechanism title from an outcome title, so both pass.

commit/SKILL.md already opens by noting that commit titles are extracted into the changelog and release notes. The new rule hooks directly into that mental model: a reader scanning the changelog sees only the title.

Solution

  1. Extend the title rule in both commit/SKILL.md ## Title guidelines and _data/commit-format.md ## Title constraints with one additional bullet: titles must describe the outcome the change delivers, not the mechanism it uses, framed against the changelog/release-notes reader. Include a compact bad/good pair (e.g., dependency upgrade framed as version swap vs. security fix).

  2. Delete summarize-change/SKILL.md's ## Title guidance section entirely. Its current three bullets are about title sourcing (using the ticket title as input), not discipline. Change-summary titles will follow the same rule as commit titles through the downstream pipeline — no separate title discipline lives in summarize-change.

  3. No cross-references across skills. The rule is short enough to inline at point of use; indirection costs more than it saves for a one-line rule.

Acceptance criteria

  • commit/SKILL.md ## Title guidelines includes an outcome-vs-mechanism bullet framed against the changelog/release-notes reader, with a bad/good example.
  • _data/commit-format.md ## Title constraints includes the matching bullet with a bad/good example.
  • summarize-change/SKILL.md's ## Title guidance section is removed.
  • No new cross-references are introduced between the three skills for the new rule.
  • A future agent reading the updated guidance cold produces outcome-framed titles without further prompting.

Metadata

Metadata

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions