git-commits

name	git-commits
description	Rules for writing commit messages in the deep-cuts repository — subject line format, body content, scope naming, and what to omit

Git Commit Messages

Every commit message is permanent project history. Write it for the person (or agent) reading git log six months from now, not for the person who just reviewed the diff.

---

Subject line

Format: type(scope): imperative verb phrase

fix(ipc): route all Tauri imports through $lib/ipc
feat(analysis): add sleep prevention during pipeline run
docs(feedback): archive C1, F1a, F1b completed items
test(analysis): add pass invariant tests

Type signals the category of change:

Type	When to use
feat	New user-visible capability
fix	Corrects a bug or wrong behavior
refactor	Internal restructuring, no behavior change
test	Adding or fixing tests only
docs	Documentation only
perf	Performance improvement
tooling	Dev tools, scripts, lint
chore	Deps, config, build — nothing a user sees

Scope is the subsystem or domain: ipc, analysis, scanner, frontend, stores, db, css, skills, feedback, design. Keep it to one word. If you can't name the scope, the commit may contain multiple logical changes.

Verb is imperative, present tense: add, fix, replace, remove, extract, not added, fixes, replacing.

Length: subject under 72 characters. If you can't fit it, the commit is probably too large.

---

Body

Include a body when the why is not obvious from the subject and diff. The diff already shows what changed — the body explains the decision, the problem, or the constraint.

fix(rust): replace silent filter_map(ok) with visible error handling

filter_map(|r| r.ok()) was swallowing SQLite row-mapping errors across
multiple query paths, making schema drift invisible at runtime. Each
call site now logs the error and the query continues — no behavior
change for callers, but failures are now observable in logs.

Good reasons to add a body:

• The fix is non-obvious and a future reader might revert it thinking it's wrong.
• A design decision was made between two plausible alternatives.
• The change has a known limitation or follow-up.
• The commit implements a tracked backlog item — name the item ID.

Bad reasons to add a body:

• Restating what the diff already shows ("changed X to Y in file Z").
• Describing the task context ("as part of the F1 campaign we decided to...").
• Trailing noise ("per review", "as discussed", "various cleanup").

---

Scope and backlog references

When a commit implements a tracked item from the operations backlog, reference the item ID in the subject or body:

feat(ipc): add typed CommandMap with 86 commands (F1b)
fix(stores): make library.init() idempotent and add dispose() (F3)

This creates a navigable link between git log and doc/operations/.

---

What to omit

• Do not explain the code. Well-named identifiers do that. Never write "added a new function called X that does Y".
• Do not reference the PR, session, or conversation. These are ephemeral. The commit stands alone.
• Do not add "various", "misc", "cleanup", or "small fixes" as the entire subject. Name the specific thing that changed.
• Do not use past tense. "Fixed" → "fix", "Added" → "add".
• Do not pad. A short, precise subject is better than a long vague one.

---

One logical change per commit

The subject line is a forcing function. If you cannot write a single clear subject, the commit contains multiple logical changes and should be split.

A commit that touches the same concern in multiple files is fine (e.g. "fix(css): replace hardcoded colors with --sg-* tokens in 18 components"). A commit that touches two unrelated concerns in the same session should be two commits.

---

Examples

feat(analysis): add HDBSCAN structure clustering pass
fix(download): structured error events, spawn_blocking, group key validation
refactor(backend): modularize commands, extract repositories, decouple coordinators
test(analysis): add pass invariant tests for lifecycle, order, and reset
docs(architecture): add data flow and IPC domain map (D5)
tooling(skills): auto-inject skill table into agent instruction files
chore: add tools/ export scripts and models/ directory scaffold