The map you didn't draw

What you thought the work looked like, and the work that was actually done — drawn as a branch history of goals, strategies, commands, and queries.

Read it like a Git log: time runs down the page, each strategy works on its own branch, and branches merge back when the map is revised. A ring around a node means you defined it. No ring means the agent found it along the way. Tap any node to see what's inside it.

0nodes
0defined by you
0obstacles found
0dead ends

An illustrative sailing-mod run, not your actual log. The shape is the point.

Symbols

How to read one command

Every command node hides the whole Dizzy chain. Tap one and you'll see it unpacked:

c → D → E → J → Mcommand, procedure, events, projection, model
y = Q(q, M) ⊖ ŷthe query node that follows it

A green query node means the observation matched the expectation. A red one is a residual, and it's almost always followed by an obstacle and a new goal with a qualifier: avoid, maintain, or achieve.

What the comparison shows

Switch between the two views. The plan is a clean tree: one fundamental goal, two strategies, three objectives, three commands. The work is about three times larger. Almost all of the growth follows one pattern: a query fails, an obstacle gets named, and a new goal appears to route around it. The agent ran that pattern over and over without stopping to ask.

Gyou ⊂ Gdone
gap = Gdone ∖ Gyouevery un-ringed node

From the outside, the residual at the end is zero: everything works. So by the loop's own rules, nothing tells you your map is out of date. That's the trap.

Which un-ringed nodes matter

New strategiesA whole branch you didn't plan, like multiplayer sync. These change what the product is. You need to know every one.
New goals with qualifiers"Avoid storms over land," "maintain vanilla boats." Each is a constraint now baked into the code — the things that surprise you six months later.
Dead endsBranches that never merged. Cheap to skip, but their obstacles explain why the surviving design looks the way it does.
Commands and passing queriesThe bulk of the history. Usually safe to trust once you understand the goals above them.

Why the 800-line log doesn't close it

The log is this graph with the lanes, rings, and edges removed: every decision at the same depth, in the order it was made, with the same weight. The graph above is the same information with its shape put back — which is the part you need to understand the software.

What might close it

  1. Log decisions as typed events. Goal added, strategy added, obstacle named, query passed or failed. Then the graph above is just a projection of the log.
  2. Every node names its parent. Anything that can't point back to a ringed node is unplanned scope, and floats to the top of the review.
  3. Review top-down. New strategies first, then qualified goals, then dead ends. Stop when the rest stops surprising you.
  4. Round-trip the human. For each un-ringed node, the agent predicts whether you'd have approved it and how sure it is. You answer a random sample. Your disagreement rate estimates how much of the graph you still need to read — and the nodes it was least sure about are the ones to ask you first next time.

That last one turns "do I understand the software?" into a measurement. If the agent predicts your answers well, the gap is small even though the graph is big.

Open questions