Markdown is the source. HTML is the review layer.

The Markdown vs HTML debate keeps getting framed as a choice.

It is not a choice. They serve different jobs.

Markdown is where I keep the source. PRDs, architecture notes, decisions, research, sprint plans, SOPs — all of it lives in Markdown. It is clean, diffable, searchable, and easy to pass back into an agent on the next turn. Agent memory.

HTML is the review layer. Not the source, not the final artifact — a surface for human reasoning after the Markdown has enough shape.

The pattern I have settled into looks like this.

Brainstorm in Markdown. Let ideas diverge — multiple flows, options, branching structures, rough arrows in text. This is one of the most useful things about working with AI: the divergence is cheap. You can have three different versions of an idea before you have committed to any of them.

Once the Markdown has shape, generate a simple HTML review page. Not polished, not final. Just visual enough to make the structure apparent.

Flows become visible. Timelines become visible. Dependencies become visible. Gaps become visible.

The HTML does not change the source. It is a second pass that lets you ask: can I see this clearly enough to make a better decision?

The prompt that produces this is not complicated:

Take these Markdown files and create a simple standalone HTML review page.
Show the flow of the idea, key decisions, open questions, risks, and relationships
that are easier to understand visually. Use tables, timelines, grouped sections
where they help. Do not change the source content. Make the HTML a review
surface for human reasoning.

The output is not a website. It is a thinking tool.

For product work, this slots in before wireframes or hi-fi design:

1. Brainstorm messy ideas in Markdown
2. Let the agent diverge into multiple flows or options
3. Generate the HTML review page
4. Pick the strongest direction
5. Only then detail it into design or implementation

The visual layer is the reasoning surface before the final design surface. It makes the shape of the work obvious to a human before the team commits to building it.

The reason this distinction matters is that a text-only agent reading your HTML is mostly just reading markup — the visual structure means nothing to the model. But to a human, a well-structured HTML page can reveal in ten seconds what takes ten minutes to extract from a flat document.

Markdown is for agents. HTML is for you.

Keep the source clean. Use the review layer when the shape matters more than the content.