How to comment on a Markdown file the LLM will actually read

By Elad Diamant·Published April 21, 2026

Claude returned 1,800 words. It's 82% fine. The 18% that isn't is spread across five specific passages — a wrong assumption in section two, a missing edge case, a tone problem in the third bullet, a hallucinated dependency, a step that's out of order. You want to fix those five, not rewrite the whole thing. So you start typing.

You type the first correction. Forty-five seconds. You re-read it; you're proud. Four to go.

By the third one, the original answer has scrolled out of view. You stop describing the location and just paraphrase the fix: "and somewhere there's a paragraph on retention that needs to say it more directly." You know, as you type it, that the model is going to pick the wrong paragraph. You send it anyway. By the fourth, you decide — audibly, in the voice of a person who has given up — the model will probably catch those on its own. It will not. Three of five make it into the message. The next answer comes back wrong on the other two.

That is what "commenting on a Markdown file" looks like in 2026 when the reader is the language model that wrote it. It looks like quietly losing two corrections per round to the writing tax of the chat box. This post is about the format that stops that from happening, and the one comparison that matters: the chat box you would otherwise be typing into.

Why the chat box can't carry five corrections

There is exactly one place the feedback has to land: back in the chat with the model that wrote the answer. Anywhere else is a detour, because anywhere else the model can't read it. Comment on the file in a doc you keep on your hard drive and the model never sees it. Annotate it inside the rendered Markdown in your editor and the model never sees it. The chat is the workspace because the chat is the only surface that returns. So the real question — the only one — is the one you actually face every time: why not just type it into the chat.

And for one correction, you can. For five, you can't — not because the chat box is broken, but because writing each correction in prose, with the original answer scrolled out of view, is hard enough work that the last two get silently downgraded. The gap isn't in the chat box's plumbing; the gap is in you, by the fourth correction, deciding that points four and five aren't worth typing. (The full argument is in the manifesto; this post is the field manual that demonstrates it.)

What you need is a format that does the writing tax for you — that lets you raise five points as comfortably as you raised the first one, and lands all five back in the chat anchored to the exact passages they refer to, so the model can't pick the wrong target on the next turn.

The format that does work

It's not a tool. It's a shape. Each comment is a verbatim quote from the model's answer followed by your note, separated by ---, sent back in one message with one instruction at the top: apply these edits; leave everything else unchanged. The model maps every note to its exact passage and applies the whole set in a single round-trip. The export block looks like this:

# Apply these edits to your last answer. Leave everything else unchanged.
---

"the system can leverage a cross-functional synergy touchpoint"
[Off tone] too corporate. "this connects to X" is plenty.

---

"delight velocity"
[Delete] we do not measure this.

---

"moreover,"
[Delete] One use of "moreover" per page, maximum.

---

The full walkthrough — why this works, the manual recipe you can do in any plain-text editor, and the mechanism for anyone who wants to understand why structured input beats prose — is in the guide. The browser tool that automates the highlighting and the export is right here.

The footnote: HTML comments inside the file

One related question gets asked enough that it earns a section: "can't I just leave HTML comments in the Markdown itself?" In a .md file you own and never hand off, yes:

## Introduction

Welcome to the product. <!-- @tom — too corporate? -->

Works as a personal sticky note. Won't help you with the chat-box case above, because an HTML comment inside a chat message is read by the model as text, not as a review annotation — and even if the model does read it, you've still typed the location in prose ("the comment after the Introduction heading") which is the exact problem we just solved. HTML comments answer a different question: leaving notes to yourself inside a file you will edit later. They are not the format that returns five corrections to a chat.

One catch worth knowing: HTML comments pass through to rendered HTML. The first time a reviewer forgets to delete one before publishing, they learn that <!-- --> is very much visible in your RSS feed and your search index.

What changes when the format does the writing tax for you

Step out of the chat box for the feedback step, and the things that used to happen in your head stop happening.

• Point four makes it into the message. The reason it didn't before was that typing the directions to it — "in the bullet under Architecture, not the second one, the third" — cost more than the correction was worth. Highlight the passage; type the note. The friction that made point four not worth raising is gone.
• You stop hedging the location. The verbatim quote rides along with every comment. You stop writing "somewhere there's a paragraph on retention" and start writing the fix.
• The model stops picking the wrong target. Not because the model got smarter — because the message it's reading no longer leaves the target ambiguous. Five corrections, five anchored quotes, no "not that one, the other one" on the next turn.
• One round-trip instead of four. The five corrections that used to need four turns and a fight about which bullet you meant land in one paste. The next answer is wrong on zero of five, not three of five.

None of this requires a smarter model. The model that wrote your 1,800-word answer already applies five clearly-anchored corrections in one paste when it gets them. The bottleneck was never the model — it was the four minutes between you reading the answer and you giving up on points four and five. Move the writing out of the chat box, and the bottleneck goes with it.

That's the whole field manual. The rest is taste.