creating-commits

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Creating Commits

Create a commit using Chad's personal commit structure and message contract.

## Workflow

1. Inspect the working tree with `git status --short`.
2. Review the relevant diff before writing the message.
3. Read the commit template:
   ```bash
   git config --get commit.template
   ```
   The template owns the visible headings, separator, and ticket placeholder.
   This skill owns the authoring requirements below.
4. If the conversation was compacted or the user redirected the task after this
   skill was read, re-read this skill immediately before drafting the message.
5. For a pull-request commit, read the `creating-pull-requests` skill and draft
   the final, unwrapped PR body first. For a standalone commit, draft the
   message directly.
6. Apply the `writing-in-my-voice` skill to all prose sections.
7. Check the draft against the message content contract below.
8. Before committing, give the user a concise checkpoint confirming that the
   draft explains the problem, outcome, approach, and validation at a depth
   suited to the change's complexity, with relevant context, tradeoffs, and
   source links where applicable. State when no relevant external source exists.
9. Stage only the files that belong in this commit.
10. Create the commit with the generated message.

Do not run `git commit` until every applicable contract item is present. A
message with the right headings can still fail the contract.

## Message Content Contract

Write for a junior software engineer who has no prior context for the change.
The reader must understand the message without inspecting the diff or opening a
link first. Use plain language and define unfamiliar terms where they first
appear.

Scale the description to the complexity of the change and the context needed to
understand it. Simple changes usually need only a brief explanation in each
section. Complex changes need a more thorough account of the background,
reasoning, tradeoffs, and validation. Judge complexity by the reasoning and
context a reader needs: a small diff can require substantial explanation, and a
large mechanical change can be simple to explain.

Use the contract below to choose relevant content. It isn't a requirement for a
separate sentence or paragraph per bullet. Keep the problem, outcome, approach,
and validation clear; include supporting details only where they help the reader
understand or assess the change. Don't invent business stakes, alternatives, or
unfamiliar terms to fill out the message.

The `Why?` section must explain the problem and value, with relevant context:

- The existing system or behavior and the background needed to understand it.
- The concrete problem and its impact on the business: cost, risk, delay, lost
  revenue, support load, or a capability the company cannot offer yet.
- The value this change creates: who is unblocked, what we can ship or operate
  after this that we could not before, and why that matters now.
- Any unfamiliar project, tool, or domain term used in the explanation.
- Direct links to relevant ADRs, design documents, dependent or preceding pull
  requests, and maintained third-party documentation or repositories when those
  sources exist.

Never treat a ticket, plan, ADR, RFC, or "the user asked" as the reason for the
change. Those are pointers to the work. Sentences like "the ticket says so,"
"the plan calls for this," "this implements EE-1232," or "the RFC requires it"
fail the contract even when they are factually true. Name the operational or
business outcome instead. Links still belong in `Why?` as supporting sources;
they do not replace the value explanation.

The `How?` section must explain the approach and validation, with relevant
implementation detail:

- The chosen approach and the responsibilities of the important components.
- Meaningful tradeoffs or alternatives that affected the implementation.
- The validation commands and results, including why they provide useful
  evidence.
- Direct links to relevant implementation sources and third-party tools when
  those sources exist.

Links support the explanation; they do not replace it. Do not omit a relevant
source that is available in the task context. Skip details that are obvious from
the diff and avoid a step-by-step diary.

## Pull-request Commits

For a commit that will create a pull request, the complete unwrapped PR body is
the primary authoring artifact. Draft and validate it under the
`creating-pull-requests` skill first, then use the same title and prose for the
commit message, hard-wrapped at 72 characters. The wrapping rule controls line
width; it is not a target for message length.

## Stack-aware commits

When `wt-stack` is available, run `wt-stack --json status` before staging to
determine whether the current branch belongs to a Stack. A repository without
local Stack state continues through the normal workflow.

For a Stack-owned branch:

- Preserve the branch and review-unit boundaries from the
  `managing-stacked-changes` skill.
- Keep the commit scoped to the review unit owned by the current branch and
  worktree.
- Before the first `wt-stack sync`, derive the branch tip's commit title and
  body from the prepared PR title and body. `wt-stack` uses that commit to
  initialize a missing pull request.
- Leave rebasing and pushing to `wt-stack sync`. Do not push a Stack branch
  independently as part of a combined commit-and-publish request.

The commit-derived PR description is only an initial value. The
`creating-pull-requests` skill requires publishing and verifying the prepared
body after `wt-stack sync`. Once the pull request exists, later commits can
describe their incremental change because `wt-stack` does not replace existing
pull request metadata from those messages.

## Defaults

Unless the user already specified otherwise:

From chadxz/prompts, MIT.

More from chadxz/prompts