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)

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