Unit 02.04: Drawing the graph before writing it

Twenty minutes with the graph as data catches design errors that cost hours once nodes exist.

State fields, nodes, edges, conditions

The design is four lists: what is in the state, what each node does to it, which edges exist, and the condition on each edge. Written as data it can be read in one screen.

The code shows a research-and-publish workflow in that form.

# The drawing, as data. Do this before any node body exists.
DESIGN = {
    "state": {"question": "str", "findings": "list", "draft": "str",
              "approved": "bool", "attempts": "int"},
    "nodes": {
        "research": "fills findings",
        "draft":    "fills draft from findings",
        "review":   "sets approved",
        "publish":  "side effect -- must run at most once",
    },
    "edges": [
        ("START", "research", "always"),
        ("research", "draft", "always"),
        ("draft", "review", "always"),
        ("review", "publish", "approved is True"),
        ("review", "draft", "approved is False and attempts < 3"),
        ("review", "END", "attempts >= 3"),
        ("publish", "END", "always"),
    ],
}

print("state fields:", ", ".join(DESIGN["state"]))
print()
for src, dst, when in DESIGN["edges"]:
    print(f"  {src:9} -> {dst:9} when {when}")

# Two things this catches before any code exists: `attempts` is needed or the
# revise loop never terminates, and `publish` has a side effect so the retry
# path must not be able to reach it twice.

Two problems are visible before any node body exists. attempts is in the state because the review -> draft edge is a cycle, and a cycle without a counter does not terminate. And publish is marked as having a side effect, which means the retry path must not be able to reach it twice.

Both of those are cheap to fix at this stage and expensive to discover later - the second one especially, because its symptom is a duplicate action in a downstream system rather than an error in your logs.

The mistake this prevents

The mistake is drawing boxes and arrows without the conditions. A diagram showing review -> draft and review -> publish looks complete and says nothing about when each fires, which is the part that has bugs. Write the condition on every edge.

Takeaway

Write the graph as data before writing nodes: state fields, nodes, edges, and the condition on each edge. The conditions are what reveal missing counters and unguarded side effects.

Mark complete