Prompt to mermaid diagram, with prompts that survive a retry

A prompt to mermaid diagram comes back as valid Mermaid when you name the diagram type, the node labels, and the decision that splits the path. A vague sentence spends one of the five free AI uses on a picture you will delete, and those five are a lifetime total, not a refill that shows up tomorrow.

I treat the prompt like a tiny spec. If I can't point at the boxes before I hit generate, the model will invent a plausible system and I will argue with it. That's a bad use of a scarce generation. The AI diagram generator will happily draw whatever you imply. Your job is to stop implying.

Name the type before you name the story

The first word that matters is the diagram type. "Diagram" is not a type. A flowchart, a sequence diagram, and a block grid are different files, and the model picks one if you don't. I say the keyword I want in the source, not a vibe. "Flowchart, top down" is a different request from "show the deploy."

Direction is the second word. Top down fits a decision. Left to right fits a pipeline. If you skip it, you get whichever the model saw more often in training, and then you spend a use flipping LR to TD. You could have typed two words.

Then the nodes, as a closed list. "Nodes only: Commit, CI, Staging, Production. Decision: tests passed? Decision: reviewer approved?" A closed list is the difference between a chart of your pipeline and a chart of every tool the model associates with shipping. I also name the edges that aren't obvious. "If tests fail, return to Commit. Do not add a rollback service."

Exclusions belong in the same sentence as the thing they block. An exclusion parked at the end reads like a suggestion. "Do not add Slack, a ticket, or a node that isn't in the list" has to sit next to the path, or the extra box still appears and you feel rude deleting it. You shouldn't. It wasn't yours.

Ids are for you. Labels are for the reader. If you care about the source, say "ids: commit, ci, tests, stage, approve, prod, fix. Labels can be longer than the ids." Models like to use the label as the id, then a question mark or a slash breaks the parse. Asking for short ids up front saves the fix pass.

A prompt I would send back

Last week someone on my team pasted this into the generator:

"Make a diagram of our deploy so people get it."

I would send that back before it ever hit the model. It doesn't name a type. It doesn't name a system. "Our deploy" could be a mobile release, a database migration, or a Friday script nobody wants to own. "So people get it" is a wish about the audience, and the model can't see your audience. It will guess a happy path and decorate it.

Here's what that kind of prompt tends to return. I didn't even have to generate it to predict the boxes. Slack, a ticket, a rollback service, and a straight line to production with no failed test.

flowchart LR
    begin[Deploy] --> notify[Notify Slack]
    begin --> ticket[Open a ticket]
    begin --> tests[Run tests]
    tests --> prod[Production]
    tests --> rollback[Rollback service]

Both outcomes of the test step fall downward into more systems, and neither edge says yes or no. Production is reachable even when the tests are just a sibling, because nothing in the prompt made tests a gate. The rollback service sounds responsible. We don't have one. The chart invented an owner.

That's the concrete failure. The file parses. The review is still wrong. If you accept it because the preview looks finished, you've documented a deploy you don't run. I've done that. I merged a chart with a "security scan" diamond that no job in the pipeline actually ran, and a new hire asked who owned the scan. Nobody. The box was a compliment the model paid to the word deploy.

A second failure mode is syntax, and it's cheaper to see. The model writes Call API (v2) without quotes, or it names a node end, which closes a subgraph and eats the rest of the file. People blame the layout. The source closed itself. The flowchart syntax page is where those shape rules live. I'm not going to restate the whole page here. I am going to say: if your label has parentheses, the prompt should demand quotes, and if a step is called "end," the id must not be the word end.

The same deploy, written so the draft can be wrong in only one place

This is the prompt I actually want for that pipeline. It's longer. Length isn't the goal. Constraints are.

"Flowchart, top down. Ids: commit, ci, tests, stage, approve, prod, fix. Labels: Commit, CI, Tests passed?, Staging, Reviewer approved?, Production, Fix the branch. Edges: Commit to CI. CI to the tests decision. If tests passed, Staging. If not, Fix the branch, and Fix the branch returns to Commit. Staging to the reviewer decision. If approved, Production. If not, Fix the branch. Label the decision edges Yes and No. Do not add Slack, tickets, rollback, scanning, or any node that is not in the id list. Quote any label that contains a question mark."

Read it once as a checklist before you generate. Type is there. Direction is there. Ids and labels are separated. Both decisions have two named outcomes. The return edge has a target. The exclusion list is specific. There's no "and anything else a reader might need." That clause is how the Slack box sneaks back.

A tighter prompt can still be wrong because you were wrong. If production really requires the reviewer before staging, this spec is a lie and the diagram will be a faithful lie. Fix the sentence. Don't ask the model to "make it more accurate" without saying which arrow moved. It will move a different one.

The prompt guide covers the patterns I reuse: a spec, a closed vocabulary, a revision that protects node ids, and a source dump with a mapping rule. This post is the practical lesson for one chart. That guide is the catalog. I send people to the guide when they already agree the prompt is a spec and they want the SQL and bullet-list versions. I keep them here when they still think "diagram the deploy" is a prompt.

What that spec should draw

If the generator follows the spec, you get this. If it adds a box, delete the box. Don't buy a third draft to remove a line you can erase.

flowchart TD
    commit[Commit] --> ci[CI]
    ci --> tests{"Tests passed?"}
    tests -->|Yes| stage[Staging]
    tests -->|No| fix[Fix the branch]
    fix --> commit
    stage --> approve{"Reviewer approved?"}
    approve -->|Yes| prod[Production]
    approve -->|No| fix

Commit goes to CI, CI goes to a real question, and the No path is a loop back to the branch rather than a new product called Rollback. Staging is not production. The reviewer is a second diamond, not a caption on the first one. I can trace Yes/Yes to Production with a finger. That's the test I use in review. If I have to narrate the chart out loud to know whether a failed test ships, the chart failed.

Look at the return from fix to commit. Some people want the fix to return to CI only, on the theory that the commit already happened. Say that in the prompt if it's true: "Fix the branch returns to CI, not to Commit." I left the return on Commit because in our shop the fix is a new commit. Your shop may differ. The diagram can't settle an argument you haven't had.

The flowchart generator is the page I open for this shape, because the surrounding notes are about decisions and not about sequence lifelines. A sequence prompt for the same deploy would name participants and replies. If you wanted "CI calls the test runner and the runner returns a status," you asked for a conversation and then complained that you got boxes. Pick the type in the first line so that complaint can't happen.

The five uses don't come back in the morning

Free AI on MermaidViewer is five uses total. Generate, edit, and fix all spend from that pile. I have watched someone burn four of them on "make it cleaner," "add more detail," "make it pop," and "try again." The fifth use finally named the nodes. They could have started there.

The counter is not five a day. It is five. An anonymous session and a free account share that kind of lifetime budget, and retrying from another browser is a worse plan than writing a better sentence. I won't pretend the counter is a suggestion. Treat use number one as the one that has to land.

A use is worth it when the diagram doesn't exist yet and the prompt is already a spec. A use is a waste when you're renaming Production to Prod, flipping one edge, or deleting Slack. Those are edits. The editor does them without spending a generation. Live preview is the point. You change a label, you see the diamond move, you keep going.

Edit and fix are real features, and they're the right spend when the draft is structurally close but the source is cursed. "Keep every node id. Add a No edge from approve to fix. Do not add services. Do not restyle." That's an edit prompt. "This failed to parse, quote the labels that contain parentheses, and do not rename ids" is a fix prompt. "Make it better" is how you shuffle a chart you already reviewed.

If you outgrow five uses, the paid line is more AI, not a different diagram language. Starter is $6.99 a month. Pro is $11.99 a month. I'm not going to dress that up. Hand editing stays available after the five are gone. I still edit by hand when the change is one arrow, even on a paid plan, because a prompt is a worse diff than a line change.

When the draft is one typo away from done

I stop prompting when the remaining problems are local.

A label like API (v2) needs quotes: api["API (v2)"]. Parentheses in an unquoted label are a classic parse break, and the preview goes blank, and someone assumes the whole chart is illegal. Quote the label. Keep the id boring.

A node id of end is worse. That word closes a subgraph. The rest of the file vanishes. If the last step is called End of deploy, the id can be finish and the label can say End. Say that in the prompt if your process uses the word. Otherwise you'll debug a missing tail for twenty minutes and blame the theme.

Both edges of a diamond labeled Yes is a logic bug the parser will not catch. I look for it on every generated flowchart. The model likes agreement. Your policy is made of disagreement. If the No path is missing, the diamond is decoration and you should delete it or name the other outcome.

Extra nodes are the other silent bug. Read the draft against the id list, not against your feelings about the picture. If notify isn't in the list, it's wrong even when the box is pretty. Pretty is how bad docs survive review.

The visual editor is the right next read if you want to drag a node after the source is valid. Dragging is fine once the text means the right thing. Dragging a fictional Slack box into a nicer position does not make the Slack box true. The draw overview is the broader "you're looking at a canvas" piece. Stay on this page until the prompt itself is honest.

Hand the picture to someone who wasn't in the room

I don't trust my own reading of a chart I just prompted. I wrote the spec, so I see the spec. A teammate sees the arrows. Ask them which path ships to production when tests fail. If they hesitate, the labels are doing too much work or the return edge is aimed at the wrong id.

Samples help when you're stuck on tone. The diagram examples collection is a pile of finished pictures, which is useful when you need to see what "short labels" look like and useless when you paste one and hope it matches your deploy. Examples are not your pipeline. The broader diagram guide is where I'd send a teammate who hasn't chosen flowchart versus sequence yet. Choosing late is how you get a beautiful chart of the wrong question.

My opinion, after too many of these reviews: the model is a fast typist with no stake in your on-call rotation. It will add a rollback service because rollback is a word that hangs around deploy. You have the stake. Put the closed list in the prompt, generate once, and delete anything that isn't on the list. If the first draft's only crime is an extra box, you won. If the first draft is a different diagram type, the prompt failed and the use was the tuition.

When the sentence is specific enough that you could sketch the boxes on paper, put it in the AI diagram generator and then change the one arrow it still gets wrong.