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

Create a repository-compliant recommendation from the staged diff. Resolve its
boundary and enforced rules before drafting.

## When to Use

Use for commit-message drafting, staged-boundary review, split decisions, or
emoji/type(scope): subject formatting.

## When Not to Use

Do not use for PR titles, release notes, changelogs, or exact-message execution.

## Inputs

Use staged/unstaged state and repository policy.

## Procedure

1. **Baseline state**

   - Inspect staged and unstaged changes separately.
   - If nothing is staged, do not produce a final diff-based message. Offer an
     unstaged draft only when explicitly requested.
   - Record the staged file list and summary for the final consistency check.

2. **Resolve effective policy**

   - Read applicable repository instructions, mechanical enforcement
     (`commitlint`, hooks, CI workflow/env, validation scripts), then the nearest
     `commit_message.md`.
   - Effective enforcement overrides optional prose defaults. Report conflicts
     and use a form accepted by both whenever possible.
   - With no repository policy, state and use this Conventional Commits fallback:
     `type(scope): subject`; optional scope; type from `feat`, `fix`, `docs`,
     `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, or `revert`; no
     emoji; imperative lowercase subject, at most 72 characters, no final period.

3. **Classify the boundary**

   - Identify the dominant intent and required coupled changes.
   - For unrelated intents, stop before drafting a combined message. Output
     ordered groups with files, intent, and a provisional message for each.
   - Continue with one combined message only after the user explicitly opts out
     of the recommended split.

4. **Draft and validate**

   - Produce one recommendation. Add alternatives only when materially distinct
     valid type or scope interpretations remain.
   - Add body/footer only for motivation, impact, verification, issue links, or
     breaking changes.
   - Use a repository validator when it accepts candidate input. Otherwise check
     type, emoji, scope, length, subject, body, and footer manually. A HEAD-only
     check does not validate a candidate.
   - Rerun the staged summary before finalizing. If it changed, reread the diff
     and restart classification.

5. **Finalize safely**

   Label the result as a suggestion or final choice. Run `git commit` only after
   explicit user authorization.

## Output Contract

| State | Required output |
| --- | --- |
| Single intent | `Detected`, `Spec`, one `Proposed`, `Validation`, optional body/footer and materially distinct alternatives |
| Mixed intents | `Detected`, `Split` groups, and `Notes`; no combined `Proposed` until the user opts out of splitting |

`Spec` names the source, enforcement, and conflicts. `Validation` names the
validator result or manual checks.

## Success Criteria

- Output matches the current staged diff and effective policy
- Mixed work yields a split plan, not a disguised combined message
- Every candidate is validated; filler alternatives are omitted
- No commit runs without explicit authorization

## Failure Handling

No staged diff: explain and stop. No policy: state the fallback. Conflicts:
report them and use the stricter accepted form. Changed staging: restart.