@widnyana/design-thinking 0.0.1

package/skills/design-graph/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: design-graph
+description: >
+  Design Graph — the artifact: annotated call graph of a concrete problem;
+  nodes = functions, edges = data flow; every node annotated with A,
+  cardinality, E, R. Use when drawing a graph before writing code or
+  reconstructing and diffing one against existing code. Includes the
+  completeness checklist.
+---
+
+# 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](/skill:design-method) to
+something, and it is written in [Graph Protocol](/skill:graph-protocol) 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 [Graph Protocol](/skill:graph-protocol) for a complete, non-TS worked
+example (a resumable URL-sync CLI in Python) with all sections filled.

package/skills/design-method/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: design-method
+description: >
+  Design Thinking — the §1–§10 problem-first pipeline: shapes → graph(A) →
+  cardinality → break points (E: ⟳ ↯ ☠) → requirements (R) → boundaries →
+  behavior layers → scope → test layers → verdict. Stack-agnostic. Use when
+  planning, designing, or refactoring any feature or system.
+---
+
+# Design Thinking — The Method
+
+A stack-agnostic design methodology. Read the problem. Draw the data flow as a
+call graph (the **Design Graph**). Write code that IS the graph. If the code
+doesn't match the graph, something is wrong.
+
+The method is language-neutral. Where it says "Effect", "gen", or "pipe" in the
+Effect-TS appendix (`effect-ts.md`), substitute your stack's equivalent: Result
+types, exceptions at layer joins, middleware, RAII, constructor injection —
+whatever your language provides. The discipline never changes, only the vocabulary.
+
+Render every result in [Graph Protocol](/skill:graph-protocol) format.
+
+```
+X → DesignGraph<A, E, R>
+│              │   │  │  │
+│              │   │  │  └─ what each node needs     (§5)
+│              │   │  └──── where the graph breaks   (§4)
+│              │   └─────── what flows through nodes  (§2)
+│              │
+│              └─ nodes = functions, edges = data flow
+│
+└─ the problem: what you're trying to build
+
+§1  Shapes       the nouns: records, IDs, variants, errors
+§2  A            happy path as call graph
+§3  Cardinality  one-shot (1), many (N), or time-bounded (T)
+§4  E            break points: retry, escape, die
+§5  R            dependencies: compile-time or wiring-time proof
+§6  Boundary     parse: unknown → trusted at edges
+§7  Behavior     orthogonal layers wrap without changing the graph
+§8  Scope        acquire/release tied to lifecycle
+§9  Test         swap R, same graph shape
+§10 Structure    happy path = A, failure handling = E, never tangled
+```
+
+## 1. Name the shapes
+
+What are the things? Before drawing a graph, define the domain language.
+
+- **Records** — entities that flow through nodes. A User, a Product, an Order.
+- **IDs** — identity of things. Branded, constrained, never a bare string.
+- **Variants** — internal state transitions. A step is Continue or Finished.
+  A status is Pending, Active, or Cancelled.
+- **Errors** — named failure modes. Not strings. Structured, carrying context.
+
+These are the nouns. The graph is the verbs. You cannot draw the graph until
+you know what flows through it.
+
+→ *Protocol section: SHAPES.*
+
+## 2. Think A first
+
+Map the happy path as a call graph before writing any code.
+
+```
+F1(A) -> F2(A) -> F3(A)
+```
+
+What is the success data flow? What goes in, what comes out, what transforms
+happen in between? This graph IS your program structure. Draw it first. The
+code follows.
+
+→ *Protocol section: GRAPH (edges) + header tree (A).*
+
+## 3. One or many?
+
+Is each node one-shot or a flow?
+
+- **One value** — the node runs, produces A, done. `(1)`
+- **Many values over time** — the node emits A repeatedly: events,
+  subscriptions, paginated pulls, batches. `(N)`
+- **Time-bounded** — the result is valid for a window. Cache it. Deduplicate
+  concurrent lookups. `(T)`
+
+Same three channels (A, E, R) in all cases. Different cardinality. Mark it on
+the graph so the code matches.
+
+→ *Protocol section: CARDINALITY.*
+
+## 4. Think E second
+
+Mark where the graph can break. Each break point is one of three things:
+
+- **Retry** `⟳` — transient failure, try again. Network timeout, rate limit,
+  connection reset.
+- **Escape Hatch** `↯` — recoverable, return an alternative. Fallback value,
+  cached result, default, skip-and-continue.
+- **Die** `☠` — defect, invariant violation, programmer bug. NOT a domain
+  error. Something is fundamentally wrong.
+
+Failures are first-class values in the E channel until you truly cannot handle
+them. They flow through the graph like data — whether your language expresses
+that as Result types, checked exceptions, error returns, or a strict rule that
+exceptions only cross at layer joins. You decide at each node: retry, escape,
+or propagate. Only `die` when the program's assumptions are violated.
+
+→ *Protocol section: GRAPH (E annotations) + VERDICT.*
+
+## 5. Think R third
+
+Mark what each node in the graph needs to exist. "We cannot do X if we don't
+have Y."
+
+R is proof that dependencies are satisfied — at compile time (injected via
+constructors, generics, typeclasses, traits) or at wiring time (composition
+root, DI container, context object). Every node declares what it requires: a
+database connection, a config value, an HTTP client. R shrinks as you provide
+layers. When R is empty, the program can run. If R is not empty, the compiler
+or the wiring tells you exactly what's missing.
+
+→ *Protocol section: GRAPH (R annotations) + TEST LAYERS.*
+
+## 6. Trust at boundary
+
+Where does untrusted data enter the graph? HTTP requests, file reads,
+environment variables, user input, third-party API responses.
+
+Convert `unknown → trusted` at the edges — a schema, a parsing constructor, a
+validating factory, a DTO boundary. One definition = type + validator +
+transformer. Define it once, use it everywhere.
+
+Trust nothing at the boundary. Trust everything inside. The boundary is the
+only place you parse. After that, the types guarantee shape.
+
+→ *Protocol section: BOUNDARIES.*
+
+## 7. Layer behavior
+
+What cross-cutting concerns wrap nodes? Retry policies, timeouts, logging,
+tracing, caching.
+
+These wrap WITHOUT changing the core graph — middleware, decorators,
+higher-order functions, aspects. The happy path stays clean: you can read it
+without wading through retry logic and timeout configuration. Behavior is
+composed orthogonally. The graph says WHAT happens. The layers say HOW it
+behaves under pressure.
+
+→ *Protocol section: BEHAVIOR.*
+
+## 8. Scope resources
+
+What nodes acquire resources? Database connections, file handles, WebSocket
+connections, child processes, locks.
+
+Acquire/release must be structurally bound: RAII, `defer`, context managers,
+`try/finally` at the owning node — even on error, even on interrupt. Cleanup
+is structural, not a TODO comment you hope someone remembers.
+
+→ *Protocol section: SCOPE.*
+
+## 9. Swap R to prove it
+
+The call graph doesn't change between production and tests. Only R changes.
+
+Same graph shape. Same A flowing through. Same E possible. Different layer
+behind R. If the graph can't run with a test R, the design has hidden
+dependencies. If you have to mock the world to test one node, the node is
+doing too much.
+
+This is the payoff of separating A, E, and R — you prove the graph correct by
+swapping what's behind R.
+
+→ *Protocol section: TEST LAYERS.*
+
+## 10. Separate A from E structurally
+
+The separation of A (§2) and E (§4) maps directly onto code structure, in any
+language:
+
+- **The happy path body** — one readable place. Every call is an A flowing
+  through the graph. No error handling inside. (In Effect-TS: the `Effect.gen`
+  body. Elsewhere: the main function, the do-notation block, the straight-line
+  pipeline of calls.)
+- **The failure join points** — the complete E enumeration. Before writing
+  them, read the actual failure modes of every node on the happy path. The
+  join points catch, retry, or translate every E the happy path can produce.
+  (In Effect-TS: `.pipe()` after gen. Elsewhere: the middleware stack, the
+  Result chain, the try/catch at the layer boundary.)
+
+This is not a stylistic preference. If error handling lives inside the happy
+path body, the A path and E path are tangled — you cannot read the happy path
+without wading through catches and retries. The happy path body IS the call
+graph from §2. The join points ARE the error annotations from §4.
+
+### E scoping at graph layers
+
+Each layer scopes its own E before passing to the next layer. A service catches
+storage errors and produces a domain error. Auth catches domain errors and
+produces an access error. The handler catches access errors and produces the
+declared interface error. Each layer's handling is a complete enumeration of
+what IT received — not what originated three layers down. Consumers never see
+implementation errors from deeper layers. *(See protocol.md for the diagram.)*
+
+### Divergent strategies
+
+When two nodes in the same happy path need different failure handling — one
+should fail hard, the other should fall back gracefully — that is a
+**divergent strategy**. Handle each node's E inline within the happy path at
+the fork, because the outer join point cannot distinguish which node produced
+which error. This is the ONE exception to "no error handling in the happy
+path." It exists because the graph has a fork: two branches with different
+failure semantics sharing a node. Mark it clearly — it should be rare.
+
+---
+
+## The Pipeline
+
+```
+PROBLEM
+  -> "What are the shapes?"                       -> define the domain language
+  -> "What is the happy path?"                    -> draw the call graph (A)
+  -> "Is each node one-shot or a flow?"           -> mark cardinality
+  -> "Where can it break?"                        -> annotate errors on the graph (E)
+  -> "What does each node need?"                  -> annotate requirements on the graph (R)
+  -> "Where does untrusted data enter?"           -> parse at graph boundaries
+  -> "What wraps nodes without changing them?"    -> layer behavior orthogonally
+  -> "What resources need cleanup?"               -> scope lifecycle
+  -> "Can I swap R and the graph still works?"    -> verify with test layers
+  -> "Does my code separate A from E structurally?" -> happy path = A, joins = E
+  -> CODE                                         -> the code IS the graph
+```
+
+**If the code doesn't match the call graph, the implementation is wrong.**
+
+---
+
+*The original Effect-TS instantiation of this method ships verbatim in the
+package at `references/effect-ts.md` — for attribution and Effect-TS users
+only. Everything above is stack-agnostic.*

package/skills/graph-protocol/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: graph-protocol
+description: >
+  Graph Protocol — notation spec for Design Graphs. Fixed sections (PROBLEM,
+  SHAPES, GRAPH, CARDINALITY, BOUNDARIES, BEHAVIOR, SCOPE, TEST LAYERS,
+  VERDICT) and fixed markers (⟳retry ↯escape ☠die 🔒boundary (1)(N)(T) ⛈layer
+  @scope). Use when writing, reviewing, or checking any Design Graph so
+  notation is mechanically checkable and identical across languages.
+---
+
+# Graph Protocol
+
+The notation spec for **Design Graphs**. A Design Graph is the annotated call graph
+of a concrete problem: nodes are functions, edges are data flow, and every node
+carries annotations for data (A), cardinality, failure (E), and requirements (R).
+
+The Protocol is stack-agnostic. A graph written for Go, Rust, Python, TypeScript,
+SQL, or a spreadsheet renders identically. Only the vocabulary inside the
+annotations changes (e.g. what "retry" means in your language).
+
+Every tool in this package (`/cg`, `/cg-plan`, `/cg-review`, `/cg-map`, and the
+`/dt` active mode) MUST emit output in the format below.
+
+---
+
+## Canonical output skeleton
+
+Sections appear in this fixed order. Omit a section only when it is genuinely
+empty for the problem at hand (say so: `SCOPE: none`), never to skip thinking.
+
+```
+PROBLEM: <one-line statement of what you're building or examining>
+
+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:  <the nouns: records, IDs, variants, errors>
+
+GRAPH:
+  <ascii call graph, annotated inline>
+
+CARDINALITY: <node (1|N|T) list>
+BOUNDARIES:  <every edge crossing untrusted → trusted>
+BEHAVIOR:    <cross-cutting layers that wrap nodes>
+SCOPE:       <resources: acquire@… → release@…>
+TEST LAYERS: <the R that tests provide — same GRAPH, zero code change>
+VERDICT:     <code matches graph? what is missing/tangled?>
+```
+
+---
+
+## The header tree
+
+The header names the problem and anchors the three channels. `X` is your problem;
+everything after it is the graph you build.
+
+```
+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: what you're trying to build
+```
+
+---
+
+## Section rules
+
+### PROBLEM
+
+One line. The thing you're building or the question you're answering. If you
+cannot write it in one line, the problem is not understood — stop and refine.
+
+### SHAPES
+
+The domain nouns. Name them before drawing anything:
+
+- **Records** — entities that flow through nodes (User, Order, Config).
+- **IDs** — identity, never a bare primitive (UserId, Email).
+- **Variants** — internal state transitions (pending|active|cancelled).
+- **Errors** — named failure modes, structured, carrying context (not strings).
+
+Format: comma-separated list. These are the nouns; the graph is the verbs.
+
+### GRAPH
+
+ASCII call graph. Nodes are functions/steps; edges are data flow. Annotate
+**inline**, using the branch conventions from the header tree:
+
+```
+parse → Handler → Service → Repo
+│                      │        │
+│                      │        └─ R: DbConn · (N)
+│                      └─ E: timeout ⟳retry×3 → ↯escape(cached)
+└─ 🔒 HTTP body → trusted
+```
+
+Inline annotation grammar:
+
+| Annotation | Meaning | Example |
+|---|---|---|
+| `R: a, b` | what the node requires (§5) | `R: DbConn, Config` |
+| `E: <err> ⟳retry[×n] → ↯escape(alt)` | failure handling (§4) | `E: NetErr ⟳retry×3 → ↯escape(fallback)` |
+| `E: <err> ☠die` | defect, not domain error (§4) | `E: NullConfig ☠die` |
+| `🔒 x → y` | untrusted → trusted boundary (§6) | `🔒 JSON → Settings` |
+| `(1) (N) (T)` | cardinality (§3) | `(N)` = many over time |
+| `⛈ name` | behavior layer wrapping the node (§7) | `⛈logging wraps Service` |
+| `@scope` | resource bound to a scope (§8) | `DbConn @main` |
+
+### CARDINALITY
+
+One line listing each node's arity:
+
+- `(1)` — one-shot: runs once, produces one value.
+- `(N)` — many: emits values over time (stream, iterator, subscription, pages).
+- `(T)` — time-bounded: result valid for a window; cache it, dedupe concurrent lookups.
+
+Same three channels (A, E, R) in all cases. Different cardinality. The code must
+match: don't implement a `(N)` node as a one-shot.
+
+### BOUNDARIES
+
+Every place untrusted data enters the graph: HTTP requests, file reads, env
+vars, user input, third-party responses. The rule: **parse, don't validate** —
+convert `unknown → trusted` once, at the edge, then trust the types everywhere
+inside. One definition per shape = type + validator + transformer, reused
+everywhere.
+
+### BEHAVIOR
+
+Cross-cutting concerns that wrap nodes WITHOUT changing the core graph:
+retry policies, timeouts, logging, tracing, caching. Composed orthogonally
+(middleware, decorators, higher-order wrappers, aspects). The graph says WHAT
+happens; the layers say HOW it behaves under pressure. If removing logging
+forces you to edit business logic, behavior is not orthogonal.
+
+### SCOPE
+
+Resources that must be released: connections, file handles, sockets, child
+processes. Acquire/release must be structurally bound (RAII, `defer`, context
+managers, `try/finally`) — never convention or a TODO. Notation:
+
+```
+SCOPE: DbConn acquire@main → release@main · WS acquire@Handler → release@Handler
+```
+
+### TEST LAYERS
+
+The R that tests provide. The call graph does not change between production and
+tests — only R changes. Same graph, same A, same E, different layers behind R.
+If the graph can't run with a test R, the design has hidden dependencies. If
+you must mock the world to test one node, the node does too much.
+
+### VERDICT
+
+The structural check. Answer explicitly:
+
+- Is the happy path (A) readable on its own, free of failure handling?
+- Is every E the graph can produce handled at a defined join point?
+- Do per-layer E scopes translate errors (inner errors never leak through)?
+- Does the code match the graph? **If the code doesn't match the call graph,
+  the implementation is wrong.**
+
+---
+
+## E scoping at graph layers
+
+Each layer scopes its own E before passing to the next:
+
+```
+Services  →  Auth  →  Handlers
+E=SqlErr      E=DbErr      E=AuthErr      E=RPC errs
+  ↓ scope       ↓ scope      ↓ scope
+DbErr          AuthErr      RPC errs
+```
+
+A service catches `SqlErr` and produces `DbErr`. Auth catches `DbErr` and
+produces `AuthErr`. The handler catches `AuthErr` and produces the declared
+error. Each layer's handling enumerates what IT receives — never what originated
+three layers down. Consumers never see implementation errors from deeper layers.
+
+## Divergent strategies (the one exception)
+
+When two nodes in the same happy path need different failure semantics — one
+must fail hard, another must fall back gracefully — handle that node's E
+inline at the fork, because the outer layer cannot distinguish which node
+produced which error. Mark it clearly; it should be rare.
+
+---
+
+## Worked example (non-TS: Python CLI)
+
+```
+PROBLEM: sync a list of URLs to local files, resumable, with a status line
+
+X → DesignGraph<A, E, R>
+│              │   │  │  │
+│              │   │  │  └─ R: Http, Clock, Logger      (§5)
+│              │   │  └──── E: NetErr, DiskErr          (§4)
+│              │   └─────── A: (url, bytes), Status     (§2)
+│              │
+│              └─ nodes = functions, edges = data flow
+│
+└─ the problem
+
+SHAPES:  Url, Target(path), Downloaded(url, bytes), Status(pending|done|failed), NetErr, DiskErr
+
+GRAPH:
+  load_state → plan → fetch … download → write → report
+  │                │              │                    │
+  │                │              ├─ E: NetErr ⟳retry×3(-backoff) → ↯escape(skip, mark failed)
+  │                │              └─ 🔒 raw bytes → Downloaded (size, content-type checked)
+  │                └─ R: StateFile · (1)
+  └─ 🔒 state file → trusted (schema-validated; corrupt → ↯escape(empty, warn))
+
+CARDINALITY: load_state (1) · plan (1) · fetch (N) · download (1) · write (1) · report (T)
+BOUNDARIES:  load_state 🔒 file → State · fetch 🔒 wire → Downloaded
+BEHAVIOR:    ⛈retry wraps fetch · ⛈rate-limit wraps fetch · ⛈progress wraps write
+SCOPE:       Http acquire@main → release@main · StateFile @main (context manager)
+TEST LAYERS: R = {Http: FakeHttp, Clock: FrozenClock, Logger: Silent} — same GRAPH, no stubs in nodes
+VERDICT:     happy path reads as the pipeline above; all NetErr handling lives at the
+             write/report join, not inside download; state corruption escapes at the edge.
+             Matches graph → implementation valid.
+```
+
+Note the stack vocabulary: `context manager` for scope, exceptions caught at
+layer joins for E, plain functions for nodes. Protocol unchanged.