Commit Hygiene

When to Use

Use this skill when:

• Creating commits
• Creating or naming branches
• Reviewing commit history in a PR
• Cleaning up staged changes

Critical Rules

1. Commit messages MUST follow Conventional Commits — enforced by GitHub ruleset, rejected on push if invalid
2. Branch names MUST follow type/description format — enforced by GitHub ruleset, rejected on push if invalid
3. Keep one logical change per commit
4. Message should explain why, not only what
5. NEVER include Co-Authored-By trailers
6. NEVER commit generated/temp/local files

Commit Message Format (enforced by GitHub ruleset)

Regex: ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+

<type>(<optional-scope>): <description>
<type>(<optional-scope>)!: <description>   ← breaking change

Allowed Types

Rules

• Type MUST be lowercase, one of the listed values
• Scope is optional, lowercase, allows a-z, 0-9, ., _, -
• ! before : marks a breaking change
• Description MUST start after : (colon + space)
• Description should be imperative mood ("add", not "added" or "adds")

Valid Examples

feat(cli): add --json flag to session list command
fix(store): prevent duplicate observation insert on retry
docs(contributing): update workflow documentation
refactor(internal): extract search query sanitizer
chore(deps): bump github.com/charmbracelet/bubbletea to v0.26
style(tui): fix alignment in session detail view
perf(store): optimize FTS5 query for large datasets
test(sync): add coverage for conflict resolution
ci(workflows): split e2e into separate job
fix!: change session ID format

Invalid Examples (push will be rejected)

Fix bug                          ← no type prefix
feat: Add login                  ← description should be lowercase
FEAT(cli): add flag              ← type must be lowercase
feat (cli): add flag             ← no space before scope
feat(CLI): add flag              ← scope must be lowercase
update docs                      ← no conventional commit format

Branch Naming Format (enforced by GitHub ruleset)

Regex: ^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

<type>/<description>

Allowed Types

feat, fix, chore, docs, style, refactor, perf, test, build, ci, revert

Rules

• Type MUST be one of the listed values
• Description MUST be lowercase
• Only a-z, 0-9, ., _, - allowed in description
• No uppercase, no spaces, no special characters

Valid Examples

feat/json-export-command
fix/duplicate-observation-insert
docs/api-reference-update
refactor/extract-query-sanitizer
chore/bump-bubbletea-v0.26
ci/split-e2e-job

Invalid Examples (push will be rejected)

feature/add-login                ← "feature" not allowed, use "feat"
fix/Add-Login                    ← uppercase not allowed
my-branch                        ← no type prefix
fix_something                    ← missing "/" separator

Pre-Commit Checklist

• Commit message matches conventional commits format
• Branch name matches type/description format
• Diff matches commit scope (no unrelated changes)
• No secrets, credentials, or .env files
• No binaries, coverage outputs, or local artifacts
• No Co-Authored-By trailers
• Tests relevant to the change pass