# decision-lens
> **Stop letting AI hide the real tradeoffs.** A Claude Skill that pressure-tests your decisions through multiple independent expert lenses, surfaces the disagreements, and converges on a recommendation plus the questions only you can answer.
[](LICENSE)
[](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
---
## The Problem
When you ask AI "what should I do?", you usually get one of two bad answers:
1. **A single recommendation** that hides the real tradeoffs — you act on it without knowing what you're trading away
2. **A list of 5 options** with no recommendation — the AI just bounced the decision back to you, more confused than before
Both fail. The first hides information. The second creates decision fatigue.
## What decision-lens Does Differently
Instead of giving one opinion or dumping options, this skill makes Claude reason from **multiple independent expert perspectives** — product, marketing, UX, business, risk, architecture, cognitive science, and more. It forces the real disagreements between these roles to surface, then converges on:
- **What everyone agrees on** (the consensus)
- **Where they disagree** (the most important section — disagreement is usually exactly where you actually need to decide)
- **One primary recommendation** (with reasoning)
- **3–5 questions only you can answer** (not execution details disguised as decisions)
- **Concrete next actions** (with owner and acceptance criteria)
The output looks like a real strategy review by a senior team. Not a brainstorm.
## Quick Start
### Install
Drop `SKILL.md` into your Claude Code skills directory:
```bash
# Clone the repo
git clone https://github.com/xuenerissa-png/decision-lens.git
# Copy the skill to your Claude Code config (adjust path as needed)
cp decision-lens/SKILL.md ~/.claude/skills/decision-lens/SKILL.md
```
Or, for any project, drop `SKILL.md` into `.claude/skills/decision-lens/` in your project root.
### Use
In any Claude Code session, trigger the skill by saying any of:
- "Let's use the decision lens on this"
- "Multi-role review please"
- "Help me think through this"
- "评审一下" (Chinese)
- "审视一下这个决定"
Or just describe a complex decision — Claude will proactively offer: *"This looks like a complex decision — want me to run it through the decision lens?"*
## When To Use This Skill
**✅ Use it for**:
- Product direction calls ("Which audience should we focus on?")
- Architecture choices ("Build auth ourselves or use a third-party?")
- Scope cutting ("Do we ship feature X for launch or push to V2?")
- Positioning decisions ("Are we a tool or a platform?")
- Cross-project tradeoffs ("Which project gets the next 2 weeks?")
**❌ Don't use it for**:
- Writing code, fixing bugs, debugging — execution tasks
- Single-fact questions ("what does this function do?")
- Decisions where you already know the answer and just want validation
## See It In Action
Three real-world examples (decisions you've probably faced):
- [**01 · Product Positioning**](examples/01-product-positioning.md) · Developer-first or marketer-first for a new SaaS?
- [**02 · Feature Scope Cut**](examples/02-feature-scope-cut.md) · Ship community feature for launch (investors want it) or focus on core?
- [**03 · Technical Architecture**](examples/03-technical-architecture.md) · Build your own auth or use Clerk for a 3-person B2B team?
Each example shows the full output format and explains what the framework caught that a single-stance answer would have missed.
## How It Works Under The Hood
The skill defines:
1. **A trigger protocol** — when to fire and when not to (prevents over-application on trivial questions)
2. **A 7-section output structure** (full version) and a 4-section compressed version for medium-complexity questions
3. **A role library** — 5 baseline roles always present + 7 specialty roles summoned as needed
4. **Mountable lenses** — VC lens, cognitive experience lens, and project-specific lenses you can define yourself
5. **Output discipline** — must converge to a recommendation, decision questions must be genuinely user-only, action items must be executable
See [SKILL.md](SKILL.md) for the complete specification.
## Why This Exists
This framework was built and battle-tested across several shipped products over a year of solo development. It started as a personal protocol after watching too many AI conversations end with "well, here are five things you could do" — leaving the actual decision exactly where it started.
The core insight: **AI is great at generating options. It's bad at forcing the tradeoffs to the surface.** Multi-role review is a structural fix — by asking multiple independent perspectives to argue with each other first, the disagreements become visible. Those disagreements are usually where the real decision lives.
This skill is the productized, anonymized version of that protocol. It's MIT licensed — use it, modify it, mount your own lenses on top of it.
## Contributing
This is v0.1. Contributions welcome:
- **New lenses** for specific domains (healthtech, fintech, education, etc.)
- **New role definitions** with clear scope
- **Real-world examples** (anonymized) showing how the framework worked or didn't
- **Translations** — currently the SKILL.md is English; trigger words include Chinese
Open an issue first to discuss scope, then PR.
## License
MIT — see [LICENSE](LICENSE).
## Author
Built by [@xuenerissa-png](https://github.com/xuenerissa-png) while developing multiple products in parallel and getting tired of AI giving scattered advice.
If you find this useful, a ⭐ is the cheapest way to tell me it's worth iterating on.