git-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Conventions

The rules below are canonical. Rework a branch's history in the main session with the fast rework
recipe at the end of this skill. Use the `git-best-practices-agent` subagent only for large,
unattended rewrites the user doesn't need to wait on.

## Commit Messages

- Imperative subject, <=50 chars, capitalized, no trailing period ("Add retry to token refresh",
  not "Added"/"Adds"). Test: "If applied, this commit will [subject]".
- Blank line between the subject and the body; wrap the body at 72 chars.
- Explain WHY, not what. The diff already shows what changed.
- Keep it concise; add detail only where it earns its place. The whole message must stay under
  350 characters.
- One logical change per commit. Don't bundle unrelated edits; commits needn't be artificially
  small, but each must be a single coherent change. Review the staged diff before committing.
- The subject must summarize the whole change, not one narrow aspect of it.
- Don't list the files that changed. The diff already does.
- Don't narrate the review exchange ("Addresses review feedback", "Per PR comments").
- No conventional-commit prefixes (`chore:`, `fix:`, `feat:`, `docs:`). Write a plain descriptive
  subject.
- Never add AI attribution signatures (`Co-Authored-By: Claude`, "Generated with Claude Code",
  robot emoji, etc.).
- Never add `Co-Authored-By` trailers of any kind.
- Include the Jira ticket key when there is one. Plenty of work has none, especially in the
  tooling and automation repos; write the subject without one rather than hunting for a ticket.

### Enforcement

For Claude, these rules are enforced by the `git-commit-guard.sh` PreToolUse hook: deterministic
checks block AI signatures and messages over 350 characters, and an LLM gate blocks commits that
bundle unrelated changes or whose subject under-describes the diff. The gate fails open, so an
error or timeout never blocks a commit.

Robert's Codex setup also registers a `Bash` PreToolUse adapter for this guard.
New or changed Codex hooks require trust review through `/hooks` before they run.
Follow the rules above even when a hook is unavailable or skips a command.

## Branch Naming

Format: `rcedwards/JIRA-TICKET-short-description`, or `rcedwards/short-description` when the
work has no ticket.

Examples:
- `rcedwards/GD-6163-sk2-firebase-event`
- `rcedwards/FOX-1234-fix-login-bug`
- `rcedwards/pr-nudge-business-hours`

The `rcedwards/` prefix signals the branch is owned by one person and may be rewritten.

The ticket key is expected in the app repos (`ios-onxmaps`, `android-onxmaps`) and in service
repos where the work is tracked in Jira. Tooling, automation and config repos routinely carry
work that has no ticket. Never invent a key, leave a placeholder, or stop to ask for one.

## Pull Requests

Create PRs as drafts first: `gh pr create --draft`.

Title format: `[GD-XXXX] - Description` where the work has a ticket, otherwise a plain
descriptive title with no bracket prefix.

Use the PR template from `.github/pull_request_template.md` whenever the repo has one. Many of
the smaller repos do not.

### Description

- Keep it concise and focused on the core problem and solution.
- Skip implementation specifics and architecture explanations.
- Skip the screenshots section when there are no UI changes.
- Say what the change does, not how it is implemented.

### Test Plan

- Only essential manual testing steps.
- Focus on core functionality verification.
- Drop edge cases unless critical.
- Keep steps actionable and specific.

### Triggering CI

To run the CI pipeline on a PR: `gh pr comment <PR_NUMBER> -b "ci test"`.

### General

- Be concise; assume reviewers understand the technical context.
- Focus on business value and user impact.
- Remove boilerplate that adds no value.
- No emojis in the title or body.

## Commit-by-Commit Reviewability

GitHub supports reviewing PRs commit-by-commit, so history must read forward, never backward.

- Each commit builds on the last. A later commit never undoes or contradicts an earlier one on the
  same branch.
- No fix-up-the-fix commits. If an earlier commit was wrong, rebase and fold the fix into the
  commit that introduced it rather than stacking a corrective commit on top.
- One concern per commit. Separate refactoring from behavior changes, infrastructure from feature
  logic.
- The branch should tell a story: setup, then implementation, then wiring it together.
- Clean up history before opening the PR with the Fast History Rework recipe below. If the branch
  is already pushed, force-push with `--force-with-lease` (feature branches only, never main or
  develop).

## Fast History Rework

Use this to fold review fixes into earlier commits, reword, drop, or redistribute changes across a
pushed branch. It takes minutes in the main session; a subagent starts cold and re-verifies each
step, which makes the same rework many times slower.

1. Make all code changes at the tip first, as plain commits, and test there once. The tip is the
   "tested tip".
2. Back up: `git branch <branch>-backup-<tag> <tested-tip>`. Ask the user once, for the whole
   rework, before skipping repo hooks on the rebuilt commits (org policy requires it).
3. Map ownership: `git show --stat --format= <sha>` for each original commit. A file that only one
   target commit touches can take its final content directly in that commit.
4. Rebuild on the original merge base, never a newer develop:
   `git checkout -B <branch> $(git rev-parse <first-commit>^)`. For each target commit:
   - `git cherry-pick --no-commit <original>`

From rcedwards/blaude-bode, MIT.

More from rcedwards/blaude-bode