Hard rule
Complete steps 1–4 before git commit. Every commit path — plan todos, deploy
flows, user "commit and push", and handoffs from other skills — runs this pass
first; git prep elsewhere does not satisfy it.
When to use
- User or plan says commit, push, or "implement and deploy"
- Repo workflow (e.g. AGENTS.md) requires commit before push
- Another skill ends with "commit these changes"
- You are about to run
git commit for any reason
Does not replace
Git safety protocol (no amend unless allowed, no force push, no skip hooks) and
staging discipline (explicit paths, no secrets) stay in their owning rules. This
pass governs message quality and diff alignment only; hooks and CI remain the
server-side gate.
Commit-message pass
Run in order. Each step is complete only when its criterion is true.
Mode: draft the message unless the user explicitly asked to create the commit.
Commit mode adds repository mutation after Step 4.
- Learn the style and bound the change (run in parallel):
git log --oneline -20 and two full bodies with
git show --format='%B' -s <hash>git status --short and the complete staged diff (git diff --cached)
Classify every staged path and hunk as intended or unrelated. In draft mode,
report unrelated work without changing the index. In commit mode, restage only
within the user's commit authorization; ask when intended scope is ambiguous.
Criterion: the draft matches the repository's observed type, scope,
capitalization, and body conventions; every staged hunk has an intended
purpose with no unrelated hunk hidden inside the commit.
- Write the message. Use the repository's observed subject format and
capitalization. When history uses Conventional Commits, follow its
type(scope): summary shape. After one blank line, explain the problem, the
concrete constraint or evidence, and why this approach was chosen. Mention
intentional omissions and blocked follow-up when they affect the change.
Use prose for one cohesive change; use a Changes: list only for genuinely
independent changes. Ground why-claims in concrete files, symbols, errors,
behavior, or tickets.
Criterion: the subject states the intent, while the body adds reasoning that the
diff cannot show.
- Cross-check. Compare the message line by line with the staged diff. Remove
claims supported only by unstaged files, assumptions, or unrun validation.
Criterion: every staged change is accounted for, every why-claim has concrete
evidence, and the message contains no unrelated claim.
- State and deliver. Before
git commit (commit mode) or before returning
(draft mode), state in the reply: the chosen subject, one sentence of body
rationale, and any blocked follow-up (e.g. values not in this commit). In
commit mode, create the commit, then report its hash and whether unrelated work
remains in the working tree. Treat a commit as repository state only; report
deployment or validation only when its evidence was actually observed.
Criterion: the pre-commit statement is present; draft mode returns a
diff-grounded message only; commit mode distinguishes committed, uncommitted,
validated, deployed, and blocked states.
1---2name: writing-commit-messages3description: Required before every git commit. Run this pass when staging, committing, push, or any workflow says commit — plan todos, AGENTS.md deploy flow, user "commit and push", handoffs from other skills, or drafting feat(scope) from memory.4---56## Hard rule78Complete steps 1–4 before `git commit`. Every commit path — plan todos, deploy9flows, user "commit and push", and handoffs from other skills — runs this pass10first; git prep elsewhere does not satisfy it.1112## When to use1314- User or plan says commit, push, or "implement and deploy"15- Repo workflow (e.g. AGENTS.md) requires commit before push16- Another skill ends with "commit these changes"17- You are about to run `git commit` for any reason1819## Does not replace2021Git safety protocol (no amend unless allowed, no force push, no skip hooks) and22staging discipline (explicit paths, no secrets) stay in their owning rules. This23pass governs message quality and diff alignment only; hooks and CI remain the24server-side gate.2526## Commit-message pass2728Run in order. Each step is complete only when its criterion is true.2930**Mode:** draft the message unless the user explicitly asked to create the commit.31Commit mode adds repository mutation after Step 4.32331. **Learn the style and bound the change** (run in parallel):34 - `git log --oneline -20` and two full bodies with35 `git show --format='%B' -s <hash>`36 - `git status --short` and the complete staged diff (`git diff --cached`)37 Classify every staged path and hunk as intended or unrelated. In draft mode,38 report unrelated work without changing the index. In commit mode, restage only39 within the user's commit authorization; ask when intended scope is ambiguous.40 Criterion: the draft matches the repository's observed type, scope,41 capitalization, and body conventions; every staged hunk has an intended42 purpose with no unrelated hunk hidden inside the commit.432. **Write the message.** Use the repository's observed subject format and44 capitalization. When history uses Conventional Commits, follow its45 `type(scope): summary` shape. After one blank line, explain the problem, the46 concrete constraint or evidence, and why this approach was chosen. Mention47 intentional omissions and blocked follow-up when they affect the change.48 Use prose for one cohesive change; use a `Changes:` list only for genuinely49 independent changes. Ground why-claims in concrete files, symbols, errors,50 behavior, or tickets.51 Criterion: the subject states the intent, while the body adds reasoning that the52 diff cannot show.533. **Cross-check.** Compare the message line by line with the staged diff. Remove54 claims supported only by unstaged files, assumptions, or unrun validation.55 Criterion: every staged change is accounted for, every why-claim has concrete56 evidence, and the message contains no unrelated claim.574. **State and deliver.** Before `git commit` (commit mode) or before returning58 (draft mode), state in the reply: the chosen subject, one sentence of body59 rationale, and any blocked follow-up (e.g. values not in this commit). In60 commit mode, create the commit, then report its hash and whether unrelated work61 remains in the working tree. Treat a commit as repository state only; report62 deployment or validation only when its evidence was actually observed.63 Criterion: the pre-commit statement is present; draft mode returns a64 diff-grounded message only; commit mode distinguishes committed, uncommitted,65 validated, deployed, and blocked states.
lucavb