---
name: semantic
description: Generate a single-line Semantic Commits subject from staged changes and the current branch name. Use when the user asks to write a semantic commit message, generate a semantic subject, summarize staged changes with a typed commit prefix, 生成 semantic 提交信息, 写 semantic 风格提交说明, or wants an Angular-style `type(scope): summary` subject that is tracked separately from Conventional Commits.
commit-message-protocol: semantic
---

# Semantic Commits

## Purpose

Generate a commit message from the current git staged changes.

Requirements:
- Follow Semantic Commits.
- Use the `type(scope): summary` structure when a scope is useful.
- Follow the configured commit message language for the summary.
- Extract a Jira ID or work item ID from the current branch name when possible and prepend it to the summary.
- Ignore branch tokens that are clearly version numbers, release numbers, dates, or pure numeric identifiers.

## Workflow

1. Confirm there are staged changes before drafting the message.
2. Read the staged diff, not the full working tree, and summarize only what is staged.
3. Read the current branch name.
4. Extract a ticket-like identifier from the branch name.
5. Choose the narrowest semantic commit type.
6. Generate a concise subject line.

## Commands

Use git commands that inspect only the staged area:

```bash
git branch --show-current
git diff --cached --name-only
git diff --cached --stat
git diff --cached
```

If there are no staged changes, do not invent a message. Tell the user there is nothing staged to commit.

## Ticket Extraction

Extract a meaningful ticket-like token from the branch name.

Preferred pattern:

```text
[A-Za-z][A-Za-z0-9]+-\d+
```

Rules:
- If the branch contains **multiple** substrings that match this pattern, use the **last** match. Prefix segments are often release or iteration noise; the real work item ID is usually at the end (for example `...-CZGZH-SCP-7921` → `SCP-7921`).
- Keep the extracted ticket exactly as it appears in the branch name.
- The pattern requires a **leading letter** in the key, so a numeric prefix such as `202-` before the key is not treated as the project key (for example `feature/202-SCP-7921` → `SCP-7921`).
- Ignore tokens that look like versions or releases when interpreting the branch, for example `1.2.3`, `v2.0.1`, `2026.03`, `release-1.0.0`.
- Ignore pure numbers such as `1234`.
- **Do not** substitute unrelated acronyms from the diff or summary for the branch ticket. If the branch yields a `Key-123` token, the subject must include that exact ticket form.
- If no valid ticket is found, omit it.

## Type Selection

Choose the commit type from the staged change intent:

- `feat`: new feature or user-visible capability
- `fix`: bug fix or behavior correction
- `refactor`: code restructuring without behavior change
- `perf`: performance improvement
- `docs`: documentation only
- `test`: tests only
- `style`: formatting or non-functional style changes
- `build`: build tooling or dependency packaging changes
- `ci`: CI workflow or pipeline changes
- `chore`: routine maintenance that does not fit the types above
- `revert`: reverting an earlier commit

Do not guess `feat` by default. Pick the narrowest accurate type from the staged diff.

## Output Format

Always output a single-line subject only.

Subject template:

```text
<type>(<scope>)?: <ticket-id> <summary>
```

If there is no ticket:

```text
<type>(<scope>)?: <summary>
```

Subject rules:
- Keep it concise and specific.
- Follow the configured commit message language.
- Focus on the purpose of the staged change, not a file list.
- Do not end the subject with punctuation.
- Keep the type keyword in English.

## Examples

Branch: `feature/ABC-5690-user-center-sync`
Staged intent: user center integration

Output:

```text
feat(user-center): ABC-5690 用户中心模块数据联调
```

Branch: `fix/abc-6021-order-status`
Staged intent: fix incorrect status mapping

Output:

```text
fix(order): abc-6021 修复订单状态映射错误
```

Branch: `release/1.3.0`
Staged intent: update README

Output:

```text
docs(readme): 更新接诊流程说明
```

Branch: `feature/202SP5-CZGZH-SCP-7921`
Staged intent: add SCA security component types

Output:

```text
feat(sca): SCP-7921 新增 SCA 安全组件类型支持
```

Branch: `feature/202-SCP-7921`
Staged intent: same as above

Output:

```text
feat(sca): SCP-7921 新增 SCA 安全组件类型支持
```

## Response Style

When returning the result to the user:
- Return exactly one final commit message subject line only.
- If the staged diff is ambiguous, choose the single best subject and return only that one line.
- Do not add explanations, labels, bullets, or alternative candidates.

## Additional Resources

- For more examples, see [references/examples.md](references/examples.md)