evanflow-design-interface

Name: evanflow-design-interface
Author: evanklem

419stars18forks

How to install evanflow-design-interface?

evanklem/evanflow/evanflow-design-interface

$npx -y skills add evanklem/evanflow --skill evanflow-design-interface

Installs into the current project.

Summary

Design a module's interface using parallel sub-agents producing radically different designs ("design it twice"). Compare on depth, simplicity, and efficiency. Embedded grill on the synthesized choice. Use when designing a new API, exploring interface options, or deciding the shap

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Design an Interface
2
3
4	Source principle: "Design It Twice" from John Ousterhout's A Philosophy of Software Design. Your first idea is unlikely to be the best. Generate radically different designs, compare, synthesize.
5
6	## Vocabulary
7
8	See `evanflow` meta-skill. Key terms: interface, depth, module, adapter.
9
10	## When to Use
11
12	- Designing a new API surface (tRPC router, service interface, public function set)
13	- Refactor changes a public interface — design before implementing
14	- Stuck on the shape of a module
15	- The team disagrees on the right interface
16
17	## The Flow
18
19	### 1. Gather Requirements
20
21	- What problem does this module solve?
22	- Who are the callers? (other modules, external users, tests)
23	- Key operations
24	- Constraints (performance, compatibility, existing project patterns from `CONTEXT.md`)
25	- What should be hidden vs. exposed
26
27	### 2. Spawn Parallel Sub-Agents (Design It Twice — actually 3+)
28
29	Dispatch 3+ Explore or general-purpose agents simultaneously (single message, multiple Agent tool calls). Each gets a radically different constraint:
30
31	- Agent 1: "Minimize method count — aim for 1–3 methods max."
32	- Agent 2: "Maximize flexibility — support many use cases."
33	- Agent 3: "Optimize for the most common case (specify what that is)."
34	- (Optional) Agent 4: "Take inspiration from <specific paradigm or library>."
35
36	Each returns:
37
38	1. Interface signature (types, methods, params)
39	2. Usage example (how the caller actually uses it)
40	3. What the design hides internally
41	4. Trade-offs
42
43	### 3. Present Designs Sequentially
44
45	Show each design separately so the user can absorb each before comparison. No tables yet — let each design stand on its own.
46
47	### 4. Compare
48
49	After all designs are shown, compare on:
50
51	- Interface simplicity: fewer methods, simpler params
52	- General-purpose vs. specialized: flexibility vs. focus
53	- Implementation efficiency: does the shape allow efficient internals or force awkward ones?
54	- Depth: small interface hiding significant complexity (good) vs. large interface with thin implementation (bad)
55	- Ease of correct use vs. ease of misuse
56
57	Discuss in prose. Highlight where designs diverge most.
58
59	### 5. Synthesize
60
61	Often the best design combines insights from multiple options. Ask:
62
63	- "Which design best fits the primary use case?"
64	- "Any elements from other designs worth incorporating?"
65
66	### 6. Embedded Grill on the Synthesis
67
68	Before committing to the design:
69
70	- "What's the simplest way a caller could misuse this?"
71	- "What test would force this interface to change unnecessarily? Does that test exist or would we write it?"
72	- "Is the interface still simple after we incorporate the borrowed elements, or did the synthesis bloat it?"
73	- "Apply the deletion test to internal helper modules implied by this design."
74
75	## Hard Rules
76
77	- Don't let sub-agents converge. Enforce radical difference. If agents return similar designs, re-spawn with sharper constraints.
78	- Don't skip comparison. The value is in the contrast.
79	- Don't implement. This skill is purely about interface shape. Implementation goes through `evanflow-writing-plans` + `evanflow-tdd`.
80	- Don't evaluate based on implementation effort. Evaluate on interface quality.
81	- Never auto-commit. Even a design doc gets staged, not committed.
82
83	## Hand-offs
84
85	- Design chosen → `evanflow-writing-plans` (the plan implements the design)
86	- Design reveals architecture concerns → `evanflow-improve-architecture` first
87	- New domain terms emerged → `evanflow-glossary` to update `CONTEXT.md`

People who liked this also viewed

6 picks

Type

evanflow-design-interface

419stars18forks

View on GitHub

How to install evanflow-design-interface?

evanklem/evanflow/evanflow-design-interface

$npx -y skills add evanklem/evanflow --skill evanflow-design-interface

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Design an Interface
2
3
4	Source principle: "Design It Twice" from John Ousterhout's A Philosophy of Software Design. Your first idea is unlikely to be the best. Generate radically different designs, compare, synthesize.
5
6	## Vocabulary
7
8	See `evanflow` meta-skill. Key terms: interface, depth, module, adapter.
9
10	## When to Use
11
12	- Designing a new API surface (tRPC router, service interface, public function set)
13	- Refactor changes a public interface — design before implementing
14	- Stuck on the shape of a module
15	- The team disagrees on the right interface
16
17	## The Flow
18
19	### 1. Gather Requirements
20
21	- What problem does this module solve?
22	- Who are the callers? (other modules, external users, tests)
23	- Key operations
24	- Constraints (performance, compatibility, existing project patterns from `CONTEXT.md`)
25	- What should be hidden vs. exposed
26
27	### 2. Spawn Parallel Sub-Agents (Design It Twice — actually 3+)
28
29	Dispatch 3+ Explore or general-purpose agents simultaneously (single message, multiple Agent tool calls). Each gets a radically different constraint:
30
31	- Agent 1: "Minimize method count — aim for 1–3 methods max."
32	- Agent 2: "Maximize flexibility — support many use cases."
33	- Agent 3: "Optimize for the most common case (specify what that is)."
34	- (Optional) Agent 4: "Take inspiration from <specific paradigm or library>."
35
36	Each returns:
37
38	1. Interface signature (types, methods, params)
39	2. Usage example (how the caller actually uses it)
40	3. What the design hides internally
41	4. Trade-offs
42
43	### 3. Present Designs Sequentially
44
45	Show each design separately so the user can absorb each before comparison. No tables yet — let each design stand on its own.
46
47	### 4. Compare
48
49	After all designs are shown, compare on:
50
51	- Interface simplicity: fewer methods, simpler params
52	- General-purpose vs. specialized: flexibility vs. focus
53	- Implementation efficiency: does the shape allow efficient internals or force awkward ones?
54	- Depth: small interface hiding significant complexity (good) vs. large interface with thin implementation (bad)
55	- Ease of correct use vs. ease of misuse
56
57	Discuss in prose. Highlight where designs diverge most.
58
59	### 5. Synthesize
60
61	Often the best design combines insights from multiple options. Ask:
62
63	- "Which design best fits the primary use case?"
64	- "Any elements from other designs worth incorporating?"
65
66	### 6. Embedded Grill on the Synthesis
67
68	Before committing to the design:
69
70	- "What's the simplest way a caller could misuse this?"
71	- "What test would force this interface to change unnecessarily? Does that test exist or would we write it?"
72	- "Is the interface still simple after we incorporate the borrowed elements, or did the synthesis bloat it?"
73	- "Apply the deletion test to internal helper modules implied by this design."
74
75	## Hard Rules
76
77	- Don't let sub-agents converge. Enforce radical difference. If agents return similar designs, re-spawn with sharper constraints.
78	- Don't skip comparison. The value is in the contrast.
79	- Don't implement. This skill is purely about interface shape. Implementation goes through `evanflow-writing-plans` + `evanflow-tdd`.
80	- Don't evaluate based on implementation effort. Evaluate on interface quality.
81	- Never auto-commit. Even a design doc gets staged, not committed.
82
83	## Hand-offs
84
85	- Design chosen → `evanflow-writing-plans` (the plan implements the design)
86	- Design reveals architecture concerns → `evanflow-improve-architecture` first
87	- New domain terms emerged → `evanflow-glossary` to update `CONTEXT.md`

People who liked this also viewed

6 picks

Type