Diagram Truth
The workbench for turning a tidy first diagram into a more honest one.
Interactive tutorial and evidence archive. Step 3 observed September 29, 2026; full tutorial acceptance unverified.
Status and source
Availability: Published project page. Maturity: Interactive tutorial and evidence archive. Evidence: Source description only. Delivery: unknown. Source record (reviewed 2026-09-29).
About the project
The first shape is a claim. Make it answer for itself.
Diagram Truth is the interactive side of The First Diagram Is Usually a Liar. The article explains why tidy diagrams can mislead and how the ROY method tests whether a visual earns its reading cost. The browser tutorial lets you put that argument to work across five steps. Its third step, Draw the Truth, compares a neat first pass with a revision that shows doubt, exceptions, and return paths.
The application runs in your browser. The public repository preserves the tutorial source and the separate experiment archive.
Draw the truth, not the brochure.
Switch between the tidy V1 and the honest V2. The destination stays the same; V2 exposes the doubt, missing exception, and revision loops that the straight line concealed. Hide and reveal the return paths to see how much meaning the diagram was carrying.
These two states are teaching illustrations. They are distinct from the preserved V1 and V2 competition rounds. The workbench is not a live Mermaid parser or a general-purpose editor.
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.
Read the argument. Test it in the workbench.
Read the argument in full.
The companion page carries the complete Final Cut, connecting the experiment, Notion, Replit, visual consistency, and process knowledge into one argument. Its historical appendix retains the original V1 and V2 diagrams, deck, four heat guides, and publication records.
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 Writing holds the public explanation. Diagram Truth is the project doorway to the interactive tutorial. The archive keeps the source and evidence inspectable.
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 documented in v0.5
The Council's v0.5 scoring update remains a documented method change, not proof of an objective winner.
- 05
Process Knowledge current writing
The Final Cut follows BPMN for Mermaid into process capture, a shared narrative record, and the 15-skill BP-SKILL suite, then connects that work to reusable visual preferences and a bounded pilot.
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.
The Step 3 deep link opened the Draw the Truth workbench in a browser on September 29, 2026. That check does not certify every tutorial interaction or future GitHub Pages deployments.