git-commits

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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
```

From robertolupi/deep-cuts, AGPL-3.0.

More from robertolupi/deep-cuts