Lens Review

---
name: lens-review
description: "Review a design artifact (GDD / vision / ADR / mechanic spec / prototype doc / any design document) through 100 game design lenses. Auto-picks 3-5 most relevant lenses based on artifact type, outputs multi-angle insights + multiple directions with explicit trade-offs (no single prescribed answer). Hedged tone, not preachy. **Triggers**: (1) user says \"过 lens / lens review / use a lens / 用透镜看看 / change the angle / 换个角度评估\" (2) user provides a design artifact path and asks for \"blind spots / risks / different perspectives / 盲点 / 风险 / 不同视角\" (3) before/after major changes to a vision or proposition-level doc (4) stuck on what to do next, wants reframing (5) user mentions \"lens / game design lens / 设计透镜\". Library lives at lib/100-lenses.{zh,en}.md, shared between Claude Code and Codex / other tools that read it directly. / 用 100 个游戏设计透镜审视设计 artifact,自动选 3-5 个最相关透镜,产出多视角洞察 + 多方向建议(带 trade-off,不指定对错)。"
argument-hint: "<artifact-path> [#N | --category <cat> | --count <3-8>]"
user-invocable: true
allowed-tools: Read, Glob, Grep
version: 1.0.0
---

# Lens Review Skill

Apply 100 classic game design lenses to a design artifact for multi-angle review.

**What makes this skill different**: it does NOT give you "the right answer". It surfaces **perspectives + multiple directions + trade-offs**, leaving the decision to you. Tone is hedged, not preaching.

---

## Language detection

**Always match the user's language** in the response:

1. If the artifact content is mostly Chinese → read [`lib/100-lenses.zh.md`](../../lib/100-lenses.zh.md), respond in Chinese.
2. If the artifact content is mostly English → read [`lib/100-lenses.en.md`](../../lib/100-lenses.en.md), respond in English.
3. If the user's invocation message is in a different language than the artifact, prefer the **invocation language** for the response (user is the audience).
4. If unclear, default to English.

The lens library files are equivalent in content; pick the one matching the response language so the lens names / questions match the rest of the output.

---

## Data source

**Lens library** (single source of truth, shared across Claude Code and Codex):

- [`lib/100-lenses.zh.md`](../../lib/100-lenses.zh.md) — Chinese
- [`lib/100-lenses.en.md`](../../lib/100-lenses.en.md) — English

100 lenses each, 5 static fields per lens: `Category / How to use / Key questions / Elaboration / When to use`. This skill consumes the library; it does not modify it.

Users can extend the library with their own lenses (custom project-specific lenses) by appending entries in the same format.

---

## Invocation modes

| Form | Behavior |
|---|---|
| `/lens-review <artifact>` | Read artifact + auto-pick 3-5 most relevant lenses + full pass |
| `/lens-review <artifact> #N` | Apply a single specific lens (for deep dive on one angle) |
| `/lens-review <artifact> #N,M,K` | Apply multiple specified lenses |
| `/lens-review <artifact> --category <cat>` | Restrict to a category (Designer/Player/Experience/Process/Game) |
| `/lens-review <artifact> --count 5` | Explicit count (default 3-5, can go 3-8) |

---

## Auto-selection heuristics

After reading the artifact, pick lenses based on **artifact type + content keywords**. Default mapping (can layer):

| Artifact type | Suggested lens categories (pick 3-5 from) |
|---|---|
| **Vision / proposition doc** | Experience (#1 Essential / #2 Surprise / #3 Fun / #4 Curiosity) + Designer (#100 Secret Purpose / #11 Infinite Inspiration / #10 Resonance) |
| **GDD - mechanic / combat / balance** | Game / Balance (#30 Fairness / #31 Challenge / #32 Meaningful Choice / #34 Skill vs Chance / #47 Balance) |
| **GDD - puzzle / level** | Game / Puzzle (#50 Parallelism / #52 The Puzzle) + #61 Interest Curve |
| **ADR / architecture decision** | Process (#13 Eight Filters / #14 Risk Mitigation) + Designer (#100 Secret Purpose / #12 Problem Statement) |
| **UX / HUD / Interface spec** | Interface (#53 Control / #54-55 Physical/Virtual Interface / #56 Transparency / #57 Feedback) |
| **Story / Narrative spec** | Story (#65 Story Machine / #68 Hero's Journey / #70 Story / #69 Weirdest Thing) |
| **Character spec** | Character (#75 Avatar / #76 Function / #77 Traits / #81 Transformation) |
| **Prototype spec / early experiment** | Experience + Process (#13 Eight Filters / #91 Playtesting / #15 The Toy) |
| **Audio / Aesthetics spec** | Experience (#10 Resonance / #63 Beauty) + Aesthetics |
| **Multiplayer / Community spec** | Community (#86 Community / #87 Griefing / #89 Team / #36 Competition / #37 Cooperation) |
| **Generic design review (type unclear)** | Pick one from each of 4 major categories + #1 Essential Experience as anchor |

**Selection principles**:
- Prefer matching artifact keywords against each lens's `When to use` field (already in library)
- Don't pick lenses unrelated to the artifact (better fewer than padding)
- If the artifact spans multiple framings, pick across categories
- **Avoid mechanically picking the same 5 every time** — the heuristics above are starting points, not defaults

**Avoid**:
- ❌ Picking all 100 lenses (selectivity is core value)
- ❌ Picking only "famous" lenses (#1/#2/#3) when more specific ones fit better

---

## Output format

For each picked lens, output the following template. **Strictly follow section order and punctuation**:

```markdown
### Lens #N: English Name (中文名 if responding in Chinese)

> **What this lens asks** / **这盏 lens 在问的是**: [one-sentence framing, distilled from library's `How to use` field]

---

**[Observation]** / **【观察】** — What's in the doc

[List factual evidence from the artifact only. No judgment, no interpretation. Cite with file:line anchors like `[doc.md:L42-L48](path/to/doc.md#L42-L48)`.]

---

**[Insight]** / **【洞察】** — What this lens surfaces (one reading, not a verdict)

[Analyze through this lens. **Must be hedged**: "perhaps / possibly / it looks like / one reading / if X happens, Y might follow".

You may reference relevant examples (from the library's `Elaboration` field, or well-known game design touchstones like Wii Sports, Hades, Slay the Spire, etc).

If there's a counter-reading, surface it: "It could also be read the other way: ..." — show this is one lens among many, not THE truth.]

---

**[Directions to consider]** / **【可以走的方向】** — None is "the right one"; pick based on current resources / timeline / risk appetite

- **A. [Direction title]** — [one-line description].
  *Trade-off*: [costs + benefits, neutral phrasing, no leaning].

- **B. [Direction title]** — [one-line description].
  *Trade-off*: ...

- **C. [Direction title]** — [one-line description].
  *Trade-off*: ...

- **D. [Optional 4th direction]** — [one-line description].
  *Trade-off*: ...

---
```

**Direction count**: minimum 3, maximum 4. Fewer than 3 = narrow, violates "multiple directions" principle; more than 4 = decision fatigue.

---

## Tone rules

**Hedged** (required):
- ✅ "The doc looks like it sells X, but element Y *perhaps* creates a hidden gap"
- ✅ "One possible reading is..."
- ✅ "If [condition], the experience *might* drift from A to B"
- ❌ "The doc is clearly wrong"
- ❌ "Players *will* do X"
- ❌ "You must do X"

**Multiple directions** (required):
- ✅ List 3-4 directions, each with `Trade-off`, no preferred answer
- ❌ "I suggest you do X" — single direction
- ❌ "Best practice is Y" — authoritative voice

**Not preaching** (required):
- ✅ "What this lens surfaces is..." (the lens is doing work, not you lecturing)
- ✅ Reference examples by description, not as gospel ("the classic Wii Sports baseball case")
- ❌ "You should realize..." / "You need to..."
- ❌ Packaging "my judgment" as "universal truth"

**Preserve multiple perspectives** (strongly recommended):
- ✅ Actively surface "It could also be read the other way" — show lens is a tool not dogma
- ✅ Acknowledge trade-offs honestly; don't say "A is obviously better than B"

---

## Execution steps

1. **Parse args**: artifact path + optional lens IDs / category / count
2. **Read artifact**: use Read tool on user-provided doc
3. **Detect language** of artifact (and invocation message), pick library file accordingly
4. **Read library** (`lib/100-lenses.zh.md` or `lib/100-lenses.en.md`) — read once, reuse in context
5. **Pick lenses**:
   - Explicit (`#N` / `#N,M,K`) → use as-is
   - `--category` → restrict to that category's lenses
   - Auto → use § "Auto-selection heuristics" + match artifact keywords against each lens's `When to use` field
6. **For each picked lens, emit the output template**:
   - Distill library's `How to use` + `Key questions` into the "What this lens asks" one-liner
   - Read artifact for evidence → [Observation]
   - Analyze through lens; reference `Elaboration` if relevant → [Insight]
   - List 3-4 directions with `Trade-off` → [Directions]
7. **Summary tail** (always include, 4 sub-items):
   - **Picked** — list the N lenses chosen + one-line "why this lens fits"
   - **Avoided** — if there's an explicit reason to skip certain lenses (e.g., user said "exclude X"), list them
   - **Not picked but worth considering** — list 3-5 other relevant lenses + one-line "why they'd be a different angle"
   - **Deep dive hint** — one line: `/lens-review <artifact> #N` form, so user knows how to single-lens drill
8. **Do not modify the artifact** — only surface perspectives; the user decides what to change

---

## What this skill does NOT do

- ❌ Does not modify the artifact / write patches / generate code
- ❌ Does not pick more than 8 lenses (selectivity is core value)
- ❌ Does not assert absolutely, does not preach, does not give a single direction (tone rules enforce)
- ❌ Does not decide for the user — only shows perspectives + trade-offs
- ❌ Does not invent lenses outside the library (if a custom lens is needed, ask user to extend `lib/100-lenses.*.md`)

---

## Extending the library

Users can append project-specific lenses to `lib/100-lenses.{zh,en}.md` using the same 5-field format. Custom lens numbers should use a prefix to distinguish from the canonical 100, e.g., `#P1 The Lens of NL Translation` for a project-specific lens.

The skill will pick up custom lenses automatically since it reads the whole library at runtime.