Reviewing agent commits that touch .md files

An agent's commit just landed, and some of the files in it are Markdown: a plan, a README, a handoff note, a docs page. Code gets a careful review. Markdown often gets a quick glance. A reformatted file or a changed status line gets past a quick glance.

Here are five steps for reviewing an agent's commit when it touches .md files. It builds on the wider guide to seeing what changed in a Markdown file. For the git basics, see how to diff Markdown files with git. Here the focus is a commit someone else made, and that someone is an agent.

Before you start

You need the commit or the branch. If the agent made one commit, get its hash from git log --oneline. If it worked on a branch, you can review the whole branch against main.

All the commands below are plain git. They only read. None of them change your files.

1. List the Markdown files it changed

Start with the size of the change, not the content.

For one commit:

git show --stat <commit> -- '*.md'

For a whole branch, compared with where it split from main:

git diff --stat main...HEAD -- '*.md'

The three dots mean "what changed on this branch since it left main." Changes made on main in the meantime are left out.

The -- '*.md' part limits the output to Markdown files, in any folder. Keep the quotes, so git matches the pattern and not your shell. If you only want file names, use --name-only in place of --stat.

Now compare the list with what you asked for. A file you did not expect is your first question for the agent.

2. Read the prose word by word

A Markdown paragraph is often one long line. Change one word and a normal diff shows the whole paragraph removed and added again. Word diff fixes that:

git diff --word-diff main...HEAD -- docs/plan.md

For a single commit, git show --word-diff <commit> -- docs/plan.md does the same. Removed words show as [-old-] and added words as {+new+}. The rest of the line stays as plain context.

Read for meaning here. Did the agent soften a requirement? Change a number? Drop a step from a list? Those are the edits that matter, and word diff makes them easy to find.

If a file has a long history of agent edits, git log -p -- docs/plan.md shows each commit to that one file with its diff.

3. Hide whitespace churn to spot a reformat

Sometimes the stat from step 1 looks wrong. You asked for a small fix, and the file shows dozens of changed lines. Here is what that looks like for a placeholder plan file that got one status change, one word change and a trimmed trailing space on most lines:

git diff --stat main...HEAD -- docs/plan.md

 docs/plan.md | 82 ++++++++++++++++++++++++++++++------------------------------
 1 file changed, 41 insertions(+), 41 deletions(-)

Now run the same stat while ignoring whitespace and blank lines:

git diff -w --ignore-blank-lines --stat main...HEAD -- docs/plan.md

 docs/plan.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

The real edits were two lines. The other 39 changed lines were whitespace only. In a real commit that churn can also be blank lines added or removed, or indents changed.

A big drop between the two stats means the file was reformatted. The commit still holds all of those changed lines. The flags only hide them from your view.

The -w flag ignores whitespace inside lines. --ignore-blank-lines hides changes that are made up only of blank lines. Neither one hides a swapped list marker, such as every * turned into -. Those still show up. Word diff from step 2 helps you see past them.

Why this matters: trailing spaces can be a hard line break in Markdown. Removing them can change the page. And the next person, or agent, who runs git blame on that file will see the agent's commit on every reformatted line. Why editors reformat Markdown on save covers the usual causes.

4. Check that front matter edits are intended

Many agent-written files start with a YAML header between --- lines. It holds fields like status, date and owner. A small change there can change how the file is used. A plan marked status: done may stop getting attention.

Front matter sits at the top of the file, between the first two --- lines. So read every hunk whose line numbers fall inside that block. The first one often starts near line 1, as in @@ -1,8 +1,8 @@, but a change deep in a long header can start lower. For each changed field, ask:

• Did you ask for this change?
• Is the new value true? If work is still open below a done, ask why it says done.
• Did a date move forward without new work behind it?
• Did a field disappear, or did its spelling change, such as owner becoming Owner?

Tools that read front matter often match field names exactly. A renamed key can quietly break a script or a list that sorts by status.

5. Ask the agent to undo the churn

If step 3 showed churn, do not fix it by hand line by line. Ask the agent. Be specific about what to keep. For example:

Your last commit reformatted docs/plan.md. Only two lines were real edits: the status and one word. Keep those two edits and undo every other change to whitespace, blank lines, list markers and line wrapping. Then show me git diff --stat main...HEAD -- docs/plan.md.

The final sentence asks for a number you can check yourself. When the new stat shows a small count with and without -w, the churn is gone.

If the agent keeps reformatting, the cause may be a formatter it runs, or a tool that saves the file in its own style. Ask it which commands touched the file. You can also add a line to its instruction file, such as "never reformat Markdown files you edit."

A short checklist

1. List the .md files the commit or branch changed.
2. Read the prose with --word-diff.
3. Compare the stat with and without -w --ignore-blank-lines.
4. Read the front matter hunk at the top of each file.
5. Ask the agent to undo any churn, and check its new stat.

For why an untouched line should come back the same after a save, see what a byte-for-byte round-trip save is.

Where Sashmark fits

Sashmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released. Edit in place with a clean Round-Trip is planned for v1: lines you did not edit stay byte-for-byte the same, so a fix you make would leave the rest of the diff small. A Changes View, which highlights what changed since you last looked with no git needed, is also planned for v1. The app itself has no AI features. See the planned features, the help pages and the roadmap for where each part stands.

See what Sashmark is and follow along at sashmark.com.