---
description: Generate a Conventional Commit message from conversation history and diffs
---

# commit-message

When I start a message with "/commit-message" or "CMD-COMMIT-MESSAGE", you must strictly enter "Commit Message Mode" and output ONLY a single Conventional Commit message.

## 1) Source Analysis (mandatory)

- Scan the ENTIRE conversation history to recover:
  - the original user goals / requirements
  - any constraints (performance, API shape, UX, compatibility, etc.)
- Scan the current file diffs to confirm what was actually changed.
- If conversation intent and diffs disagree, trust diffs and reflect the true net change.

## 2) Synthesis & Filtering (mandatory)

- AGGREGATE outcomes: include all end-state features/fixes shipped in this session.
- FILTER noise: exclude exploration, dead ends, "fixed typo", "debugged", "changed approach", temporary hacks, etc.
- Prefer user-impact + architectural intent over implementation trivia.
- If there are multiple significant changes, pick ONE primary theme for the subject/type,
  then capture secondary changes in the body bullets.

## 3) Output Format (mandatory)

### Commit Message Structure
```
<type>(<scope>): <subject>

<body>

## Technical Details

<technical-details>

## Learning Notes

<learning-notes>

<footer>
```

### Type (required)

Choose ONE:

- feat: new user-facing capability
- fix: user-facing bug fix
- docs: documentation only
- style: formatting only (no behavior change)
- refactor: restructure without behavior change
- perf: performance improvement
- test: add/update tests
- chore: tooling/build/deps (no production behavior change)
- revert: revert a prior commit
- ci: CI configuration/scripts

### Scope (recommended)

- Use kebab-case.
- Prefer repo/project conventions if discoverable from context.
- Otherwise infer a concise area name (examples):
  - frontend/ui: ui, components, routing, state, forms, a11y
  - backend/api: api, auth, db, cache, queue, workers
  - platform/infra: build, ci, deps, config, observability
  - game/graphics: rendering, vfx, physics, input, camera, assets
  - shared: core, utils, types
- Multiple scopes allowed: `ui,api` (comma-separated, no spaces).
- Omit scope only if truly cross-cutting and a single scope would mislead.

### Subject (required)

- <= 72 chars, imperative, lowercase start, no period
- Must describe net impact (what changed for the project)

### Body (required)

- Blank line after subject
- Bullets with `-`
- Wrap at ~72 chars/line
- Explain WHAT + WHY (not a step-by-step HOW)
- No intermediate work, no debugging narration
- CRITICAL: no hyperlinks, no file paths, no citation links
- CRITICAL: avoid backticks entirely; use single quotes for identifiers
  (e.g., 'AuthToken', 'PlayerController', 'useQuery')

### Breaking Changes

If backward compatibility is broken:

- Add `!` after scope: `feat(api)!:` or `refactor!:`
- Include footer line: `BREAKING CHANGE: <impact + migration hint>`

Common triggers:
- renamed/removed public APIs, props, CLI flags, config keys
- DB schema changes requiring migration
- changed data formats, save files, wire protocols
- dependency upgrades that force code changes downstream

## Technical Details (required)

Give project-relevant implementation context as bullets. Include the most helpful subset:

- Interfaces/contracts: API endpoints, event shapes, command/query boundaries
- Data: schema changes, migrations, caching strategy, consistency notes
- Runtime/perf: hot paths, complexity changes, batching, memory considerations
- UX: state model, error handling, loading states, accessibility implications
- Security: authn/authz decisions, validation, sensitive data handling
- Testing: what coverage was added/updated and what it protects

Keep it concrete, but do NOT include file paths.

## Learning Notes (required)

Capture reusable knowledge as bullets:

- Why this approach over alternatives (1–2 bullets)
- Key libraries/APIs/patterns used (1–2 bullets)
- Gotchas / sharp edges / future tuning knobs (1–3 bullets)
- Optional: follow-up ideas if clearly implied by the work (not new scope)

## Footer (optional)

- BREAKING CHANGE: ...
- Closes #123 / Refs #456
- Co-authored-by: ...

## Output Requirements (hard)

- Output ONLY the commit message in a single markdown code block.
- No preamble, no explanations, no extra commentary.
- Aggregate all shipped outcomes from this session.
- Never include hyperlinks, file paths, or backticks.
