Update commit skill to four-pass method

skills/commit/SKILL.md

@@ -1,56 +1,190 @@
 ---
 name: commit
-description: Create atomic git commits following the three-pass methodology.
+description: Create atomic git commits using a four-pass methodology — content, standards, final review, and post-commit verification. Use when committing code or documentation changes. Triggers on "commit", "git commit", or when the user asks to commit changes.
 ---
 
-# commit
+# Commit
 
-## Trigger
+> Create atomic git commits using a four-pass methodology that separates content decisions from formatting standards.
 
-`/commit`
+## Skill documents
 
-## Process
+| File | Purpose |
+|:-----|:--------|
+| [SKILL.md](SKILL.md) | Overview, commit format reference, atomicity rules |
+| [WORKFLOW.md](WORKFLOW.md) | Four-pass execution sequence |
+| [references/chris-beams-commit-style.md](references/chris-beams-commit-style.md) | The 7 rules our format is built on |
 
-Read `./atomic-git-commits.md` in this skill's directory for the full reference. Then follow these steps.
+---
+
+## When to use
 
-### 1. Content pass
+- User asks to commit staged or unstaged changes
+- User runs `/commit`
+- Changes are ready and the user explicitly requests a commit
 
-- Run `pre-commit run --all-files` to fix formatting first
-- Check `git status` and `git diff --staged` to understand what's staged
-- Identify how many distinct logical/atomic changes exist
-- Summarize them: one sentence per proposed commit
+## When NOT to use
 
-### 2. Get user confirmation
+- No changes exist to commit
+- User has not explicitly asked for a commit
 
-Ask the user which change(s) to proceed with. Even if there is only ONE logical change, get explicit confirmation before proceeding.
+---
 
-### 3. Standards check
+## Quick reference
 
-For each commit:
+<mark>**One logical change per commit. Separate concerns across four passes: content, standards, final review, post-commit verification.**</mark>
 
-- Standard prefix used (feat:, fix:, docs:, refactor:, style:, test:, build:, ci:, perf:)
-- Subject capitalized after colon
-- Imperative mood ("Add" not "Added")
-- Under 50 characters for subject
-- Body explains WHY not just what
-- 72 character wrap for body lines
+---
+
+## Required reading
+
+Read before executing:
+
+1. [references/atomic-git-commits.md](references/atomic-git-commits.md) — the full atomic commit methodology and Conventional Commits standard
+
+---
+
+## Key principles
+
+| Principle | What it means |
+|:----------|:-------------|
+| Atomic | One complete logical change per commit — not by size, by coherence |
+| Imperative mood | "Add feature" not "Added feature" — completes "If applied, this commit will..." |
+| WHY not what | Body explains the reasoning, not just a list of files |
+| Working state | All tests pass after the commit |
+| Selective staging | Stage files per logical change, not everything at once |
+
+### Test-driven commits
+
+Every commit should pass all tests:
 
-### 4. Final review
+1. Write failing tests for new functionality
+2. Implement the feature
+3. Ensure all tests pass
+4. Commit the complete change
 
-- Re-read the commit message. Does it tell a complete story?
-- Check the diff one more time. Are all changes intentional?
-- Can this be reverted independently?
+This ensures each commit represents a working state of the codebase.
 
-### 5. Commit
+---
+
+## The coherence test
+
+> If you removed any file from this commit, would the remaining files still represent the same complete logical change?
+
+- If removing a file leaves a hole → it belongs
+- If removing a file leaves a perfectly coherent commit → it does not belong
+
+---
+
+## Common AI atomicity mistakes
 
-Use `git commit -e -m "your message"` so the message is pre-filled but the user can edit it in their editor before finalizing.
+<mark>**These are not valid reasons for combining changes into one commit:**</mark>
 
-NEVER add a co-author credit.
+- **Modified in the same session** — files changed during one conversation are not automatically one atomic commit
+- **Sharing a prefix** — using `docs:` on two unrelated documentation changes does not make them atomic
+- **Requested as one task** — "update the docs and fix the bug" is two tasks and two commits
+- **Touching the same area** — editing three files in `src/auth/` for different reasons is three commits
+- **"While I was in there" changes** — noticing a typo while fixing a bug does not make the typo part of the bug fix
 
-### 6. Output
+**Example of mixed changes that should be separated**:
 
-Display the full commit message:
+```bash
+# BAD: Two different logical changes in one commit
+git add TODO.md docs/research/ai-coding/what-is-a-frame.md
+# This mixes: project management (TODO) + documentation (frame concept)
 
+# GOOD: Separate atomic commits
+git add TODO.md
+git commit -m "build: Add TODO.md with AI frame loading system entry"
+
+git add docs/research/ai-coding/what-is-a-frame.md
+git commit -m "docs: Create comprehensive frame concept documentation"
 ```
-git log -1 --format="%h %s%n%n%b"
+
+---
+
+## Content focus blindness
+
+Both people and AI consistently miss formatting standards while focused on content logic. The four-pass approach solves this by making standards verification a dedicated step (Pass 2) separate from content decisions (Pass 1).
+
+---
+
+## Commit message format
+
+```text
+<type>: <Subject line — 50 chars max>
+
+<Body explaining WHY — wrap at 72 chars>
+
+- Bullet points for specific changes
+```
+
+### Standard prefixes
+
+| Prefix | Use for |
+|:-------|:--------|
+| `feat:` | New features or functionality |
+| `fix:` | Bug fixes and corrections |
+| `docs:` | Documentation only changes |
+| `refactor:` | Code restructuring without changing behaviour |
+| `style:` | Formatting, white-space changes |
+| `test:` | Adding or updating tests |
+| `build:` | Build system or dependency changes |
+| `chore:` | Maintenance tasks |
+| `perf:` | Performance improvements |
+| `ci:` | CI configuration changes |
+
+### Subject line rules
+
+- Standard prefix, lowercase (e.g. `feat:`, `fix:`)
+- Capitalize first word after colon ("Add" not "add")
+- Imperative mood ("Add" not "Added")
+- No period at end
+- Under 50 characters total
+
+### Body rules
+
+- Blank line after subject
+- Wrap at 72 characters
+- Explain WHY, not just what
+- Start with explanatory paragraph before bullets
+- Add warmth — show care for users and future developers
+
+### Example
+
+```text
+fix: Fix null pointer in payment validation
+
+When users had incomplete billing data, validation would crash
+instead of showing helpful errors. This adds proper null checks
+and returns meaningful validation messages.
+
+- Add null checks for all required fields
+- Return validation errors instead of exceptions
+- Include tests for edge cases with missing data
 ```
+
+---
+
+## The pre-commit atomicity trap
+
+Pre-commit hooks can accidentally cause you to commit multiple unrelated files together:
+
+1. You stage one file: `git add file1.js`
+2. You run `git commit` and hooks fix OTHER files
+3. You run `git add -A` to include the fixes
+4. **Result**: your commit now includes unrelated files
+
+**Prevention**: Run `pre-commit run --all-files` in Pass 0. This fixes all formatting upfront so hooks have nothing to fix during the actual commit.
+
+---
+
+## Execution
+
+<mark>**Read and follow every step in [WORKFLOW.md](WORKFLOW.md).**</mark>
+
+---
+
+## The governing principle
+
+> Make each commit a gift to your future self — one complete idea, clearly explained, independently revertible.