---
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