---
name: change-kind-naming
description: Decide the correct change kind and semantically align branch names, PR titles, commit prefixes, and PR template types. Use when choosing Conventional Commit or branch prefixes for fix, refactor, chore, docs, feat, perf, test, or CI changes.
---

# Change Kind Naming

## Quick Start

Before committing, pushing, or opening a PR, classify the actual change type and
make these four surfaces agree semantically under the repository's allowed
branch prefixes:

- commit subject prefix
- PR title prefix
- branch prefix
- PR template "Type of Change"

If they disagree, stop and fix the naming before publishing.

## Classification Rules

Use `fix` only when the change corrects externally observable broken behavior, user-facing wrong output, a failing workflow, data loss, security exposure, or a regression.

Use `refactor` when the change preserves behavior but improves internal structure, terminology, names, boundaries, generated bindings, or code organization.

Use `feat` when the change adds a new user-visible capability or supported workflow.

Use `docs` when the shipped code behavior does not change and the diff is documentation-only.

Use `test` when the diff only adds or changes tests.

Use `ci` when the diff only changes CI/CD automation.

Use `chore` for maintenance that is not product behavior, architecture, docs, tests, or CI.

## Tie-Breakers

Prefer `fix` over `refactor` when the old state caused a real user or integration failure.

Prefer `refactor` over `fix` when the old state was confusing, inconsistent, or poorly named but still worked.

Prefer `feat` over `refactor` when users can now do something they could not do before.

Prefer `docs` over `refactor` when only docs changed, even if the docs clarify architecture.

Prefer the highest-impact type when one PR intentionally mixes types. If the mixed change is accidental, split it.

## Naming Alignment

Use branch prefixes that match the final classification:

- `feat/...`
- `feature/...`
- `fix/...`
- `docs/...`
- `perf/...`
- `refactor/...`
- `chore/...`

This repository's CI does not allow `test/...` or `ci/...` branches. For a
test-only or CI-only change, use a `chore/...` branch while keeping the more
precise `test:` or `ci:` Conventional Commit and PR title. Select `Other` in the
PR template. Alignment is semantic here; it does not require the branch and
commit prefix strings to be identical.

Do not use:

- `test/...`
- `ci/...`
- `codex/...`
- `claude/...`

In repositories that define branch rules, such as this repository's
`CONTRIBUTING.md`, the repository rule wins over generic agent defaults.
Never use tool-dependent prefixes such as `codex/...` or `claude/...`
when the project requires change-kind branch prefixes.

Use the same Conventional Commit prefix in the commit subject and PR title:

```text
refactor: rename hardware archive retention setting
```

In the PR template, check the matching Type of Change. Do not leave `Bug fix` checked for a `refactor:` PR.

## Pre-Publish Checklist

Run this before `git commit`, `git push`, or `gh pr create`:

- Does the change fix broken behavior? If no, avoid `fix`.
- Does the change preserve behavior while renaming or reorganizing? Use `refactor`.
- Do branch, commit, PR title, and PR template all agree?
- Does the PR body explain compatibility separately from behavior?
- If the branch prefix is wrong and the PR is already open, prefer renaming before review starts. If renaming would close or disrupt the PR, weigh whether updating title/body/commit is enough.

## Example

Renaming `refreshIntervalDays` to `retentionDays` while preserving compatibility is `refactor`, not `fix`, because the old setting worked but used misleading terminology.

Use:

- branch: `refactor/hardware-archive-retention-naming`
- commit: `refactor: rename hardware archive retention setting`
- PR title: `refactor: rename hardware archive retention setting`
- PR type: `Refactoring`