design-thinking

A Claude Code (and general-purpose agent) skill that turns UX/UI questions — "nav bar or not?", "modal or inline?", "why do we even have this sidebar?" — into evidence-cited Design Decision Records (DDRs). The deliverable is not the chosen option; it is the WHY: numbered claims, each citing a usability heuristic (H#), a simulation outcome (S#), a project principle (P#), or an evidence class (E#). Taste is not a citation. Decisions stay consistent across a project via a per-project ledger (.design-thinking/) that every run reads before reasoning. The whole skill is plain Markdown — SKILL.md plus reference docs — readable by any agent with filesystem access.

How it works

Six phases, run in order, with a hard gate before anything is recorded:

flowchart LR
    C[1 Context] --> F[2 Frame]
    F --> D[3 Diverge]
    D --> S[4 Simulate]
    S --> G{5 Crit gate}
    G -- weak WHY --> F
    G -- thin option set --> D
    G -- pass --> R[6 Decide & Record]
    R --> L[(Ledger<br/>.design-thinking/)]
    L -. consistency check .-> F

Loading

• Phase 0 — Detect Mode: new decision, audit of an existing UI, consistency review, or ledger bootstrap.
• Phase 1 — Context (Empathize/Discover): observe code/screens first, then batched questions on product, users, evidence, constraints; write context.md.
• Phase 2 — Frame (Define): replace the asked question with the real problem — a problem statement and a How-Might-We, confirmed with the user before any option is named.
• Phase 3 — Diverge (Ideate): 3–5 genuinely different options, always including the status quo; no evaluation while listing.
• Phase 4 — Simulate (Prototype/Test): persona × journey walkthroughs producing numbered outcomes S1..Sn; optional grayscale wireframe previews when options differ structurally.
• Phase 5 — Crit gate: evidence check against the Weak-WHY blacklist, steelman every rejected option, consistency scan against the ledger, assumption surfacing. Failure loops back — iteration is the feature.
• Phase 6 — Decide & Record: write the DDR, promote durable rules into principles.md, mark superseded DDRs, end with implementation notes.

The ledger

Per-project persistent state, created in the project root:

.design-thinking/
├── context.md          # product, users, evidence inventory (E1–E5), constraints
├── principles.md       # numbered project principles P1..Pn, each citing the DDR that established it
├── decisions/
│   ├── 001-<slug>.md   # DDRs: options, simulations, WHY, rejections, revisit triggers
│   └── 002-<slug>.md
└── previews/           # transient wireframe HTML; deleted after the decision is recorded

Every run starts by reading context.md, principles.md, and all DDR titles + status lines. A new decision that conflicts with an old one must conform or explicitly supersede it — never silently diverge.

Example walkthrough

Question: "Should I add a nav bar to my recipe app?"

Reframed (Phase 2): Home cooks need to move between browsing, saved recipes, and the shopping list mid-cooking, but currently must return to the home screen each time. HMW: how might users reach the app's four sections with minimal orientation cost, one-handed, mid-task?

Options (Phase 3): 1. bottom tab bar · 2. hamburger menu · 3. home-screen hub + back (status quo) · 4. gesture-based section swiping

Simulation verdicts (Phase 4):

• S1: Maya (weeknight cook) / resume shopping list with wet hands / tab bar: one thumb-reach tap, no misfires.
• S2: Maya / same journey / hamburger: two taps plus a top-left reach; hesitated at the icon.
• S3: Tom (first visit) / find saved recipes / status quo: backtracked twice; never discovered the shopping list.
• S4: Tom / first visit / gesture swiping: no affordance — did not discover sections without instruction.

WHY (Phase 6, after the crit gate):

1. All four sections stay visible and one tap away during cooking, the highest-friction moment observed (S1, H1).
2. A persistent bar beats recall-based navigation for interrupted, one-handed use (S2, S3, H6).
3. 82% of sessions are on phones, so thumb-zone placement outweighs the vertical space cost (E1).

Revisit if: sections > 5, or tablet traffic > 25%.

Repository layout

This repository is the skill: the repo root is the skill directory. There is no plugin or marketplace wrapper — just SKILL.md (the entry point Claude reads first) and the reference docs it pulls in per phase. Drop this folder into any skills directory Claude Code scans and it auto-loads; the name in SKILL.md's frontmatter (design-thinking) is the skill's identity.

design-thinking/                  # the skill (repo root)
├── SKILL.md                      # entry point: pipeline, modes, Weak-WHY blacklist, ledger contract
├── frameworks.md                 # canonical models + criticisms-as-guardrails
├── methods.md                    # Phase 1–3 toolbox (empathy maps, HMW, personas, journeys)
├── decision-criteria.md          # H1–H10, E1–E5, scoring rubric, citation format
├── ui-patterns.md                # pattern catalog: wins-when / fails-when per decision family
├── wireframe-base.css            # grayscale low-fi preview kit
├── wireframe-example.html        # openable two-option wireframe (CSS inlined) — Phase 4 starting point
├── templates/                    # context-brief, principles, simulation, decision-record
├── README.md
└── LICENSE

SKILL.md links to the reference docs with plain relative paths, so the folder works unchanged wherever it lands.

Installation

Claude Code (auto-loaded skill)

Put the skill folder in a skills directory Claude Code scans; it then activates automatically whenever a request matches the description (a UX/UI decision). Skills are model-invoked, not slash commands — there is nothing to type.

# personal — available in every project
git clone https://github.com/c0utin/design-thinking ~/.claude/skills/design-thinking

# or project-local — checked in with one repo
git clone https://github.com/c0utin/design-thinking .claude/skills/design-thinking

Update later with git -C ~/.claude/skills/design-thinking pull.

Any agent with filesystem access

Point the agent at SKILL.md. It carries the full pipeline; the reference docs load per phase (progressive disclosure), so nothing else is required up front. To vendor it into another project without git:

mkdir -p <dest>/design-thinking
cp -r SKILL.md frameworks.md methods.md decision-criteria.md ui-patterns.md \
      wireframe-base.css templates <dest>/design-thinking/

Design notes

• First-diamond discipline. Context and framing come before any option is named; the asked question ("nav bar or not?") is rarely the real problem, and a wrong frame invalidates everything downstream.
• Crit is a gate, not a step. The most credible critique of design thinking is that it lacks crit — so a decision that cannot survive an evidence check, steelmen, and a consistency scan does not get recorded.
• Grayscale wireframes only. Previews use placeholder bars and no brand styling, so users react to structure, not polish that isn't being decided.
• Principles are earned. Nothing enters principles.md by fiat; each P# cites the DDR that established it, so a principle can be traced — and superseded — like any other decision.
• Evidence honesty. "We assume" is a recordable answer: E5 team assumptions are cited as such rather than dressed up as user knowledge, and every DDR names the observable events that should trigger a revisit.