Conventional Commits

---
name: conventional-commits
description: 'Writes a commit subject that passes the hooks: type, scope, breaking-change marker, record id. Use for a commit message or after a hook refused one.'
---
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# Conventional Commits

Construct a one-line commit subject that passes the `commit-msg` and `tracker-commit-msg` hooks on the first attempt. For staging and diff splits, read the git reference of `cli-tools`. For tracker records, use `work-tracker`.

## Rules

- **Use `basicly commit` by default.** It derives the type, the scope and the record id, so only the description is yours.
- **Write the description in lowercase letters, digits, spaces and hyphens only.** The hook rejects every other character, also in proper nouns and acronyms.
- **Put a version, a file name or a capitalised name in the body.** The hooks check only the subject line.
- **Never invent a record id.** The hook reads the ids from `.basicly/ledger/events-*.jsonl`.
- **Read `git status --short` column 1 before you commit.** `git commit` takes the whole index, including a file staged by a refused attempt.
- **Run `basicly hooks-build` once in each clone and worktree.** An uninstalled hook lets a bad message through to CI.
- **When a hook rejects the commit, read its error output.** It names the offending characters.

## Read when needed

- Before composing a subject by hand or using command overrides, read [message format and command options](references/message-format.md).
- For valid/invalid subjects, a refusal or hook installation details, read [examples and enforcement](references/examples-and-enforcement.md).
- Completion means the intended staged diff is committed with the real record id; read the commit result before any push or tracker write.