Menu
Draft and create git commits that preserve task and requirements context.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Create a pull request with a structured description derived from the branch commits, plus an optional guided tour of the changed files for reviewers.
Create a reviewable requirements document grounded in the user request and the current codebase.
Create an execution-ready markdown task list with nested checkboxes for one-task-at-a-time agent workflows.
| name | create-git-commit |
| description | Draft and create git commits that preserve task and requirements context. |
Use this skill when the user wants help drafting or creating a git commit after implementation work is complete.
A good commit message answers three questions for the next reader: why this change was needed now, what approach was chosen, and what the change enables or leaves for later. The rest of this skill is organized around four concerns that shape a commit message and one section on workflow.
A Final Self-Check at the end mirrors these sections so the last pass is easy to run.
Gather information from two places before writing.
Start with the planning docs when they exist:
./stevies/REQs.md./stevies/TODO.mdUse them to understand:
Do not simply restate these documents. Distill the context into the commit message. Do not include them as commit contents unless the user explicitly asks.
Then inspect the git state for decision-relevant details the planning docs may not capture:
git status --shortgit diff --staged when staged changes existgit diff when unstaged context mattersgit log -5 --oneline to match local commit styleThe diff and log often reveal incidental decisions (naming choices, structural tradeoffs, scope boundaries) that are worth surfacing in the commit message even when the planning docs don't mention them.
Ask before proceeding when any of the following are unclear:
Use specific questions like:
Do not invent motivation, ticket IDs, ticket URLs, tradeoffs, or future plans when they are not visible in the gathered context.
Structure the commit body around three concerns:
git show would already make obvious (file names, helper names, moved code, renamed variables, test file additions) unless a specific location is central to the decision.Keep a sentence only if it answers at least one of:
Remove anything a reviewer would assume was done or that has no lasting significance: test results, code formatting, build status, routine refactoring that doesn't change behavior.
The final body should still be useful when the reader already has the diff open.
Weak, because it repeats the diff:
Update worker prompt handling, add task ownership instructions, and adjust commit workflow guidance.
Strong, because it records the decision and consequence in plain words:
Make worker execution deterministic by keeping task ownership explicit
in the prompt instead of relying on runtime inference. This removes
coordination drift between parallel agents. Broader workflow
automation is a separate follow-up.
Weak, because it lists implementation mechanics:
Rename scratch queue fields, update references, and add tests for the new field names.
Strong, because it explains the reason for the shape of the change in the codebase's own vocabulary:
Standardize scratch queue naming around the runtime model so tooling
and worker prompts use the same words. Keeping the rename narrow
avoids mixing terminology cleanup with behavior changes, which makes
the follow-up automation work easier to review.
Use this format when preparing the final commit message:
[TICKET-KEY] Imperative title
<1-3 short paragraphs, more when the change genuinely needs the room>
ticket: <ticket-url>
Omit the ticket prefix and footer when no ticket information is available or expected by the repository style.
[TICKET-KEY].ticket: <ticket-url>.The primary ticket for this commit always uses a ticket reference. That's the "why are we here" link. Any work mentioned as context (scaffolding, prior work, related patterns, or follow-ups) should use the corresponding short commit hash instead.
Rationale: most git servers auto-convert commit hashes (e.g., abc1234) to clickable links, and a hash is a stable, immutable reference to the actual implementation. Use ticket references only when no commit hash is available.
Wrap every identifier that appears in the codebase in backticks so it renders as inline code. This includes function and method names (Notifier::send), types (MessageQueue), file paths (worker.cpp, config.yaml), configuration keys (status: ready), event names (user.created), CLI flags (--check), and any similar reference a reader could grep for.
The test is whether the token would exist as-is in the repository. If yes, backtick it. Plain English words that happen to sound technical (queue, producer, subscriber, publish, wire format) stay unquoted unless they are literally the name of something in the code.
Write the commit as if you are talking to a coworker who is about to pick up this code. The goal is to lower the bar to entry for the next person who reads it, not to sound authoritative or thorough. Detailed and approachable are the same thing here.
Prefer two short sentences over one long sentence.
—) as sentence joiners.;) as sentence joiners.When drafting a sentence, if it would naturally want an em-dash or semicolon in the middle, that is a signal to split it into two sentences.
The vocabulary bar is "words a competent engineer new to this codebase would recognize," not "words that would fit in a design document."
MessageQueue, Notifier, producer, subscriber, ticket, hook are all fair game when they already exist in the code or team's vocabulary.Weak, because it reaches for a sophisticated framing:
Route both events through MessageQueue::publish so Worker becomes a
queue producer like every other component, aligning it with the
single-fan-out model the rest of the system has already adopted.
Strong, because it says the same thing in plainer language and backticks the code:
Route both events through `MessageQueue::publish` so `Worker` uses
the message queue like every other component. The rest of the system
already publishes this way.
Weak, because it uses em-dashes as sentence joiners and imports outside vocabulary:
The message queue is becoming the single fan-out point for structured
events — producers publish once, and subscribers pick events up from
the queue rather than being called directly.
Strong, because it splits into short sentences and stays in the codebase's own words:
The message queue is becoming the one place structured events are
published. Producers publish once. Subscribers (`Notifier`, `Worker`,
future consumers) pick events up from the queue instead of being
called directly.
Rules for executing the commit itself, separate from the message content.
Before proposing or creating the commit, verify each section.
Content
Structure
[TICKET-KEY] prefix.Tone
A strong commit message should still help someone months later understand why this was done now, why this approach was chosen, and why the code is shaped this way. It should complement the diff, not duplicate it.