settled-reach/.claude/skills/git-commit/SKILL.md

---
name: git-commit
description: >
  Commit changes with clean, structured messages. Use when the user says
  "commit", "save my work", "commit changes", or invokes /git-commit. Enforces
  conventional commit format, groups changes into logical commits, and maintains
  CHANGELOG.md. Never squash unrelated changes into one commit.
user-invocable: true
allowed-tools: Bash, Read, Grep, Glob, Write, Edit
---

# Commit Skill

## Workflow

1. Run `git status` and `git diff --stat` to assess all pending changes.
2. **Triage: session vs pre-existing.** Separate changes you made in this
   session from changes that were already dirty when the session started.
   Check the conversation history — if you didn't touch a file, it's
   pre-existing. After grouping your own commits, surface any remaining
   modified or untracked files to the user:

   > These files are also modified/untracked but weren't part of this
   > session's work:
   > - `path/to/file` — <brief description of the diff>
   > - `path/to/other` — <untracked, N files>
   >
   > Should any of these be included in a commit?

   Wait for the user's answer before staging them. Never silently skip
   or silently include pre-existing changes.
3. Group changes into **logical commits** — each commit should represent one
   coherent change. Common groupings:
   - A bug fix (all files touched to fix one issue)
   - A new feature or system (e.g., new trait files + localization + events)
   - Refactoring / cleanup (encoding fixes, comment fixes, renaming)
   - Config / meta changes (CLAUDE.md, .claude/ skills, mod descriptor)
   - Data corrections (province remapping, missing fields)
4. For each logical group, stage only the relevant files and commit with a
   properly formatted message.
5. After all commits, update CHANGELOG.md.

## Commit Message Format

```
<type>(<scope>): <short summary>

<optional body — what and why, not how>

Co-Authored-By: Claude <noreply@anthropic.com>
```

The trailer is intentionally **unpinned** — do not write a model version into the
example. The model-identifier variant the Claude Code harness appends automatically
(e.g. `Co-Authored-By: Claude Opus <version> <noreply@anthropic.com>`) is equally
valid; leave it as the harness emits it. Pinned version numbers are the root cause of
attribution drift (this line read `Claude Opus 4.6` for months after the model moved on).

### Types

| Type | Use for |
|------|---------|
| `feat` | New game system, mechanic, or feature |
| `fix` | Bug fix — crashes, logic errors, broken references |
| `refactor` | Code restructuring without behavior change |
| `chore` | Build, config, tooling, skills, CLAUDE.md, infrastructure |
| `docs` | Documentation, design docs, discussion logs, briefings |
| `data` | Game data changes — entity definitions, map templates, balance values |
| `loc` | Localization additions or corrections |

### Scope

Use the project subsystem as scope. Examples:
- `agents` — agent personality files (.claude/agents/)
- `skills` — skill definitions (.claude/skills/)
- `docs` — design documents, architecture docs
- `briefings` — agent briefing files (docs/briefings/)
- `discussions` — discussion round archives
- `schema` — database schema changes
- `db` — database operations, connector scripts
- `config` — project configuration, endpoints
- `simulation` — game simulation server-side code
- `client` — game client code, rendering
- `engine` — engine-level systems (ECS, chunk loading, etc.)
- `ui` — user interface, HUD, insert/minimap
- `audio` — sound system, audio propagation
- `assets` — visual assets, sprites, art
- `meta` — project config, CLAUDE.md, team roster

### Rules

- Summary line: imperative mood, lowercase, no period, max 72 chars.
- Body: wrap at 72 chars. Explain *why* the change was made.
- Never combine unrelated changes (e.g., don't mix a crash fix with new features).
- When in doubt, prefer more smaller commits over fewer large ones.

### Clerk safety valve (`Clerk-Skip:` trailer)

The pre-push clerk reviews each commit for D-record consistency. For a pure bulk
content commit — e.g. shipping thousands of generated planetary description files
— that review is moot and just burns agents on noise. Add a `Clerk-Skip:` **trailer
line** to the commit message and `tooling/clerk-review` auto-approves that commit
without spawning an agent. Use it only for content/data dumps, never for commits
that touch `governance/`, code, or ticket-bearing work.

It must be a trailer (a line starting with `Clerk-Skip:`), not inline prose — that
way a commit that merely *mentions* the token in its subject or body isn't skipped.

```
data(content): generate 5000 planetary description files

Clerk-Skip: bulk generated content, no D-record surface
```

### Examples

```
feat(simulation): add LOS shadowcasting for vision cone

Implements 2D shadowcasting per z-level with forward/peripheral/
blind spot zones per D-011 and D-015 specifications.
```

```
docs(discussions): archive round 13 engine selection debate

Split completed round from DISCUSSION.md into per-round archive.
Updated briefings for Tyre and Troblum with new requirements.
```

```
chore(agents): add Stig UI developer agent

Standby agent for UI implementation phase. Configured with
briefing reference and Settled Reach-themed personality.
```

## CHANGELOG.md Format

Maintain `CHANGELOG.md` in the project root. Use Keep a Changelog format:

```markdown
# Changelog

## [Unreleased]

### Added
- New feature descriptions

### Fixed
- Bug fix descriptions

### Changed
- Change descriptions
```

Group entries under: Added, Fixed, Changed, Removed. Write entries from the
player/modder perspective, not implementation details.

After committing, read the existing CHANGELOG.md (create if missing), prepend
new entries under `[Unreleased]`, and commit the changelog update separately as:

```
chore(meta): update changelog
```

## Version Tracking

Version is tracked in CHANGELOG.md. When the user bumps the version,
move `[Unreleased]` entries under a new version heading and commit as:

```
chore(meta): release v0.1.0
```

## Staging Rules

See `.claude/rules/git-safety.md` for staging rules (always-loaded).
These apply to ALL git operations, not just this skill.