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
|