Skip to content

#446 Require outcome-first framing in commit titles #454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
williamthorsen merged 1 commit into from
Apr 20, 2026
Merged

#446 Require outcome-first framing in commit titles #454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/agents/content/skills/_data/commit-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ Common example: if a package is added to `packages/workspace-a`, that updates th

- **72 characters max** (hard limit).
- **Describes the code change, not what prompted it.** Ask: "what does the diff do?" Bad: "Address review findings". Good: "Add error logging to `handleStateUpdate`".
- **Describes the outcome, not the mechanism.** The title feeds the changelog and, for release-notes-contributing work types, the release notes — a reader scanning those sees only the title. Ask: "what does this change deliver?" — not "what did I edit?" Bad: "Upgrade hono from v1 to v2". Good: "Upgrade hono to patch authentication vulnerability".
- **No ephemeral references.** If it won't make sense to a reader who has only `git log`, leave it out.
- **Only document what's in the diff.** External actions (e.g., updating a ticket) don't belong.

Expand Down
1 change: 1 addition & 0 deletions packages/agents/content/skills/commit/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ Do not include the ticket ID in the commit title. The branch name carries it. In

- **Imperative, task-oriented voice.** "Add…", "Fix…", "Prevent…", "Enable…" — describing what the coder did. The title appears next to the PR number in release notes; it reads as the task. This voice is distinct from the body voice, which is declarative (see below).
- **Describes the code change, not what prompted it.** Ask: "what does the diff do?" — not "why did I open the editor?" Bad: "Address review findings", "Apply feedback", "Incorporate suggestions". Good: "Add error logging to handleStateUpdate", "Remove dead rejection handler".
- **Describes the outcome, not the mechanism.** The title feeds the changelog and, for release-notes-contributing work types, the release notes — a reader scanning those sees only the title. Ask: "what does this change deliver?" — not "what did I edit?" Bad: "Upgrade hono from v1 to v2". Good: "Upgrade hono to patch authentication vulnerability".
- **No ephemeral references.** If it won't make sense to a reader who has only `git log`, leave it out.
- **Only document what's in the diff.** External actions (e.g., updating a ticket) are not part of the commit and don't belong in its message.

Expand Down
8 changes: 0 additions & 8 deletions packages/agents/content/skills/summarize-change/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,14 +123,6 @@ The YAML frontmatter provides machine-readable metadata for downstream consumers

When used as a PR description, include **from `## What` onward only** — omit the H1 title and metadata block.

## Title guidance

When the original ticket is accessible:

- Use its title as input, not verbatim
- If the branch completes all ticket work, the ticket title may suffice
- For partial work, the title should reflect actual branch contents

## Saving

### Path resolution
Expand Down
Loading