The First Diagram Is Usually a Liar
A writing-led field guide for diagrams that earn their words.
The project teaches the ROY method, the difference between a tidy lie and an honest diagram, and the value of structured disagreement when a visual model is still taking shape. The companion Writing is the public narrative. The tutorial is the practice surface. The repository keeps the receipts: prompts, Mermaid sources, rendered assets, specialist records, release notes, and the editorial cuts that show how the argument changed.
A tidy diagram can still be a tidy lie.
The first shape feels more certain than the idea.
A clean left-to-right flow can hide loops, forks, dead ends, ownership gaps, and unresolved decisions. The visual may be polished while the model is still guessing.
Explanation has a cost.
Every line, label, legend, and exception adds reading work. A diagram earns its space only when it removes more confusion than it creates.
Different tools answer different questions.
Architect, builder, editor, and critic are not interchangeable roles. Their outputs should remain comparable without pretending that their conditions were identical.
Revision is part of the evidence.
The V1 that looked plausible and the V2 that survived critique tell a more useful story together than either one can tell alone.
The Writing is the narrative. The tutorial is the rehearsal room.
Read the argument in full.
The companion page carries the long-form story, the field guide, the four heat pages, the V1 and V2 diagrams, the deck links, and the current v0.5 Council-Assisted Scoring update.
Test the method against your own thinking.
The companion repository contains the client-only React/Vite tutorial. It moves through Spot the Lie, Measure ROY, Draw the Truth, Use Disagreement, and Ship the Proof.
The surfaces are related, not duplicates. The Writing is the canonical public explanation. The application is an interactive teaching aid. The archive is the evidence boundary.
Five moves for an honest model.
Find the hidden claim.
Name what the diagram says, what it leaves out, and where its tidy path stops matching the work.
Count understanding against explanation.
Use ROY as a practical question: did the visual buy enough shared understanding to justify the reading cost?
Show the shape of the work.
Make forks, loops, revisions, dead ends, and unresolved decisions visible instead of smoothing them away.
Keep the council legible.
Compare outputs by round, role, prompt, and evidence. Core Five, Exhibition, Specialty, and Attempted entries do not become one leaderboard.
Put the source beside the picture.
Share the explanation, Mermaid source, rendered result, revision trail, and the limits of what was actually tested.
Receipts before rankings.
- 01
Governing brief archived
The ETCH-AI-SKETCH brief defines the experiment, the deliverables, and the comparison boundary.
- 02
Prompts, Mermaid, and renders archived
Eight prompts, V1 and V2 source relationships, rendered assets, and slide exports remain inspectable in the repository archive.
- 03
Specialty records archived
Notion and Replit are preserved as distinct conditions. The archive does not flatten tool, round, or role differences.
- 04
Council-Assisted Scoring current writing
The public Writing currently records the v0.5 scoring update. It is a documented method change, not proof of an objective winner.
The archive is source-safe and public. Private editorial workspaces may inform the project, but they are not linked from this public page.
The rules the project runs on.
Source before polish.
A beautiful render cannot outrank the source, the brief, or the evidence that produced it.
Comparison needs conditions.
Keep role, prompt, round, and specialty context attached to every result.
Disagreement is useful data.
Critique is not a defect to hide. It is where an attractive first answer can become a more honest model.
ROY is a heuristic.
Use it to ask better questions, not to manufacture a scientific score or a universal ranking.
Make the handoff survive.
Someone else should be able to find the source, understand the claim, and see what remains uncertain.
A field guide. Not a diagram factory.
- +A writing companion and interactive tutorial
- +A source-backed evidence archive
- +A method for making disagreement visible
- +A browser-only teaching surface
- −A general-purpose Mermaid editor
- −An AI diagram generator or model leaderboard
- −A backend, account system, or hosted database
- −Proof that the first diagram was the right one
It started as a diagramming shootout.
The project began with one brief sent through multiple tools and models. The interesting result was not that one output looked best. It was that the outputs exposed different instincts: architecture, narrative, pragmatism, restraint, code-first thinking, and the occasional polished lie.
The work then became a public experiment in revision. V1 and V2 are kept together. The article moved from prose to diagrams to audience scoring and then to Council-Assisted Scoring. The project page exists to connect those surfaces without pretending they are the same artifact.
Current public writing: v0.5, Council-Assisted Scoring. Current tutorial delivery: intended GitHub Pages route, not confirmed live at the time of this page build.