Markleft: How I review claude plans in Markdown | Martin Lysk

Skip to main content<br>AI output seldom meets the intent on the first prompt, so iteration is necessary. Today, iteration usually means providing feedback in a follow-up prompt, which leads to a rewrite of the whole document. The prompt that explains the intent behind the revision remains buried in the chat.

Imagine sending a colleague a five page document. They read it and have some concerns. The workflow would not be:

Email me a prose description of everything you dislike

I send you a completely rewritten document

Then compare the two files and figure out whether I understood you

That is absurd—this workflow has been solved for decades by comments and tracked changes in Word, or by Suggesting mode in Google Docs.

Want to see it in action? spoiler

Working with AI in Markdown and where it breaks​

Let's play through the process of creating a document—and iterate once.

A prompt to Claude:

Please write a little story about a pelican on a bike in Markdown, and add a small SVG illustration of the pelican.

This results in:

Markdown

### A Poor Pelican<br>Perry the pelican found a bright<br>red bicycle leaning against the pier—and,<br>after one curious glance,<br>decided it was exactly the sort of adventure<br>the morning required.<br>He wobbled past the fishing boats,<br>rang the tiny bell with his beak,<br>and rolled onto the beach—just in time for breakfast.<br>

Rendered<br>A Poor Pelican​

Perry the pelican found a bright red bicycle leaning against the pier—and, after one curious glance, decided it was exactly the sort of adventure the morning required. He wobbled past the fishing boats, rang the tiny bell with his beak, and rolled onto the beach—just in time for breakfast.

Step one: Collecting and formulating the critique​

Turning your feedback into useful instructions is already a precision problem.

The headline promises the wrong story. Remove the em dashes, shorten the second sentence , fix the pelican's head, put the left foot on a pedal, and make the bird look sportier.

That sounds specific. It is not.

“The headline ” works only because this toy document has one obvious headline. In a longer article you need to describe the headline you want to change.

“The second sentence ” is way more specific, but it makes both the reviewer and the AI count sentences, hoping both count them the same way.

“The left foot” is worse: prose cannot point to the exact shape in the SVG that broke the illusion. That is why tools such as Figma allow comments directly on the design surface.

Now try giving the same kind of feedback on a multi-page document with repeated headings, nested tables, diagrams, and code.

Please update the second image in the third paragraph that displays the network architecture. Move the backup server to the top right, next to the second database server, in read-only mode.

In larger documents, another problem emerges: collecting the feedback in the first place. While reading paragraph 1, one may think, “This doesn't make sense,” but maybe paragraph 3 explains it. When such a thought comes up, I don't want to stop reading and formulate a prompt. I want to leave a mark, continue reading, and come back later.

Step two: Understand the change​

Several approaches can help, but they share the same weakness: the AI produces a new document before the author can review the proposed changes in context.

We are still in the first iteration. An update executed by an LLM does not mean that our feedback was taken into account or that our intent was met. We are left with two tasks:

Find the change. One round of “spot the difference” across the whole document. Git can show diffs, but changes hidden behind rendered Mermaid diagrams, tables, and SVGs are much harder to grasp.

Recover the intent. Once we know what changed, we still have to remember which part of our original prompt the change was meant to address and decide whether the result actually satisfies the feedback.

Remember that more specific prompt:

shorten the second sentence

What if the first sentence is dropped in the rework by the AI? Mapping this prompt to the intent means:

What was sentence 2 before the change?

How did this sentence change?

Does this reflect the intent of being shorter?

We should only care whether that sentence is now shorter.

The Idea—Suggestion Mode for Markdown​

What is needed is a way to annotate parts of the document directly instead of describing their location vaguely, along with a way to review proposed changes against those annotations.

This is exactly what Markleft provides. It is based on three main components:

A WYSIWYG Markdown editor for humans to create and edit comments , propose changes, and apply suggestions without thinking about the underlying format.

A Markdown-compatible annotation spec consumable by AI, allowing users to comment on text, code, tables, Mermaid diagrams, images, and SVGs, and to propose...