99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
---
|
|
name: commit-message
|
|
description: "Use when the user asks for help writing a commit message, wants emoji/type(scope): subject formatting, or asks to review staged changes before committing."
|
|
---
|
|
|
|
# Commit Message（提交信息建议器）
|
|
|
|
## Overview
|
|
|
|
Turn a staged diff into a commit recommendation that matches repository policy.
|
|
Core principle: understand staged intent and commit boundaries before drafting the
|
|
message.
|
|
|
|
Authority source:
|
|
|
|
- `docs/common/commit_message.md`
|
|
- `docs/standards/playbook/docs/common/commit_message.md` (vendored playbook)
|
|
|
|
## When to Use
|
|
|
|
- The user asks to write or improve a commit message
|
|
- The user wants emoji/type(scope): subject formatting
|
|
- The user asks whether current staged changes should be split before commit
|
|
- The user asks to review staged changes before running `git commit`
|
|
|
|
## When Not to Use
|
|
|
|
- No staged changes exist and the user expects a final commit message based on the
|
|
actual staged diff
|
|
- The task is writing a PR title, release note, or changelog instead of a git
|
|
commit message
|
|
- The user already provided an exact commit message and only wants it executed
|
|
|
|
## Inputs
|
|
|
|
- Current staging state (`git status --short`, `git diff --cached`)
|
|
- Nearest applicable `commit_message.md`
|
|
- Whether the user wants suggestions only or a command-ready final message
|
|
|
|
## Procedure
|
|
|
|
1. **Baseline the repo state**
|
|
|
|
- Inspect staged and unstaged state separately.
|
|
- If nothing is staged, stop. Explain that a staged-diff-based recommendation
|
|
is unavailable and ask whether files should be staged first.
|
|
- If only unstaged changes exist, stop before proposing a final message. Offer
|
|
a draft only if the user explicitly wants one.
|
|
|
|
2. **Load the authority spec**
|
|
|
|
- Prefer the nearest `commit_message.md`.
|
|
- Reuse its type, emoji, scope, and body/footer conventions exactly.
|
|
|
|
3. **Summarize staged intent**
|
|
|
|
- Read the staged diff at the smallest useful granularity.
|
|
- Identify the main logical change, affected areas, and whether the staged set
|
|
mixes unrelated work.
|
|
- If staged changes combine unrelated goals, strongly recommend splitting the commit
|
|
before drafting a single message. In other words, strongly recommend splitting
|
|
the commit instead of hiding multiple intents behind one subject.
|
|
|
|
4. **Draft message options**
|
|
|
|
- Produce one recommended option and up to two alternatives.
|
|
- Keep the subject concrete, specific, and under the repo limit.
|
|
- Use body/footer only when they add real context such as motivation, impact,
|
|
verification, issue links, or breaking-change notes.
|
|
|
|
5. **Finalize safely**
|
|
|
|
- Make it explicit whether the output is a suggestion or a final chosen message.
|
|
- Do not run `git commit` unless the user explicitly asks for execution after
|
|
reviewing the recommendation.
|
|
|
|
## Output Contract
|
|
|
|
- `Detected:` staged files summary, dominant intent, and split/no-split judgment
|
|
- `Spec:` which `commit_message.md` was used
|
|
- `Proposed:` Option A (recommended), Option B, Option C
|
|
- `Optional body/footer:` only when justified
|
|
- `Notes:` risks, ambiguity, or split advice
|
|
|
|
## Success Criteria
|
|
|
|
- The recommendation matches the staged diff rather than guessed intent
|
|
- The selected format complies with the nearest commit policy
|
|
- Split advice appears when staged changes are logically mixed
|
|
- No commit command is executed unless the user asked for it
|
|
|
|
## Failure Handling
|
|
|
|
- If no staged diff exists, stop and explain the limitation instead of inventing a
|
|
final message
|
|
- If the staged set is too broad or ambiguous, recommend splitting and explain why
|
|
- If no local policy file is found, state the fallback convention before drafting
|
|
- If repo state changes during review, rerun the staged summary before finalizing
|