Skip to content

JPeetz/agent-skills / skills/development/mattpocock-dev-workflows

mattpocock-dev-workflows

Verified

Use when you need Matt Pocock's engineering workflow patterns: spec synthesis, deep-module design, domain modeling, two-axis code review, or disciplined bug diagnosis. A meta-skill covering five complementary sub-patterns for real engineering — not vibe coding.

references/design-it-twice.md

View on GitHub
# Design It Twice

When the user wants to explore alternative interfaces for a chosen
deepening candidate, use this parallel sub-agent pattern. Based on
"Design It Twice" (Ousterhout): your first idea is unlikely to be the
best.

Uses the vocabulary from codebase-design-glossary.md: module, interface,
seam, adapter, leverage.

## Process

### 1. Frame the problem space

Before spawning sub-agents, write a user-facing explanation of the
problem space for the chosen candidate:

- The constraints any new interface would need to satisfy
- The dependencies it would rely on, and which category they fall into
  (see deepening.md)
- A rough illustrative code sketch to ground the constraints, not a
  proposal, just a way to make the constraints concrete

Show this to the user, then immediately proceed to Step 2. The user reads
and thinks while the sub-agents work in parallel.

### 2. Spawn sub-agents

Spawn 3+ sub-agents in parallel. Each must produce a **radically
different** interface for the deepened module.

Prompt each sub-agent with a separate technical brief (file paths,
coupling details, dependency category from deepening.md, what sits behind
the seam). The brief is independent of the user-facing problem-space
explanation in Step 1. Give each agent a different design constraint:

- Agent 1: "Minimize the interface: aim for 1-3 entry points max.
  Maximise leverage per entry point."
- Agent 2: "Maximise flexibility: support many use cases and extension."
- Agent 3: "Optimise for the most common caller: make the default case
  trivial."
- Agent 4 (if applicable): "Design around ports & adapters for cross-seam
  dependencies."

Include both codebase-design-glossary.md vocabulary and CONTEXT.md
vocabulary in the brief so each sub-agent names things consistently with
the architecture language and the project's domain language.

Each sub-agent outputs:

1. Interface (types, methods, params, plus invariants, ordering, error
   modes)
2. Usage example showing how callers use it
3. What the implementation hides behind the seam
4. Dependency strategy and adapters (see deepening.md)
5. Trade-offs: where leverage is high, where it's thin

### 3. Present and compare

Present designs sequentially so the user can absorb each one, then
compare them in prose. Contrast by **depth** (leverage at the interface),
**locality** (where change concentrates), and **seam placement**.

After comparing, give your own recommendation: which design you think is
strongest and why. If elements from different designs would combine well,
propose a hybrid. Be opinionated: the user wants a strong read, not a
menu.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall