commit-writer

name	commit-writer
description	Create accurate git commit messages or commits from current repository changes, staged diffs, and session context. Use when asked to commit, write or revise a commit message, finalize staged work, prepare a changelog-ready commit, or summarize backend, infrastructure, data, AI, ML, model, prompt, evaluation, or experiment changes for git history.

Commit Writer

Goals

• Produce a commit message that matches the actual staged changes.
• Preserve rationale from the session without inventing behavior.
• Follow repo-specific conventions first, then use Conventional Commits.
• Work for backend systems and AI/ML model development without assuming a project type.

Inputs

• Session history for intent, rationale, trade-offs, and validation already run.
• git status --short, git diff, and git diff --staged.
• Repo conventions from files such as CONTRIBUTING.md, README.md, .github/, commitlint config, release docs, or recent commit history.
• User constraints such as "message only", "do not commit", "no Co-authored-by", or a required scope/type.

Workflow

1. Clarify the requested output. If the user asks only for a message, do not stage files or commit.
2. Inspect the working tree and index with git status --short, git diff --stat, git diff, and git diff --staged.
3. Identify the intended scope from the session and diff. If unrelated changes are mixed together, ask whether to split commits or stage only the relevant paths.
4. Stage only intended files. Use explicit paths when the worktree contains unrelated changes; use git add -A only when the full scope is clear.
5. Re-check git diff --staged after staging. The message must describe the staged diff, not unstaged files or intended future work.
6. Choose a type and optional scope. Prefer repo conventions; otherwise use Conventional Commit style.
7. Write a subject in imperative mood, at most 72 characters, with no trailing period.
8. Write a body that explains what changed, why it changed, and how it was validated.
9. Note tests honestly. Use not run (reason) when validation was not run.
10. Add footers only when applicable: breaking changes, issue references, migration notes, experiment IDs, model/version identifiers, or co-author trailers.
11. Commit with a message file and git commit -F <file> so newlines are literal. Avoid git commit -m chains for multi-line messages.
12. After committing, report the commit hash, subject, and validation status.

Type And Scope Guidance

Use the narrowest accurate type:

• feat: user-visible capability, API behavior, model capability, or workflow support.
• fix: bug fix, regression fix, data handling correction, prompt or inference correction.
• perf: latency, throughput, memory, cost, batching, caching, query, or inference speed improvement.
• refactor: internal restructuring without behavior change.
• test: unit, integration, regression, eval, benchmark, fixture, or test harness changes.
• docs: docs, examples, runbooks, model cards, experiment notes, or API docs.
• build: dependency, packaging, lockfile, image, toolchain, or generated client change.
• ci: pipeline, workflow, release automation, or quality gate change.
• chore: maintenance with no direct runtime behavior change.
• revert: reverting a previous commit.

Use scopes that match the codebase. Common backend scopes include api, auth, db, migration, cache, queue, worker, config, observability, and infra. Common AI/ML scopes include model, training, inference, eval, data, features, prompts, embeddings, rag, and experiments.

Backend Checks

When backend changes are present, inspect for:

• API contract, route, schema, serialization, auth, permission, or error behavior changes.
• Database migrations, seed data, indexes, backfills, and rollback implications.
• Configuration, environment variables, secrets handling, and deployment impact.
• Async jobs, queues, retries, idempotency, observability, and operational risk.

Mention these in the body only when they are real and relevant.

AI And Model Checks

When AI/ML changes are present, inspect for:

• Model architecture, weights, adapters, tokenizer, inference path, or serving behavior changes.
• Training, fine-tuning, evaluation, benchmark, dataset, feature, or preprocessing changes.
• Prompt, tool-use, RAG, embedding, retrieval, ranking, or guardrail changes.
• Reproducibility details such as config names, seeds, dataset versions, eval suites, or experiment IDs.

Flag large or sensitive artifacts before committing: model weights, datasets, checkpoints, embeddings, cache directories, logs, API keys, credentials, .env files, notebooks with outputs, and generated reports not intended for git.

Message Shape

Use this default structure unless the repo has a stricter convention:

<type>(<scope>): <short imperative summary>

Summary:
- <what changed>
- <what changed>

Rationale:
- <why this change is needed>
- <trade-off or design choice, if relevant>

Validation:
- <command/result or "not run (reason)">

Risk:
- <migration, rollout, model behavior, or operational risk if relevant>

Co-authored-by: Codex <[e-mail]>

Omit empty sections. Include BREAKING CHANGE: footers when the staged diff changes public APIs, schemas, data contracts, model interfaces, or deployment requirements incompatibly.

Guardrails

• Never commit unrelated user changes without explicit approval.
• Never claim tests, evals, benchmarks, or migrations were run unless the session shows they ran.
• Never hide generated artifacts, secrets, checkpoints, or datasets inside a broad commit.
• Never describe unstaged changes in the commit message.
• Do not rewrite history, amend, squash, or split commits unless the user asks.
• Prefer asking one concise question over making a risky staging decision.

Output Modes

• If committing: create one commit, then report hash, subject, and validation.
• If writing a message only: return the complete commit message in a fenced gitcommit block.
• If the staged diff is unsafe or ambiguous: stop and explain the blocking files or decision.