design-thinking — a pi package

AI coding agents ship code before asking what breaks. This extension flips the order: with /dt active, pi 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 that looks the same in Go, Rust, Python, or TypeScript.

Method by r17x (Design Thinking gist, originally Effect-TS), generalized into this stack-agnostic pi package. Licensed MIT — see LICENSE.

Why

A prose plan doesn't survive contact with review. An agent proposes "add rate limiting, handle errors," the plan reads fine, and the diff either matches it or it doesn't — prose gives no way to check which. Two failure modes follow from that: the agent picks an unstated failure path (swallow the error, retry silently, drop the request) nobody agreed to, or the reviewer approves a plan that was never specific enough to catch the mismatch once the code lands.

The graph replaces the prose plan with something that can be diffed. Nodes are functions, edges are data and error/escape paths, boundaries are named — fixed before code exists. /cg-review then reconstructs the graph the code actually implements and diffs it against the one that was planned, finding by finding, ending in a VERDICT. The notation is the same shape in Go, Rust, Python, or TypeScript, so the check doesn't depend on the stack.

Skip it for a one-line fix — prose is fine there. Reach for /dt when the change has a failure path worth agreeing on before it's written.

Guides, tips, and troubleshooting: GUIDE.md.

Three methods, one shape

From r17x's gist: the same three-channel discipline, applied to three materials.

Plus r17x's Meta Research Prompt Generator (from the gist comments) as /research-prompt: one topic line in, one research coordination prompt file and the command to run it out. Its waves of research, review, index, and synthesis agents each get an AGENT SUBGRAPH. All its files live under ./research/ in the directory where you run it:

./research/
  projects/<NAME>/.<NAME>.research.prompt   the coordinator prompt
  projects/<NAME>/RESEARCH.md               the final document
  scratch/n1_<slug>.md, r1_review_<slug>.md per-node working files
  ref/INDEX.md, ref/<repo>/, ref/<file>     cloned repos and downloaded specs

Add research/scratch/ and research/ref/ to .gitignore if you do not want them committed.

Install

# from npm
pi install npm:@widnyana/design-thinking

# via OMP
omp install npm:@widnyana/design-thinking

# pinned version
pi install npm:@widnyana/design-thinking@0.1.0

# from a local checkout of this repo
pi install /absolute/path/to/pi-packages/design-thinking

# via the omp marketplace
omp plugin marketplace add widnyana/eyay-toolkits
omp plugin install design-thinking@eyay-toolkits

# 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

With /dt on, the file /research-prompt writes goes through the approval gate like any other edit: approve it in the review dialog, or run /dt off first.

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 the graph 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:

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 (design-thinking, design-graph, graph-protocol) 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.