@widnyana/design-thinking 0.0.1

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2025 r17x — original Design Thinking concepts, methodology, and
+the Effect-TS instantiation (https://gist.github.com/r17x/90eb2f7be93932b5693753aedb09c01a)
+
+Copyright (c) 2026 Widnyana Putra — pi package adaptation: generalization of the
+method to a stack-agnostic form, the Design Graph artifact spec, the Graph
+Protocol notation, the pi extension, and the prompt templates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+Attribution: the underlying design methodology originates from r17x. The
+generalized method, Graph Protocol, and pi packaging in this repository are a
+derived work.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# design-thinking — a pi package
+
+AI coding agents ship code before asking what breaks. This extension flips the
+order: with `/dt` active, [pi](https://pi.dev) draws the call graph first —
+nodes are functions, edges are data flow, every failure path is named — then
+writes code that *is* the graph. Plans, reviews, and refactors render in a
+fixed, mechanically checkable notation (Graph Protocol) that looks the same in
+Go, Rust, Python, or TypeScript.
+
+Method by [r17x](https://github.com/r17x) ([Design Thinking
+gist](https://gist.github.com/r17x/90eb2f7be93932b5693753aedb09c01a),
+originally Effect-TS), generalized into this stack-agnostic pi package.
+Licensed MIT — see [LICENSE](LICENSE).
+
+## Install
+
+```bash
+# from npm
+pi install npm:@widnyana/design-thinking
+
+# pinned version
+pi install npm:@widnyana/design-thinking@0.0.1
+
+# from a local checkout of this repo
+pi install /absolute/path/to/pi-packages/design-thinking
+
+# try without installing
+pi -e npm:@widnyana/design-thinking
+pi -e ./pi-packages/design-thinking
+```
+
+> The `npm:` prefix is required — a bare name is parsed by pi as a local path.
+
+## Usage
+
+| Command | What it does |
+|---|---|
+| `/dt` | Toggle Design Thinking mode. While on, plans and reviews render as Design Graphs. Persists across restarts. |
+| `/dt on\|off\|status` | Set or query the mode explicitly. |
+| `/dt <prompt>` | Turn the mode **on** (never off), then run `<prompt>` under it — graph and clarifying questions first, implementation after your go-ahead. |
+| `/cg <module \| task>` | Generate a call graph: extract the graph existing code implements, or sketch one for a task. |
+| `/cg-plan <task>` | Design before code — full Design Graph, then implement to match it. |
+| `/cg-review [file\|module\|diff]` | Reconstruct the implemented graph, diff it against the method's checklist, end with a VERDICT. |
+| `/cg-map <language\|framework>` | Map the Protocol vocabulary onto a stack's idioms (Result vs exceptions, RAII vs defer). |
+
+## A real-world walkthrough
+
+Task: *add rate limiting to an Express API.* One design pass, end to end:
+
+```
+> /dt                                        # mode on — graph-first rules injected
+
+> /cg-plan add per-user rate limiting to the API
+    → agent sketches a DesignGraph first (SHAPES, GRAPH, E, boundaries),
+      then implements code that matches it
+
+> /cg-map nodejs                             # optional: before planning, when the
+    → maps ⟳↯☠🔒 onto express idioms         #   stack's vocabulary is unclear
+      (middleware = boundary, AbortError = ↯escape)
+
+> git diff → review it with:
+> /cg-review src/middleware/ratelimit.ts
+    → extracts the graph the code ACTUALLY implements, diffs it against
+      the planned one, findings grouped by § number, ends with VERDICT
+
+> /dt off                                    # done — back to normal mode
+```
+
+The cycle:
+
+```mermaid
+flowchart LR
+    A["/dt on"] --> B{"stack idioms<br/>clear?"}
+    B -- no --> M["/cg-map nodejs"]
+    B -- yes --> P
+    M --> P["/cg-plan <task>"]
+    P --> C[implement] --> R["/cg-review <file>"] --> O["/dt off"]
+```
+
+Skills (`graph-protocol`, `design-method`, `design-graph`) are loaded by the
+agent on demand mid-turn — you never invoke them directly; the `/cg*` prompts
+and `/dt` mode tell the model when to reach for them.

package/extensions/design-thinking.ts

@@ -0,0 +1,166 @@
+/**
+ * Design Thinking — pi extension
+ *
+ * Adopts the three pillars:
+ *   - Design Thinking : the mindset (§1–§10 pipeline, problem-first)
+ *   - Design Graph    : the artifact (annotated call graph of a concrete problem)
+ *   - Graph Protocol  : the notation spec (fixed sections, fixed markers)
+ *
+ * When /dt mode is active, every turn appends a compact distilled block to the
+ * system prompt so design/plan/review answers render as Design Graphs in
+ * Graph Protocol form. Full specs live in the package's references/ directory,
+ * loaded on demand — not inlined here, to keep the injected prompt small.
+ *
+ * Commands:
+ *   /dt            toggle Design Thinking mode
+ *   /dt on|off     set explicitly
+ *   /dt status     show current state
+ *   /dt <prompt>   turn mode ON (never off), then run <prompt> as a user
+ *                  message — graph + clarifying questions before implementation
+ *
+ * Stack-agnostic: no language detection, no auto-enable. Adapt the vocabulary
+ * to whatever stack the project uses; never the discipline.
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const STATE_TYPE = "design-thinking-state";
+
+/**
+ * Absolute path to the shipped references/ directory, resolved from this
+ * file's own location (§6 boundary: import.meta.url → fs path). Works from
+ * a repo checkout and from an npm install — e.g.
+ * ~/.pi/agent/npm/node_modules/@widnyana/design-thinking/references — so
+ * the model can actually read the full specs in /dt mode.
+ */
+const REF_DIR = path.resolve(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"references",
+);
+
+/** Compact distilled prompt block injected while active (~33 lines). */
+const DISTILLED = `
+DESIGN THINKING MODE — active.
+Read the problem. Draw the data flow as a call graph. Write code that IS the graph.
+
+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
+
+Pipeline: shapes → graph(A) → cardinality → E(⟳retry ↯escape ☠die) → R →
+🔒 parse at boundaries → ⛈ orthogonal behavior → scope → test-R → verdict.
+
+Rules:
+- Design, plan, and review answers must render a Design Graph in Graph Protocol
+  form — fixed sections: PROBLEM, SHAPES, GRAPH, CARDINALITY, BOUNDARIES,
+  BEHAVIOR, SCOPE, TEST LAYERS, VERDICT.
+- The happy path (A) stays readable; failure handling lives at defined join points.
+- Each layer scopes its own E; inner errors never leak through.
+- If the code doesn't match the call graph, the implementation is wrong.
+- For build/fix/refactor tasks: present the Design Graph and any clarifying
+  questions FIRST; implement only after the user approves the design.
+- Adapt vocabulary to the current language/stack; never the discipline.
+
+Full specs — read these when a section needs detail:
+- ${REF_DIR}/protocol.md      (Graph Protocol: notation spec + worked example)
+- ${REF_DIR}/method.md        (the §1–§10 method, generalized)
+- ${REF_DIR}/design-graph.md  (the artifact spec + completeness checklist)
+`.trim();
+
+interface DtState {
+	enabled: boolean;
+}
+
+export default function designThinkingExtension(pi: ExtensionAPI) {
+	let enabled = false;
+
+	function applyStatus(ctx: ExtensionContext) {
+		ctx.ui.setStatus(
+			"design-thinking",
+			enabled ? "design-thinking: on" : undefined,
+		);
+	}
+
+	function persist() {
+		pi.appendEntry<DtState>(STATE_TYPE, { enabled });
+	}
+
+	function restore(ctx: ExtensionContext) {
+		const branch = ctx.sessionManager.getBranch();
+		let restored: boolean | undefined;
+		for (const entry of branch) {
+			if (entry.type === "custom" && entry.customType === STATE_TYPE) {
+				const data = entry.data as DtState | undefined;
+				if (data && typeof data.enabled === "boolean") {
+					restored = data.enabled;
+				}
+			}
+		}
+		if (restored !== undefined) {
+			enabled = restored;
+		}
+	}
+
+	// Restore toggle state when a session starts, loads, or reloads.
+	pi.on("session_start", async (_event, ctx) => {
+		restore(ctx);
+		applyStatus(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		ctx.ui.setStatus("design-thinking", undefined);
+	});
+
+	// /dt — the Design Thinking tool. Toggles mode, or /dt on|off|status.
+	pi.registerCommand("dt", {
+		description: "Design Thinking mode: /dt toggles, on|off|status set/query, anything else runs as a prompt with mode on",
+		handler: async (args, ctx) => {
+			const arg = (args ?? "").trim();
+			const lower = arg.toLowerCase();
+
+			if (lower === "status") {
+				ctx.ui.notify(`Design Thinking mode: ${enabled ? "on" : "off"}`, "info");
+				return;
+			}
+
+			// "on"/"off" set explicitly; anything else is a prompt to run in this
+			// mode and always turns the mode ON (never toggles it off); bare /dt toggles.
+			const prompt = /^(on|off|status)$/.test(lower) ? "" : arg;
+			enabled = lower === "on" || prompt ? true : lower === "off" ? false : !enabled;
+			persist();
+			applyStatus(ctx);
+			ctx.ui.notify(
+				enabled
+					? "Design Thinking ON — plans and reviews will render as Design Graphs (Graph Protocol)"
+					: "Design Thinking OFF",
+				"info",
+			);
+
+			if (prompt) {
+				// deliverAs "steer": sends immediately when idle, queues mid-stream.
+				await pi.sendUserMessage(
+					`${prompt}\n\n(Design Thinking is ON: before implementing, present the Design Graph (Graph Protocol) and any clarifying questions, then wait for my go-ahead.)`,
+					{ deliverAs: "steer" },
+				);
+			}
+		},
+	});
+
+	// While active, append the distilled block to the system prompt every turn.
+	pi.on("before_agent_start", async (event) => {
+		if (!enabled) return undefined;
+		return {
+			systemPrompt: event.systemPrompt + "\n\n" + DISTILLED + "\n",
+		};
+	});
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@widnyana/design-thinking",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Design Thinking · Design Graph · Graph Protocol — a stack-agnostic design methodology for pi. Turns every plan, review, and refactor into an annotated call graph. Method originally by r17x; generalized to a pi package by widnyana.",
+  "author": {
+    "name": "Widnyana Putra",
+    "url": "https://github.com/widnyana"
+  },
+  "contributors": [
+    {
+      "name": "r17x",
+      "url": "https://github.com/r17x",
+      "note": "Original Design Thinking concepts and methodology"
+    }
+  ],
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "prompts",
+    "skills",
+    "references",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/widnyana/eyay-toolkits.git",
+    "directory": "pi-packages/design-thinking"
+  },
+  "keywords": [
+    "pi-package",
+    "design",
+    "architecture",
+    "methodology",
+    "call-graph"
+  ],
+  "pi": {
+    "extensions": ["./extensions"],
+    "prompts": ["./prompts"],
+    "skills": ["./skills"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}

package/prompts/cg-map.md

@@ -0,0 +1,41 @@
+---
+description: Map the Graph Protocol vocabulary onto a language/framework's concrete idioms
+argument-hint: "<language | framework>"
+---
+Map the Design Graph method onto: $@
+
+Produce a vocabulary mapping so the method's three channels (A, E, R) and its
+markers have concrete, idiomatic counterparts in the target stack. Output a
+mapping table followed by a small worked mini-graph in Graph Protocol format.
+
+## Mapping table (required rows)
+
+| Protocol concept | Question to answer for the target stack |
+|---|---|
+| **A** — happy path | Where does the straight-line happy path live? (main fn, do-block, generator pipeline, SQL CTE chain…) |
+| **E** — failure carrying | How are failures values vs control flow? (Result/Either, checked exceptions, error returns, panics+recover, throw at layer joins…) |
+| **⟳ retry** | Idiomatic retry: library, decorator, middleware, policy object? |
+| **↯ escape** | Idiomatic fallback: default value, cache read, alternative path? |
+| **☠ die** | What counts as a defect? (assert, panic, raise RuntimeError, process abort…) |
+| **R** — dependencies | How are deps declared and provided? (constructor injection, traits, typeclasses, DI container, closure capture, context.Context…) |
+| **🔒 boundary parse** | Where do unknown→trusted conversions live? (schema lib, DTO layer, parsing constructors, guards…) |
+| **(1) (N) (T)** | One-shot vs stream vs time-bounded: iterators, channels, observables, TTL caches… |
+| **⛈ behavior layers** | Middleware/decorator/aspect story of the stack |
+| **Scope** | RAII, defer, context managers, try-with-resources, drop… |
+| **A/E structural split** | How the stack separates happy path from failure join points (pipe, middleware stack, Result chain, try/catch at edges) |
+| **E layer scoping** | How each layer translates inner errors into its own error type before handing off |
+
+## Rules
+
+- Be concrete: name actual libraries, patterns, and syntax idioms of the stack.
+- If the stack lacks a native counterpart for a concept, say so and name the
+  closest convention (and its cost).
+- After the table, render a mini Design Graph (PROBLEM → header tree → GRAPH →
+  VERDICT only) for a small example task in this stack, using the mapped
+  vocabulary — proving the mapping works end to end.
+- This mapping is a companion artifact: once produced, refer to it in later
+  `/cg-plan` and `/cg-review` runs in the same stack.
+
+Full specs load as skills in the `design-thinking` pi package:
+`/skill:graph-protocol` (notation), `/skill:design-method` (the method),
+`/skill:design-graph` (artifact).

package/prompts/cg-plan.md

@@ -0,0 +1,65 @@
+---
+description: Design before code — produce a complete Design Graph for a task, then implement to match it
+argument-hint: "<task description>"
+---
+Task: $@
+
+Design it before writing any code. Apply the full Design Thinking pipeline and
+produce a complete Design Graph in Graph Protocol format. Code suggestions must
+match the graph — if a snippet contradicts the graph, fix the graph or fix the
+code, never let them drift silently.
+
+## Graph Protocol — quick reference
+
+Emit ALL sections below, in this order, with these markers:
+
+```
+PROBLEM: <one line — if it doesn't fit, the problem is not understood; refine first>
+
+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:  records · IDs · state variants · named errors
+GRAPH:   ascii call graph, annotated inline:
+         R: deps · E: err ⟳retry[×n] → ↯escape(alt) | ☠die · 🔒 unknown→trusted
+CARDINALITY: node (1) one-shot · (N) many over time · (T) time-bounded
+BOUNDARIES:  every untrusted→trusted crossing (parse, don't validate)
+BEHAVIOR:    orthogonal layers (retry, cache, logging) that wrap without changing the graph
+SCOPE:       resources: acquire@x → release@x (structural, not convention)
+TEST LAYERS: the R tests provide — same GRAPH, zero code change
+VERDICT:     the target structure the implementation must satisfy
+```
+
+## Pipeline to follow
+
+1. **§1 Shapes** — the domain nouns, named before any graph is drawn.
+2. **§2 A** — happy path as a call graph, drawn first.
+3. **§3 Cardinality** — one-shot `(1)`, many `(N)`, time-bounded `(T)` per node.
+4. **§4 E** — every break point gets one of: `⟳retry`, `↯escape(alt)`, `☠die`.
+5. **§5 R** — every node declares its requirements; provided at the composition root.
+6. **§6 Boundary** — parse `unknown → trusted` at edges only; trust inside.
+7. **§7 Behavior** — cross-cutting concerns wrap nodes orthogonally.
+8. **§8 Scope** — acquire/release structurally bound (RAII / defer / context managers).
+9. **§9 Test** — same graph runs with test R; if it can't, hidden deps exist.
+10. **§10 Structure** — happy path body = A only; failure handling at defined
+    join points = E. Divergent strategies (per-fork failure semantics) are the
+    one exception — mark them.
+
+## Output contract
+
+- Design Graph first (all Protocol sections), then the implementation.
+- Each layer scopes its own E before handing off; inner errors never leak.
+- Adapt vocabulary to the project's language/stack — never the discipline.
+- The VERDICT section states the structural invariants the code must satisfy so
+  the graph can later be re-checked in review (`/cg-review`).
+
+Full specs load as skills in the `design-thinking` pi package:
+`/skill:graph-protocol` (notation), `/skill:design-method` (the method),
+`/skill:design-graph` (artifact).

package/prompts/cg-review.md

@@ -0,0 +1,69 @@
+---
+description: Review code against its call graph — reconstruct the implemented Design Graph and diff it
+argument-hint: "[file | module | diff, default: current diff]"
+---
+Review target: ${@:-the current uncommitted diff (git diff)}
+
+Reconstruct the Design Graph the code ACTUALLY implements — not the one the
+author intended. Then diff it against the method's completeness checklist.
+Every mismatch is a finding.
+
+## Graph Protocol — quick reference
+
+Emit ALL sections below, in this order, with these markers:
+
+```
+PROBLEM: <one line — what this code does, as implemented>
+
+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:  records · IDs · state variants · named errors (as actually present)
+GRAPH:   ascii call graph of the implemented code, annotated inline:
+         R: deps · E: err ⟳retry[×n] → ↯escape(alt) | ☠die · 🔒 unknown→trusted
+CARDINALITY: node (1) one-shot · (N) many over time · (T) time-bounded
+BOUNDARIES:  every untrusted→trusted crossing (parse, don't validate)
+BEHAVIOR:    orthogonal layers that wrap without changing the graph
+SCOPE:       resources: acquire@x → release@x (structural, not convention)
+TEST LAYERS: can this graph run with substituted R? if not — hidden deps
+VERDICT:     <matches | mismatches listed by § number>
+```
+
+## Findings checklist (group findings by § number)
+
+- **§1 Shapes** — unnamed errors (stringly-typed failures), bare-string IDs,
+  missing state variants.
+- **§2 A** — happy path unreadable; error handling woven through it (A/E tangled).
+- **§3 Cardinality** — `(N)` implemented as `(1)`, unbounded collection treated
+  as one-shot, missing cache/dedupe for `(T)`.
+- **§4 E** — unmarked breaks, silent swallowing, `☠die` used for domain errors,
+  retry on non-transient failures.
+- **§5 R** — hidden dependencies, node constructs its own infrastructure,
+  world-mocking required to test one node.
+- **§6 Boundary** — validation scattered inside the graph instead of parsing at
+  edges, trusted shapes built from untrusted data without conversion.
+- **§7 Behavior** — retry/timeout/logging hard-coded into business logic
+  instead of wrapping orthogonally.
+- **§8 Scope** — resources released by convention or not at all; cleanup as TODO.
+- **§9 Test** — graph can't run with substituted R.
+- **§10 Structure** — per-layer E scoping violated (inner errors leak through);
+  divergent strategies not marked.
+
+## Output contract
+
+- Implemented graph first (all Protocol sections), then findings, then VERDICT.
+- VERDICT must be explicit: "code matches graph" or the mismatch list.
+- If an intended graph exists (e.g. from a prior `/cg-plan`), diff against it;
+  otherwise review against the checklist alone.
+- Severity: mark findings that will cause runtime failures vs structural debt.
+
+Full specs load as skills in the `design-thinking` pi package:
+`/skill:graph-protocol` (notation), `/skill:design-method` (the method),
+`/skill:design-graph` (artifact).

package/prompts/cg.md

@@ -0,0 +1,50 @@
+---
+description: Generate a call graph of a module or task in Graph Protocol format
+argument-hint: "<module | task>"
+---
+Extract (if target is existing code) or sketch (if target is a task) the call graph for: $@
+
+Apply the Design Graph method — nodes are functions, edges are data flow.
+
+## Graph Protocol — quick reference
+
+Emit ALL sections below, in this order, with these markers:
+
+```
+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:  records · IDs · state variants · named errors
+GRAPH:   ascii call graph, annotated inline:
+         R: deps · E: err ⟳retry[×n] → ↯escape(alt) | ☠die · 🔒 unknown→trusted
+CARDINALITY: node (1) one-shot · (N) many over time · (T) time-bounded
+BOUNDARIES:  every untrusted→trusted crossing (parse, don't validate)
+BEHAVIOR:    orthogonal layers (retry, cache, logging) that wrap without changing the graph
+SCOPE:       resources: acquire@x → release@x (structural, not convention)
+TEST LAYERS: the R tests provide — same GRAPH, zero code change
+VERDICT:     code matches graph? happy path free of error handling? E fully enumerated?
+```
+
+## Rules
+
+- The graph is the ground truth. For existing code, reconstruct the graph the
+  code ACTUALLY implements — not what the author intended.
+- Every node gets cardinality + `R:`. Every failure gets `⟳`, `↯`, or `☠`.
+  Every trust crossing gets `🔒`.
+- Adapt vocabulary to the target language/stack (exceptions vs Result types,
+  RAII vs context managers, etc.) — never the discipline.
+- If you find nodes that violate the method (tangled happy path, unscoped
+  resources, hidden dependencies), list them under VERDICT, grouped by § number.
+
+If the full spec is needed, load the skills shipped in the `design-thinking`
+pi package: `/skill:graph-protocol` (notation) and `/skill:design-method`
+(the method).

package/references/design-graph.md

@@ -0,0 +1,88 @@
+# 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](method.md) to something, and
+it is written in [Graph Protocol](protocol.md) notation.
+
+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.
+
+---
+
+## 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 [protocol.md](protocol.md) for a complete, non-TS worked
+example (a resumable URL-sync CLI in Python) with all sections filled.