Pimp My IDE / garage dispatch
Back to garage
September 30, 2026 | Git / agent review / comprehension

Write the reason before you ship.

An agent can describe its diff. That does not mean it knows why your team wanted the change. Use the commit description as a comprehension test before the code enters history.

If you cannot state the behavior, reason, tradeoff, and exit condition without borrowing the agent's confidence, keep the change out of the release lane.

A convincing description can still be invented.

Yedhu Krishnan writes that drafting a commit body used to make him reread the code, summarize the change, and reconsider decisions. In agent-written code, he sees a new failure. The agent may know the diff but miss the reason scattered across conversations, project tools, or offline decisions. It can fill that gap with plausible reasoning.[1]

Giving the agent more context can reduce that error. It does not prove that the author understands the resulting code. Krishnan's practice is direct: he writes the commit description himself. If he cannot explain why the change exists, he does not understand what he is shipping.[1]

The commit body is useful before it becomes history. Writing it can expose a change you cannot yet defend.

Git records a message, not its truth.

The git commit documentation says a commit records the current index and a log message that describes the changes. It also offers --dry-run to summarize what the next commit would include and --patch to choose changes interactively.[2] Those controls help align the message with the actual patch. They do not check the reason in the prose.

Pro Git recommends logically separate changesets and useful messages. Its commit guideline asks for a concise subject, then a body that explains motivation and contrasts the new implementation with previous behavior.[3] The point is not a universal character-count ritual. The point is to leave a reviewable explanation attached to a bounded change.

The reason needs an owner.

Chris Beams distinguishes the diff from the message. The diff shows what changed. The message should explain the reason. His guide also says not every commit needs a body. A simple typo can stand on one line, while a consequential change needs context and side effects.[4]

An agent can draft that body. Keep the ownership clear. "Agent draft" means a person must challenge each factual claim and supply the missing project decision. "Human writes" means the person owns the words but still checks them against the staged patch. "Team review" means the explanation is examined with the code.

Make temporary decisions admit that they are temporary.

Krishnan calls out sentences such as "I am doing this until we..." because they capture exit criteria that may not exist in code or project tools.[1] That small sentence prevents a workaround from becoming permanent through silence.

  1. State the user-visible or system behavior that changed.
  2. Name the project reason. Do not infer it from the patch.
  3. Record the cost, rejected option, or condition the change accepts.
  4. Write the event that should trigger removal or reconsideration.
  5. Compare every sentence with the staged diff before committing.
Interactive makeover / explanation press

Press the reason into the record

Traditional purpose replaced: accept the generated commit message because it sounds complete. Better version: name who owns the words, select the questions that were answered, and copy a review card with unresolved evidence left visible.

Choose the writing route

The selected route changes the review duty. Native radios and checkboxes keep the control keyboardable.

Description owner
Explanation sections
Explanation draft0 / 4 sections

The reason is still blank.

Read the staged patch, then write what changed and why the project needs it. The generated description is not evidence by itself.

Selecting all four sections means the template structure is ready. The blank fields still need project facts, patch inspection, tests, and review.

Four questions before commit

Keep description and evidence separate.

01 / BEHAVIOR

Say what changed

Describe the observable difference. Check it against the staged patch and the relevant test.

02 / REASON

Name the decision

Use the real issue, conversation, incident, or product decision. Do not let the patch invent its own purpose.

03 / TRADEOFF

Leave the objection attached

Record the cost and the rejected option so a future maintainer can challenge the choice.

04 / EXIT

Give temporary code a clock

Name the event, metric, dependency, or date that should reopen the decision.

Sources read

Source log and evidence boundary
  1. Yedhu Krishnan, "Commit Description as a Thinking Tool", published and read September 30, 2026. The author describes writing commit bodies as a way to reconsider code, detect missing reasons in agent-written descriptions, and state exit criteria.
  2. Git documentation, git-commit, read September 30, 2026. The reference documents commit contents, log messages, dry-run summaries, patch selection, templates, trailers, and verification controls.
  3. Pro Git, "Contributing to a Project" commit guidelines, read September 30, 2026. The book recommends logically separate changesets and messages that explain motivation and contrast new behavior with the previous implementation.
  4. Chris Beams, "How to Write a Git Commit Message", read September 30, 2026. The guide distinguishes what the diff shows from why the message exists, and explains when a body adds useful context.
  5. Hacker News discussion, exact item 49911757, checked September 30, 2026. It led to Krishnan's post. Reader comments are not used as evidence.

Evidence boundary: this page combines one practitioner's method with Git documentation and established writing guidance. It does not prove that human-written messages are accurate, that agent-written messages are false, or that a complete description makes a change safe to merge. The press creates a review template. It does not inspect a repository.