Design Graph

Design Graph — The Artifact

A Design Graph is the annotated call graph of a concrete problem. It is what you produce when you apply Design Thinking (see the design-method skill) to something, and it is written in Graph Protocol notation (see the graph-protocol skill).

Nodes are functions. Edges are data flow. The annotations answer, for every node: what flows through it (A), how many times it runs (cardinality), where and how it can fail (E), and what it needs to exist (R) — plus the global concerns: trust boundaries, behavior layers, resource scope, and test layers.

A Design Graph is not documentation written after the fact. It is drawn before implementation (planning), reconstructed from implementation (review), and compared against implementation (verdict). The graph is the contract; the code is one instantiation of it. Hard gate: when a turn will produce code or file edits, the graph comes first — render it (and any clarifying questions), get the user's approval, and only then write code that matches it.

What a complete Design Graph contains

PROBLEM: <one line>

X → DesignGraph<A, E, R>
│              │   │  │  │
│              │   │  │  └─ R: what each node needs      (§5)
│              │   │  └──── E: where the graph breaks    (§4)
│              │   └─────── A: what flows through nodes  (§2)
│              │
│              └─ nodes = functions, edges = data flow
│
└─ the problem

SHAPES:  …        every noun the graph needs
GRAPH:  …        ascii call graph with inline R:/E:/🔒/(n) annotations
CARDINALITY: …   every node marked (1) (N) or (T)
BOUNDARIES: …    every unknown → trusted crossing
BEHAVIOR: …      every orthogonal layer and what it wraps
SCOPE: …         every resource with acquire@x → release@x
TEST LAYERS: …   the R tests provide — same GRAPH, zero code change
VERDICT: …       code matches graph? A and E structurally separated?

Completeness checklist

A Design Graph is complete when all of the following hold:

• Every node has a cardinality marker — (1), (N), or (T).
• Every node lists its R: — even if R: none (that is a feature: the node is runnable standalone).
• Every edge crossing a trust boundary is marked 🔒 unknown → trusted.
• Every failure mode has a strategy — ⟳retry, ↯escape(alt), or ☠die. No unmarked breaks, no silent swallowing.
• Every layer scopes its E before handing off (inner errors translated, never leaked).
• Every resource has an acquire point and a structural release point.
• BEHAVIOR lists only layers that can be removed without touching the happy path.
• TEST LAYERS shows a full R substitution — if it can't, the graph has hidden dependencies.
• VERDICT explicitly answers whether code and graph match, and names the mismatches.

The three uses

1. Plan (/cg-plan)

Draw the graph first. Code is written only after the VERDICT question — "does my code match this?" — has a target to be checked against. If a code suggestion contradicts the graph, fix the graph or fix the code; never let them drift silently.

2. Extract (/cg)

Given existing code, reconstruct the graph the code actually implements — not the one the author intended. The reconstructed graph is the ground truth for review and refactoring.

3. Review (/cg-review)

Render the implemented graph, then diff it against the intended graph (or against the method's completeness checklist when no intended graph exists). Every mismatch is a finding, grouped by § number. The review ends with a VERDICT line.

Worked example

See the end of the graph-protocol skill for a complete, non-TS worked example (a resumable URL-sync CLI in Python) with all sections filled.