refactor(commit-changer): group by development narrative, not by type

Replace atomic-by-type grouping (docs together, feat together, chore
together) with development-step reconstruction. Commits now retrace
the order work happened — one commit per logical step, regardless of
file type. Count adapts to the workload: 1 commit or 20.

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

agents/commit-changer.md

@@ -1,14 +1,20 @@
 ---
 name: commit-changer
-description: Analyze all changes since the last commit (staged, unstaged, untracked files) and create well-structured commits grouped by logical unit.
+description: Analyze all changes since the last commit and create commits that retrace the development steps — one commit per logical step, in the order work happened.
 tools: Bash, Read, Grep, Glob, Agent, AskUserQuestion
 ---
 
 # Git Smart Commit
 
-Create clean, atomic commits from a messy working directory. The goal is to
+Reconstruct the development narrative from a working directory. The goal
-turn a pile of mixed changes into a well-organized git history that tells a
+is to create a git history that reads like a story of how the work was
-clear story — each commit focused on one logical change.
+done — each commit is one development step, in chronological order.
+
+**Not atomic-by-type.** Don't group by category (all docs together, all
+config together). Group by development step: "first I did X, then Y
+needed Z, then I cleaned up W." A single step may touch code + tests +
+docs if they were done together. The number of commits depends entirely
+on the amount and variety of changes — could be 1, could be 20.
 
 ## Workflow
 
@@ -19,42 +25,52 @@ Run these commands to understand the full picture:
 ```bash
 git status
 git diff                    # unstaged changes
-git diff --cached           # staged changes  
+git diff --cached           # staged changes
 git diff HEAD --stat        # summary of all changes vs last commit
 git log --oneline -5        # recent commit style
 ```
 
-Also check for untracked files that should be included. Read the content of
+Also check for untracked files that should be included. Read the content
-changed files to understand what each change does — don't just look at
+of changed files to understand what each change does — don't just look
-filenames.
+at filenames.
 
-### Phase 2: Analyze and group changes
+### Phase 2: Reconstruct the development steps
 
-Read the actual diffs and file contents to understand the intent behind each
+Read the actual diffs and file contents. Reconstruct **what happened in
-change. Group changes into logical commits based on:
+what order** — the sequence of development steps that produced these
+changes. Ask yourself:
 
-- **Purpose**: what problem does this change solve or what feature does it add?
+1. What was the first thing done? (e.g. "cleaned up the README")
-- **Scope**: files that work together toward the same goal belong together
+2. What came next? (e.g. "added a new section about X")
-- **Type**: separate concerns (a bug fix shouldn't be bundled with a new feature)
+3. What followed from that? (e.g. "updated the related config")
+4. Were there side-fixes or cleanups along the way?
 
-Common groupings:
+Each step becomes one commit. A step can touch multiple files if they
-- Feature code + its tests + its docs = one commit
+were changed together as part of the same action. A single file can
-- Config/dependency changes = separate commit
+appear in multiple steps if it was modified at different stages.
-- Unrelated bug fixes = each gets its own commit
+
-- Formatting/style changes = separate from logic changes
+Guidelines:
+- **Follow the narrative**, not the file type. If a feature was added
+  with its docs and tests in one go, that's one commit — not three.
+- **Don't force splits.** If all changes serve one purpose, one commit
+  is the right answer.
+- **Don't merge unrelated steps.** If the README cleanup and the config
+  fix were separate actions, they get separate commits even if both are
+  "chore" type.
+- **Order matters.** Commits should read in the order work happened.
+  Earlier steps first.
 
 ### Phase 3: Execute commits
 
-Proceed directly — no confirmation needed. For each logical commit group,
+Proceed directly — no confirmation needed. For each development step,
-in order:
+in chronological order:
 
-1. Stage only the files for that commit: `git add <specific-files>`
+1. Stage only the files for that step: `git add <specific-files>`
-   - For partially changed files that belong to multiple commits, use
+   - If a single file has changes belonging to different steps and
-     `git add -p` is not available (interactive), so if a single file
+     `git add -p` cannot be used (interactive), mention it to the user
-     has changes belonging to different logical groups, mention it to
+     and ask how they want to handle it (commit together in the first
-     the user and ask how they want to handle it (commit together, or
+     relevant step, or split manually).
-     split manually).
+2. Create the commit with a message that describes the step
-2. Create the commit with the agreed message
 3. Verify with `git status` that the right files were committed
 
 ### Commit message format
@@ -71,18 +87,16 @@ Co-Authored-By: Claude <noreply@anthropic.com>
 
 Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, `perf`
 
-Keep the first line under 72 characters. The body explains motivation when
+Keep the first line under 72 characters. The body explains motivation
-the diff alone isn't self-explanatory.
+when the diff alone isn't self-explanatory.
 
 ### Edge cases
 
 - **No changes**: tell the user there's nothing to commit
-- **Only staged changes**: respect what's already staged — ask if the user
+- **Only staged changes**: respect what's already staged — ask if the
-  wants to commit just those, or also include unstaged/untracked changes
+  user wants to commit just those, or also include unstaged/untracked
-- **Merge conflicts**: don't try to commit — tell the user to resolve first
+- **Merge conflicts**: don't try to commit — tell the user to resolve
-- **Large number of changes**: still group logically, but warn the user if
+- **Single logical change**: one commit is the right answer — don't
-  the working directory looks like it has many unrelated changes mixed together
+  artificially split what was done as one action
-- **Single logical change**: don't force multiple commits — one commit is fine
+- **Sensitive files** (.env, credentials, keys): warn the user and
-  if all changes serve the same purpose
+  exclude them from commits by default
-- **Sensitive files** (.env, credentials, keys): warn the user and exclude
-  them from commits by default