commit

name	commit
disable-model-invocation	true
description	Safe commit workflow with optional scope hint. Inventories all changes, classifies related vs. unrelated files, traces dependencies, protects other agents' work, and optionally pushes or lands worktree commits. Usage: /commit [scope] [push|land]
argument-hint	[scope] [push|land]

/commit [scope] [push|land] — Safe Commit Workflow

Commit current work without picking up or harming unrelated changes.

Arguments:

• /commit — commit only, infer scope from diffs
• /commit skill updates — commit, scope guided by "skill updates"
• /commit push — commit and push to remote
• /commit fish genetics fix push — scope-guided commit + push
• /commit land — cherry-pick worktree commits into main (worktree only)

Parsing: push and land are reserved keywords. Everything else in the arguments is the scope hint — a free-form description of what this commit is about. The scope hint is optional; without one, classify from diffs alone.

Examples:

• /commit → scope: (none), action: commit
• /commit fish behavior fixes → scope: "fish behavior fixes", action: commit
• /commit skill updates push → scope: "skill updates", action: commit + push
• /commit push → scope: (none), action: commit + push
• /commit land → scope: (none), action: land
• /commit genetics fixes land → scope: "genetics fixes", action: land

Phase 1 — Inventory

Run these in parallel:

git status -s            # all changes (never use -uall)
git diff                 # unstaged changes
git diff --cached        # staged changes
git log --oneline -10    # recent commit style

Also determine context:

• Which branch am I on?
• Am I in a worktree? (git rev-parse --show-toplevel differs from main repo)
• Is there a remote tracking branch?

Phase 2 — Classify Changes

For every changed and untracked file from git status -s, decide:

1. Related to current work — include in this commit
2. Unrelated (other agents/sessions) — leave alone, do NOT touch

If a scope hint was provided

The scope hint tells you what this commit is about. Use it to drive classification:

1. Keyword grep — search the file list for scope-related terms:

   git status -s | grep -i <keyword>
   

   For /commit skill updates, grep for skill, SKILL, .claude/skills/. For /commit fish behavior, grep for fish, behavior, js/.

2. Diff-check remaining files — for files that don't match the keyword, read the diff to confirm they're unrelated. Some related files won't match a simple grep (e.g., a memory file updated alongside skill changes).

3. Confidence is higher — with a scope hint, you can be more decisive about what's in vs. out. Without one, you have to read every diff and infer.

If no scope hint was provided

Fall back to the original approach:

• Read the diff for each modified file. Does it relate to what we worked on?
• For untracked files (??): are they part of this feature? If unsure, ask.

Always

• Context compaction warning: Do NOT rely on session memory for "what I changed." Context compaction creates artificial boundaries. Always classify from the actual diffs and the scope hint.
• If a file has mixed changes (yours + someone else's): STOP. Tell the user which file and what the mixed changes are. Ask what to do. Do NOT attempt to split hunks or selectively stage — that risks losing work.

Phase 3 — Trace Dependencies

For every file classified as "related":

1. Check its imports. If it imports an uncommitted file, that file MUST be included. Recurse.
2. Check for associated files:
   • New module → its tests?
   • New component → styles, config, registration?
   • Plan/doc changes related to the code change?
3. Search broadly: git status -s | grep -i <feature-keyword> If a scope hint was provided, use terms from the hint as keywords.
4. Check .claude/logs/ — include session logs for this session.

Common mistakes to avoid:

• Committing A.js which imports B.js without committing B.js → 404
• Committing a module but not its tests
• Missing files from a prior compacted context (they show as ??)

Phase 4 — Stage & Review

1. Check for pre-staged files before adding anything:

   git diff --cached --stat
   

   If files are already staged that you didn't stage, another session left them in the index. STOP and report — do not commit on top of someone else's staged work.

2. Stage only the related files by name:

   git add file1 file2 ...
   

   NEVER use git add . or git add -A — these grab everything.

3. Review what's staged — verify the count matches what you just added:

   git diff --cached --stat
   

   If the file count is higher than the number of files you staged in step 2, something else was already in the index. Investigate before committing.

4. Present the staged file list to the user and confirm it looks correct.

Phase 5 — Commit

1. Draft a commit message:

   • Summarize the nature of the change (feat, fix, refactor, docs, chore)
   • Focus on the why, not the what
   • 1-2 sentences, concise
   • Follow the style of recent commits (git log --oneline -10)
   • If a scope hint was provided, use it to inform the message (but don't just parrot it — write a proper commit message)

2. Run tests if code was staged — if any staged files are code (.js, .css, .html), run npm test before committing. All suites must pass. If tests fail after two fix attempts on the same error, STOP and report to the user (CLAUDE.md: "NEVER thrash on a failing fix"). Skip this step for content-only commits (.md, .jpg, .png, logs).

3. Dispatch a fresh agent to review the staged changes before committing. The agent receives git diff --cached and the proposed commit message. It checks:

   • Are all related files included? Any missing dependencies?
   • Are any unrelated files accidentally staged?
   • Does the commit message accurately describe the changes?
   • Any obvious issues in the diff (debug code, TODOs, broken imports)?

   Do NOT review the staged changes yourself — you selected the files, so you have selection bias. A fresh agent catches files you missed or included by mistake.

   If the agent raises concerns: STOP. Report the concerns to the user. Do not commit until concerns are resolved.

   If the agent approves: proceed to step 4.

4. Commit using a HEREDOC for clean formatting:

   git commit -m "$(cat <<'EOF'
   <type>: <message>
   
   Co-Authored-By: Claude Opus 4.6 (1M context) <[e-mail]>
   EOF
   )"
   

5. Verify:

   git status -s
   

If a pre-commit hook fails: fix the issue, re-stage, and create a NEW commit. NEVER use --amend after a hook failure — the commit didn't happen, so amend would modify the PREVIOUS commit. Maximum 2 attempts on the same hook error — if it fails twice, STOP and report.

Phase 6 — Push (if push argument)

Only if push was in the arguments:

git push

If there's no upstream tracking branch:

git push -u origin <branch-name>

NEVER force-push to main/master. If push is rejected, tell the user why and ask what to do.

Phase 7 — Land (if land argument)

Only if land was in the arguments. This is for landing worktree work onto main via cherry-pick.

Pre-checks:

• Confirm we're in a worktree (not main). If on main, stop and explain.
• Ensure all worktree changes are committed first (run Phases 1-5 if needed).

Steps:

1. Identify commits to land:

   git log --oneline main..HEAD
   

   Present the list to the user for approval.

2. Switch to main repo and protect uncommitted work:

   cd <main-repo-path>
   

   Check for uncommitted changes or untracked files:

   git status -s
   git status -s | grep '^??'
   

   If any exist:

   git stash -u -m "pre-cherry-pick stash from /commit land"
   

3. Cherry-pick approved commits:

   git cherry-pick <commit-hash>
   

   • One at a time. Verify each succeeds before the next.
   • If a conflict occurs: STOP. Report the conflict to the user. Do NOT force-resolve, skip, or abort without asking.

4. Restore stash if one was created:

   git stash pop
   

   If pop conflicts, tell the user.

5. Run tests after cherry-picks land:

   npm test
   

   If tests fail, report to the user. Do NOT attempt to fix — the cherry-picked code was already tested in the worktree. A failure here means a main-specific conflict that needs human judgment.

6. Write .landed marker on the worktree (so cleanup knows it's safe to remove):

   cat > "<worktree-path>/.landed.tmp" <<LANDED
   status: full
   date: $(TZ=America/New_York date -Iseconds)
   source: commit-land
   commits: <list of cherry-picked hashes>
   LANDED
   mv "<worktree-path>/.landed.tmp" "<worktree-path>/.landed"
   

7. Verify:

   git status -s
   git log --oneline -5
   

Key Rules

• NEVER use git add . or git add -A — stage files by name only.
• NEVER touch unrelated changes — other agents may have work in progress. Do not git checkout --, git restore, git stash (without -u), or otherwise discard changes you didn't make.
• NEVER amend after hook failure — create a new commit instead.
• NEVER force-push to main/master — warn and ask.
• NEVER push without the push argument — commit only by default.
• Protect untracked files — before stash/cherry-pick, inventory untracked files (git status -s | grep '^??'). Use git stash -u not git stash.
• If unsure whether a file is yours: ask. The cost of asking is low. The cost of committing or discarding someone else's work is high.
• Include .claude/logs/ — session logs should be committed alongside code changes.
• Always use HEREDOC for commit messages — ensures clean multi-line formatting.
• Scope hint is advisory, not absolute — even with a scope hint, check diffs. Some related files won't match the hint keywords, and some keyword matches may be unrelated. The hint narrows the search; it doesn't replace judgment.