Git Workflow

---
name: git-workflow
description: Use when committing work, creating branches, preparing PRs, resolving merge conflicts, when grouping related changes into commits, when cleaning up history before merging, or when deciding what should be a separate commit vs squashed.
---

# Git Workflow

## Overview

Each commit is an atomic, independently-revertable unit of work. Commit messages explain WHY, not WHAT (the diff shows what). Branch names reference task IDs. PRs link to the originating task and contract.

## When to Use

- Committing completed work from `incremental-implementation`
- Creating a branch for a new task
- Preparing a PR for review
- Resolving merge conflicts

## When NOT to Use

- You're in the middle of implementing — finish the task first, then commit
- Exploratory work not yet at a stable state — use `git stash` or a WIP commit

## Common Rationalizations

| Thought | Reality |
|---------|---------|
| "I'll squash it all at the end" | Squashing discards the incremental story — keep atomic commits |
| "The commit message can be 'fix'" | Future you and your teammates need to know WHY |
| "I'll just force push to clean up" | Force push rewrites shared history — never on shared branches |
| "One big commit is fine for a small change" | Small changes are the easiest place to practice atomic commits |

## Red Flags

- Commit touches files from more than one task
- Commit message describes the diff ("update user.ts") not the reason ("guard against null session on logout")
- Unrelated test fixes bundled with a feature commit
- Merge conflict resolved by accepting one side wholesale without reading both

## Core Process

### Branch naming

```
feat/T001-user-registration
fix/T023-null-session-logout
chore/update-dependencies
```

### Commit format

```
[T001] Implement user registration

Guard against duplicate email on create — UserService.create() now returns
DuplicateEmailError instead of throwing, matching the contract invariant.

Closes: T001
```

- First line: `[TASK-ID] imperative verb + what changed` (≤72 chars)
- Body: WHY this change was needed, not what the diff shows
- Footer: task reference

### Before committing

- [ ] Only files from the current task are staged
- [ ] `git diff --staged` reviewed — no debug logs, no TODO left in
- [ ] Tests pass: `<run test command>`
- [ ] Build passes: `<run build command>`

### PR checklist

- [ ] PR title matches the task title
- [ ] PR description links to task ID and to the relevant `.forge/contracts/` file
- [ ] "What changed and why" section in PR body — not just the task title
- [ ] No unresolved review comments before merge
- [ ] Merge strategy: squash only if commits are truly WIP; prefer merge commit to preserve atomic history

## Verification

- [ ] Each commit is independently revertable
- [ ] Commit messages explain WHY, not WHAT
- [ ] No debug artifacts committed (console.log, TODO, commented-out code)
- [ ] Branch references task ID
- [ ] PR links to task and contract