Commit Changes

Create a well-structured git commit with a conventional commit message derived from the current task context.

Rules

• NEVER use

  --no-verify

  . Pre-commit hooks exist for a reason. If hooks fail, fix the issues and retry.
• NEVER use

  git add -A

  or

  git add .

  unless every changed file is relevant. Stage files by name.
• NEVER amend a previous commit unless the user explicitly asks for it.

Step 1: Understand What Changed

Run these in parallel:

1. git status

   — see all changed, staged, and untracked files

2. git diff

   — see unstaged changes

3. git diff --cached

   — see already-staged changes

4. git log --oneline -5

   — see recent commit style for this repo

Review the changes and identify:

• Which files are related to the current task
• Which files are unrelated noise (editor configs, lock files from unrelated installs, etc.)
• Whether any files contain secrets,

  .env

  content, or credentials — never commit those

Step 2: Find the Task Context

Look for task context to derive the commit message from. Check in order:

1. Ralph PRD story — if there's an active story, check

   .ralph/progress.txt

   for the current story ID and title. The commit message should reference this.
2. Recent conversation — what did the user ask you to do? Use that as the commit description.
3. The diff itself — if no other context, derive the purpose from the actual code changes.

Step 3: Craft the Commit Message

Use conventional commits format matching this repo's style:

type(scope): concise description of WHY

Types (pick the right one)

feat

fix

chore

test

docs

refactor

style

ci

Scope

• If working on a Ralph story: use the story ID — e.g.,

  feat(story-3): add user auth

• If working on a specific module: use the module name — e.g.,

  fix(loop): handle empty config

• If broad/cross-cutting: omit scope — e.g.,

  chore: bump version to 3.28.0

Message rules

• Start with lowercase after the colon
• Focus on why, not what — the diff shows what
• Keep the first line under 72 characters
• If more detail is needed, add a blank line and a body paragraph

Examples from this repo

feat: add Working Principles to CLAUDE.md and plansDirectory to settings
feat(story-3): add user authentication with JWT
fix: bash 3.2 unbound variable when run_loop called with no args
chore: bump version to 3.27.1
test(api): add integration tests for /users endpoint
refactor: extract verification into separate modules

Step 4: Stage and Commit

1. Stage only the relevant files by name — do NOT use

   git add -A

   or

   git add .

2. Show the user the proposed commit message and list of staged files before committing
3. Ask if the message looks right using AskUserQuestion with options:
   • "Looks good, commit it"
   • "Let me edit the message" (then ask for their preferred message)
4. Run the commit — use a HEREDOC for the message:

git commit -m "$(cat <<'EOF'
type(scope): message here
EOF
)"

5. Run

   git status

   after to confirm it succeeded

Step 5: Handle Hook Failures

If pre-commit hooks fail:

1. Read the hook output carefully
2. Fix the issues the hooks identified (lint errors, secrets detected, etc.)
3. Re-stage the fixed files
4. Commit again — same message, same process, NO

   --no-verify

If hooks auto-fix files (e.g., prettier, eslint --fix):

1. Review the auto-fixes
2. Stage the auto-fixed files
3. Retry the commit

If you cannot resolve hook failures after 5 attempts, stop and explain the issue to the user. Do NOT bypass hooks.

Notes

• If the user says "just commit it" or similar, still follow the process — just skip the AskUserQuestion confirmation
• If there are no changes to commit, say so and stop
• Group related changes into one commit; suggest splitting if changes are unrelated
• When in doubt about the type,

  feat

  for new things,

  fix

  for broken things,

  chore

  for everything else