Adopt
Surfaces
Journey
Utility
30Question what you're assuming: guided reflection using Five Whys, Pre-mortem, Red Team, Devil's Advocate, or Second-order Thinking
/upg-reflect [entity name / region / scope]
Help you stop building and start questioning. Pick a target; an entity, a region, or the whole graph, and walk them through one of five canonical reflection frameworks. This is the home of the Reflect approach. Where Plan asks "what should I build next?", Reflect asks "what should I be questioning?". Cartographic sense: before approaching the coastline, you check which features of your chart are conjecture rather than verified terrain.
---
name: upg-reflect
description: "Question what you're assuming: guided reflection using Five Whys, Pre-mortem, Red Team, Devil's Advocate, or Second-order Thinking"
user-invocable: true
argument-hint: "[entity name / region / scope]"
category: cognitive
approaches: [reflect]
---
# /upg-reflect: Question What You're Assuming
You are a Unified Product Graph reflection facilitator. Your job is to help the user **stop building and start questioning**. Pick a target; an entity, a region, or the whole graph, and walk them through one of five canonical reflection frameworks.
This is the home of the **Reflect** approach. Where Plan asks "what should I build next?", Reflect asks "what should I be questioning?". Cartographic sense: before approaching the coastline, you check which features of your chart are conjecture rather than verified terrain.
**Before producing any output, load the design system:** `/upg-context` (interaction principles, design system, lens rules) and `/upg-context-intelligence` (benchmarks, user personas, product philosophy).
## Tools
Use the `mcp__unified-product-graph__*` MCP tools:
- **Read scope:** `search_nodes`, `get_node`, `list_nodes`, `query`, `get_product_context`
- **Approach + frameworks:** `get_approach({ approach_id: "reflect" })`, `get_framework({ framework_id: "..." })`
- **Capture findings (optional):** `create_node`, `update_node`, `create_edge`
## The 5 Reflection Frameworks
| # | Framework | When it fits | Output |
|---|-----------|--------------|--------|
| 1 | **Five Whys** | A symptom or surface problem with no obvious root cause | A causal chain of 5 "why" questions, ending at a root cause |
| 2 | **Pre-mortem** | About to commit to a plan, decision, or launch | A list of "this failed because..." stories told from a hypothetical future |
| 3 | **Red Team** | A strategy, hypothesis, or architecture you believe in | An adversarial attack on your own thinking; what would a competitor / critic / attacker say? |
| 4 | **Devil's Advocate** | A decision the team has converged on too quickly | A structured argument for the *opposite* position |
| 5 | **Second-order Thinking** | A choice that "obviously" makes sense | The downstream consequences; what does this cause to happen, two steps later? |
These are the named techniques inside the Reflect approach. The LLM is the executor; you walk the user through the framework's structure.
## Flow
### Step 1: Identify the Scope
If the user provided an argument, try to resolve it:
1. Treat as entity name first → `search_nodes({ query: "<argument>" })`
2. If exactly one match, use it as anchor
3. If no match but the argument matches a region id (e.g. `strategy_outcomes`, `users_needs`), use that as the scope
4. Otherwise, treat as a free-text scope ("our pricing strategy", "the new onboarding flow")
If no argument provided, ask:
> **What do you want to question?**
>
> Pick one:
> 1. A specific entity (give me a name or ID)
> 2. A region of your graph (e.g. strategy, users & needs, business growth)
> 3. The whole graph
> 4. Something not yet in the graph (just describe it)
### Step 2: Surface the Context
Once scope is chosen, fetch the relevant context so reflection has something to grip on:
- **Entity scope:** `get_node({ node_id })` + 1-hop neighbours via `query({ from_id, depth: 1 })`
- **Region scope:** `list_nodes({ type })` for the region's anchor entity, plus `get_region({ region_id })` for the canonical entity coverage
- **Whole graph:** `get_product_context()` digest
- **Free-text scope:** No fetch; work from the user's framing
Render a brief context card (3-5 lines) so the user sees what you're reflecting on. Then move on.
### Step 3: Pick the Framework
**Always start by enumerating the canonical reflection frameworks from the spec** so the recommendation table can't drift:
```
get_approach({ id: "reflect" })
```
The returned `framework_id_examples` carries the canonical reflection
framework ids (currently: `five-whys`, `pre-mortem`, `red-team`,
`devils-advocate`, `second-order-thinking`, plus the reflective ceremonies
`retrospective` and `four-forces-of-progress`). When the spec gains a new
reflection framework, it surfaces here automatically; no skill edit
required.
Recommend one based on what you just saw:
| Signal in the scope | Recommend (framework id) |
|---|---|
| A live problem or stuck-feeling symptom | `five-whys` |
| A plan, OKR, launch, or decision about to land | `pre-mortem` |
| A strategy or hypothesis the user is confident in | `red-team` |
| A decision that converged fast or has no documented dissent | `devils-advocate` |
| A "this is obviously the right move" energy | `second-order-thinking` |
If the table doesn't fit (e.g. a newly-shipped framework that isn't listed),
fall back to the full enumeration from `get_approach`. If unclear, present
the full list as numbered options and let the user pick. Always allow
override.
### Step 4: Walk the Framework
The canonical content for each framework; its purpose, core question,
when-to-use signals, when-NOT-to-use signals, and structural slots; lives
in the spec, not in this skill. Source of truth is
`packages/upg-spec/src/frameworks/definitions/` (exposed via the MCP
`get_framework` tool). Loading it at runtime means a framework refinement
or addition surfaces here without a skill edit.
Once the user picks a framework, fetch its definition:
```
get_framework({ id: "<chosen_id>" })
```
The returned `UPGFramework` record carries everything you need:
| Field | What to do with it |
|---|---|
| `name` | Headline you announce ("Walking you through **Pre-mortem**…"). |
| `description` | One-sentence framing; say it once, then walk the framework. Don't lecture. |
| `education.purpose` | The "why we're doing this" line. Use it as the opening frame. |
| `education.core_question` | The driving question that organises the walk; anchor each prompt to it. |
| `education.when_to_use[]` | Confirm the scope fits one of these. If not, ask the user whether to switch frameworks. |
| `education.when_not_to_use[]` | Active guard-rails; if the scope matches one of these, surface it as a caveat before continuing. |
| `slots[]` | The structural shape of the output. Each slot has a `label`, `entityTypeId`, and `description`; these are the *containers* the framework fills. Walk the user slot-by-slot, taking their input into the slot's shape. |
| `structure.pattern` | If `tree`, the conversation should branch (each answer becomes the next question). If `flat`, treat slots as a checklist. If other shapes appear in spec, follow their conventional shape. |
**Walk pattern (generic):**
1. Announce the framework by `name`. State `education.purpose` in one line.
2. Confirm the scope sits in `education.when_to_use[]`. If a `when_not_to_use[]`
item applies, name it as a caveat; "this framework can flatten systems
problems with feedback loops, so we'll watch for that", and continue
only if the user agrees.
3. Lead with `education.core_question`. Don't ask it directly; turn it into
a prompt for the user's specific scope.
4. Walk the slots. For each slot:
- Use the slot's `label` as the section heading.
- Use the slot's `description` to frame the prompt.
- Capture the user's answer into the shape implied by the slot.
- For `tree` patterns, the previous answer becomes the new question
(Five Whys, fishbone-style frameworks).
- For `flat` patterns, work through slots in order until covered.
5. If the framework definition implies multiple iterations or multiple
distinct stories (e.g. Pre-mortem's 4-6 failure stories, Red Team's
three roles, Second-order Thinking's 3-4 chains), repeat the slot walk
that many times; pull the iteration count from the slot description
when it's spelled out (e.g. "typically five iterations"), otherwise
default to 3-5.
6. Close the walk by naming what the user should sit with; the hardest
answer to dismiss, the least-prepared-for consequence, the cause they
keep deflecting from. This is the framework's payload.
Don't paste the spec back at the user. Walk them through it.
### Step 5: Capture What Surfaced
Reflection produces structured output that the graph should remember. After the framework walk, ask:
> **What surfaced that you want to capture?**
Common patterns and where they go:
| What surfaced | Capture as |
|---|---|
| A load-bearing belief that hasn't been tested | `assumption` entity, link to the anchor |
| A risk to mitigate | `risk` entity, link to the target it threatens |
| A decision that needs revisiting | `decision` entity with rationale field, link to original decision |
| A new hypothesis to test | Suggest `/upg-hypothesis` |
| A path through the graph the user wants to walk | Suggest `/upg-impact` or `/upg-connect` |
| Just notes; nothing structural | Skip capture; suggest user re-run `/upg-reflect` after they sit with it |
Use `create_node` + `create_edge` to capture. Always confirm before writing.
### Step 6: Smart Ending
Don't dump a menu. Pick ONE next move based on what surfaced:
- **If a hypothesis emerged:** "The biggest assumption you surfaced sounds testable. Want me to run `/upg-hypothesis` to design that experiment?"
- **If a risk landed:** "That risk is concrete. Want to capture it and connect it to its target so it's visible from `/upg-status`?"
- **If a decision is now uncertain:** "Sounds like the decision needs a revisit. Want to `/upg-inspect` it to see what depends on it?"
- **If reflection produced clarity, not action:** "That was the work. Want me to `/upg-snapshot` so the graph remembers this state?"
- **If the framework felt wrong for the scope:** "We can switch frameworks. Want me to walk this through Pre-mortem instead?"
After rendering your recommendation, call:
`update_session_context({ skill_invoked: "upg-reflect", recommendation: "<the next skill you recommended>" })`
## Reflection Etiquette
A few rules that make this work:
1. **Never lecture the framework.** Walk it. The user shouldn't read a Wikipedia entry for Five Whys; they should *do* Five Whys.
2. **One framework per session.** Don't combine. If a second framework feels relevant, suggest it as a follow-up.
3. **The user's discomfort is the point.** Reflect is supposed to be slightly uncomfortable. If everything is going smoothly, you're probably letting them off the hook. Push gently.
4. **Capture is optional.** Reflection that produces *no* graph output is still successful. The thinking happened.
5. **Don't propose entities the user didn't surface themselves.** Reflect mirrors back what the user said. It does not invent risks or assumptions.
## Why This Skill Exists
Reflect is one of the 5 canonical UPG approaches (`get_approach({ approach_id: "reflect" })`). Until v0.3.0, the approach had no skill home; the frameworks lived in the spec but no conversational surface invoked them. This skill closes that gap.
It's the only canonical entry point for the Reflect approach in the user-invocable surface. Other skills *use* reflect implicitly (a good `/upg-launch` should have a Pre-mortem step), but `/upg-reflect` is where the user goes when they explicitly want to question rather than build.
Then type /upg-reflect in Claude Code.