Skill method-commit

Git Commit

Skill Value

• Problem it solves: Uncommitted work needs to be saved without staging unrelated files or producing vague commit messages.
• Use when: The user says commit, save changes, or create a commit for current staged or unstaged work.
• Output: One or more focused commits with repo-convention messages.
• Ask only if: Only when branch safety, detached HEAD state, or ambiguous grouping blocks a safe commit.
• Do not do: Do not stage unrelated files or commit directly to the default branch without following repo policy.
• Interaction: Check repo/config/chat evidence first. Ask one decision-changing question at a time; use the current harness's blocking question UI when available, otherwise present numbered choices and wait.

Create well-crafted local commit(s) from the current working tree. No push, no PR: use the method-pr skill for the full ship flow.

Context

Gather context at runtime. Run each command below as its own shell call (program and arguments only). Do not join commands with ;, &&, ||, pipes, $(...), or redirects such as 2>/dev/null: that syntax fails under some shells. Read each exit status directly. A non-zero exit is a state to interpret, not a failure to suppress.

Command	Purpose	Non-zero exit / empty output means
git status	Working-tree state	Not a git repository: report and stop
git diff HEAD	Uncommitted changes	Unborn repo (no commits yet): every file is new; rely on git status
git branch --show-current	Current branch	Empty output = detached HEAD
git log --oneline -10	Recent message style	Unborn repo: no history to match
git rev-parse --abbrev-ref origin/HEAD	Remote default branch	No origin/HEAD (it may still print origin/HEAD; ignore that output): run gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'; if that also fails, use main

Default branch name: strip a leading origin/ (so origin/trunk -> trunk) and compare the bare name against the current branch. Never compare against origin/<name>.

This output is a snapshot. Re-read the branch immediately before committing (Step 6).

Workflow

Step 1: Gather and check for work

Run every Context command. If git status shows no staged, modified, or untracked files, report that there is nothing to commit and stop. Do not judge cleanliness from git diff HEAD alone; it misses untracked files.

Step 2: Resolve the branch

• Detached HEAD: if the branch decision cannot be inferred, ask whether to create a feature branch (Skill Value interaction rule). If yes, derive a name from the change content, run git checkout -b <branch-name>, then re-read git branch --show-current. If the user declines, continue on detached HEAD.
• On main, master, or the bare default branch name: create a feature branch without asking; committing on the default branch is not an option here. Derive the name from the change content, run git checkout -b <branch-name>, and re-read git branch --show-current. If the name exists, pick a non-conflicting suffix.
• Unborn repo (git log failed): there is no default-branch history yet. Ask whether the initial commit goes on the current branch or a new one.

Step 3: Determine the message convention

1. Repo conventions already in context: follow commit conventions from loaded project instructions (AGENTS.md, CLAUDE.md, or similar). Do not re-read those files.
2. Recent history: otherwise match a clear pattern in the last 10 commits (conventional commits, ticket prefixes).
3. Default: conventional commits, type(scope): description, with type one of feat, fix, docs, refactor, test, chore, perf, ci, style, build.

Choose the type by intent. Where fix: and feat: both fit, default to fix:: remedying broken or missing behavior is fix: even when it adds code. Reserve feat: for capabilities the user could not previously accomplish. The user may override.

Step 4: Group into logical commits

If changed files clearly split into distinct concerns (for example, a cleaning-script fix and an unrelated figure update), make separate commits. Group at the file level only (no git add -p), 2-3 commits at most. If the split is ambiguous, make one commit.

Step 5: Check for data, PHI, and large outputs

Before staging, review every file named for a commit. Leave out, and report as left out:

• Patient-level or raw data files (.csv, .tsv, .parquet, .feather, .rds, .RData, .sas7bdat, .dta, .sav, .xlsx, and similar) unless they are clearly synthetic fixtures or aggregate outputs the repo already tracks.
• Anything that may hold PHI or identifiers (MRNs, names, dates of birth, free-text notes), credentials, or .env files.
• Large or regenerable outputs: model objects, caches (__pycache__/, .Rproj.user/, .ipynb_checkpoints/), rendered reports the repo does not track, and files over roughly 50 MB.

Never use git add -f on an ignored path. If the user explicitly asks to commit one of these files, confirm it is synthetic or de-identified first.

Step 6: Stage and commit

Re-run git branch --show-current immediately before committing. If it differs from the branch resolved in Step 2, or is now the default branch, stop and re-resolve per Step 2.

Write the message:

• Subject: imperative, names the outcome (what is now possible or fixed), not the file list. Follow the Step 3 convention.
  • Bad: Update clean_labs.R / Add tests and fix stuff
  • Good: fix(cohort): exclude encounters after the index discharge
• Body: only when motivation or trade-offs are not obvious from the subject; separate it with a blank line.

For each commit group, isolate the named files in a temporary index so the user's real index remains untouched until the commit succeeds. Never use git add -A or git add .. For each named file, copy its existing staged snapshot when present; otherwise add its working-tree content only to the temporary index. Write the complete message to a file outside the repository with the file-write tool, then run the bundled script once per group:

SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
if [ ! -f "$SKILL_DIR/scripts/commit-group.sh" ]; then echo "method-commit: scripts/commit-group.sh not found under SKILL_DIR=$SKILL_DIR" >&2; exit 1; fi;
bash "$SKILL_DIR/scripts/commit-group.sh" <message-file> file1 file2 file3

The script copies each file's staged snapshot when present (otherwise its working-tree content), commits the temporary index with git commit -F, then aligns only the committed paths in the real index with the new HEAD. It handles unborn repos and exits non-zero, leaving the real index untouched, if any step fails; stop and report the error. -F passes $, quotes, backticks, and multi-line bodies literally.

Step 7: Confirm

Run git status to verify. Report the commit hash(es), subject line(s), and any files left out in Step 5.