🐛 fix(commit-message): resolve policy and staged boundaries
This commit is contained in:
@@ -7,92 +7,86 @@ description: "Use when the user asks for help writing a commit message, wants em
|
|||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
Turn a staged diff into a commit recommendation that matches repository policy.
|
Create a repository-compliant recommendation from the staged diff. Resolve its
|
||||||
Core principle: understand staged intent and commit boundaries before drafting the
|
boundary and enforced rules before drafting.
|
||||||
message.
|
|
||||||
|
|
||||||
Authority source:
|
|
||||||
|
|
||||||
- `docs/common/commit_message.md`
|
|
||||||
- `docs/standards/playbook/docs/common/commit_message.md` (vendored playbook)
|
|
||||||
|
|
||||||
## When to Use
|
## When to Use
|
||||||
|
|
||||||
- The user asks to write or improve a commit message
|
Use for commit-message drafting, staged-boundary review, split decisions, or
|
||||||
- The user wants emoji/type(scope): subject formatting
|
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
|
## When Not to Use
|
||||||
|
|
||||||
- No staged changes exist and the user expects a final commit message based on the
|
Do not use for PR titles, release notes, changelogs, or exact-message execution.
|
||||||
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
|
## Inputs
|
||||||
|
|
||||||
- Current staging state (`git status --short`, `git diff --cached`)
|
Use staged/unstaged state and repository policy.
|
||||||
- Nearest applicable `commit_message.md`
|
|
||||||
- Whether the user wants suggestions only or a command-ready final message
|
|
||||||
|
|
||||||
## Procedure
|
## Procedure
|
||||||
|
|
||||||
1. **Baseline the repo state**
|
1. **Baseline state**
|
||||||
|
|
||||||
- Inspect staged and unstaged state separately.
|
- Inspect staged and unstaged changes separately.
|
||||||
- If nothing is staged, stop. Explain that a staged-diff-based recommendation
|
- If nothing is staged, do not produce a final diff-based message. Offer an
|
||||||
is unavailable and ask whether files should be staged first.
|
unstaged draft only when explicitly requested.
|
||||||
- If only unstaged changes exist, stop before proposing a final message. Offer
|
- Record the staged file list and summary for the final consistency check.
|
||||||
a draft only if the user explicitly wants one.
|
|
||||||
|
|
||||||
2. **Load the authority spec**
|
2. **Resolve effective policy**
|
||||||
|
|
||||||
- Prefer the nearest `commit_message.md`.
|
- Read applicable repository instructions, mechanical enforcement
|
||||||
- Reuse its type, emoji, scope, and body/footer conventions exactly.
|
(`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. **Summarize staged intent**
|
3. **Classify the boundary**
|
||||||
|
|
||||||
- Read the staged diff at the smallest useful granularity.
|
- Identify the dominant intent and required coupled changes.
|
||||||
- Identify the main logical change, affected areas, and whether the staged set
|
- For unrelated intents, stop before drafting a combined message. Output
|
||||||
mixes unrelated work.
|
ordered groups with files, intent, and a provisional message for each.
|
||||||
- If staged changes combine unrelated goals, strongly recommend splitting the commit
|
- Continue with one combined message only after the user explicitly opts out
|
||||||
before drafting a single message. In other words, strongly recommend splitting
|
of the recommended split.
|
||||||
the commit instead of hiding multiple intents behind one subject.
|
|
||||||
|
|
||||||
4. **Draft message options**
|
4. **Draft and validate**
|
||||||
|
|
||||||
- Produce one recommended option and up to two alternatives.
|
- Produce one recommendation. Add alternatives only when materially distinct
|
||||||
- Keep the subject concrete, specific, and under the repo limit.
|
valid type or scope interpretations remain.
|
||||||
- Use body/footer only when they add real context such as motivation, impact,
|
- Add body/footer only for motivation, impact, verification, issue links, or
|
||||||
verification, issue links, or breaking-change notes.
|
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**
|
5. **Finalize safely**
|
||||||
|
|
||||||
- Make it explicit whether the output is a suggestion or a final chosen message.
|
Label the result as a suggestion or final choice. Run `git commit` only after
|
||||||
- Do not run `git commit` unless the user explicitly asks for execution after
|
explicit user authorization.
|
||||||
reviewing the recommendation.
|
|
||||||
|
|
||||||
## Output Contract
|
## Output Contract
|
||||||
|
|
||||||
- `Detected:` staged files summary, dominant intent, and split/no-split judgment
|
| State | Required output |
|
||||||
- `Spec:` which `commit_message.md` was used
|
| --- | --- |
|
||||||
- `Proposed:` Option A (recommended), Option B, Option C
|
| Single intent | `Detected`, `Spec`, one `Proposed`, `Validation`, optional body/footer and materially distinct alternatives |
|
||||||
- `Optional body/footer:` only when justified
|
| Mixed intents | `Detected`, `Split` groups, and `Notes`; no combined `Proposed` until the user opts out of splitting |
|
||||||
- `Notes:` risks, ambiguity, or split advice
|
|
||||||
|
`Spec` names the source, enforcement, and conflicts. `Validation` names the
|
||||||
|
validator result or manual checks.
|
||||||
|
|
||||||
## Success Criteria
|
## Success Criteria
|
||||||
|
|
||||||
- The recommendation matches the staged diff rather than guessed intent
|
- Output matches the current staged diff and effective policy
|
||||||
- The selected format complies with the nearest commit policy
|
- Mixed work yields a split plan, not a disguised combined message
|
||||||
- Split advice appears when staged changes are logically mixed
|
- Every candidate is validated; filler alternatives are omitted
|
||||||
- No commit command is executed unless the user asked for it
|
- No commit runs without explicit authorization
|
||||||
|
|
||||||
## Failure Handling
|
## Failure Handling
|
||||||
|
|
||||||
- If no staged diff exists, stop and explain the limitation instead of inventing a
|
No staged diff: explain and stop. No policy: state the fallback. Conflicts:
|
||||||
final message
|
report them and use the stricter accepted form. Changed staging: restart.
|
||||||
- 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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user