Commit and PR Writer

Describe exactly what changed and why — nothing more.

Step 1 — Read the actual changes

Run:

1. git status — see what is staged, unstaged, untracked
2. git diff --cached — the staged diff (this is what gets committed)
3. git diff — unstaged changes, so you can warn if relevant work is not staged

If nothing is staged, tell the user and ask whether to describe the unstaged diff or stage files first. For PR descriptions, also run git log <base>..HEAD --oneline and git diff <base>...HEAD (default base: main, fall back to master) to cover all commits on the branch, not just the latest.

Step 2 — Understand the change

From the diff alone, determine:

• What changed (files, functions, behavior)
• Why — infer from the code; if the motivation is genuinely unclear and it matters for the message, ask one short question instead of guessing
• Type: feat (new behavior), fix (corrects wrong behavior), refactor (no behavior change), perf, docs, test, chore (build/deps/config), ci
• Scope (optional): the touched module, e.g. feat(auth): — only if obvious
• Breaking? — changed public signatures, removed exports, migration required

Hard rule: every statement in the message must be traceable to a line in the diff. Do not mention tests unless test files changed. Do not claim performance improvements unless the diff shows the optimization. Do not pad with speculation.

Step 3 — Write the commit message

Format:

<type>(<scope>): <imperative subject, ≤72 chars, no trailing period>

<body: 1-5 lines explaining WHY the change was made and any non-obvious
decision. Wrap at 72 chars. Omit the body only for trivial changes
where the subject says everything.>

BREAKING CHANGE: <only if applicable — what breaks and how to migrate>

Subject rules:

• Imperative mood: "add rate limiting", not "added" or "adds"
• Specific: "fix null deref when config file is empty", not "fix bug"
• One logical change per commit — if the diff contains unrelated changes, say so and propose splitting it into separate commits (list which files go where)

Present the message in a code block. If the user asks you to commit, use a heredoc: git commit -m "$(cat <<'EOF' ... EOF)" — never commit without showing the message first.

Step 4 — PR description (only when asked)

## <Title — same rules as commit subject, may drop the type prefix>

### Summary
- 2-5 bullets: what changed and why, most important first
- Call out breaking changes and migrations explicitly

### Test notes
- How this was verified (commands run, cases covered) — only what actually happened
- If untested, write "Not yet tested" — never fabricate test results

### Notes for reviewers (optional)
- Where to start reading, known trade-offs, follow-ups deliberately left out

Quality checklist

• Every claim maps to a hunk in the diff
• Subject ≤72 chars, imperative, specific
• Type matches the dominant change (a fix with drive-by refactor is still fix)
• Body explains why, not a restatement of the diff
• Warned the user about relevant unstaged files, if any