playbook/skills/commit-message/SKILL.md

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