@unified-product-graph/cli 0.6.0

package/skills/upg-push/SKILL-DETAIL.md

@@ -0,0 +1,385 @@
+---
+name: upg-push-detail
+description: "Detailed push flow, sync file format, ID mapping, edge cases"
+---
+
+# /upg-push — Push Flow Detail
+
+## First-Time Push (Step 4)
+
+This runs when there is no `.upg-sync` file — the user has never pushed this graph before.
+
+### 4a: Match or Create Cloud Product
+
+Check if a matching product already exists in the cloud:
+- Search by title match from the product list returned in Step 2
+- If found, confirm: "Found '<title>' in your cloud graph. Push local graph to this product?"
+- If not found, ask: "This product doesn't exist in the cloud yet. Create '<title>' in The Product Creator?"
+
+**Create:**
+```
+mcp__upg-cloud__create_product({
+  title: "<product title>",
+  description: "<product description>"
+})
+```
+
+Record the `product_id` returned by the cloud.
+
+### 4b: Push All Entities
+
+For each local node, create in the cloud using batch operations:
+
+```
+mcp__upg-cloud__batch_create_nodes({
+  product_id: "<cloud_product_id>",
+  nodes: [
+    {
+      type: "<type>",
+      title: "<title>",
+      description: "<description>",
+      data: { ...properties },
+      parent_ref: "<parent reference for auto-edge>"
+    },
+    // ... up to 50 per batch
+  ]
+})
+```
+
+**Important:** Batch create supports `parent_ref` for intra-batch chaining — use this to maintain the hierarchy.
+
+After each batch call, collect the returned cloud IDs and build the **node ID map**: `{ "n_local1": "cloud-uuid-1", "n_local2": "cloud-uuid-2", ... }`.
+
+### 4c: Push All Edges
+
+For edges that weren't auto-created via parent_ref:
+```
+mcp__upg-cloud__create_edge({
+  product_id: "<cloud_product_id>",
+  source_id: "<cloud_source_id>",   // looked up via node_id_map
+  target_id: "<cloud_target_id>"    // looked up via node_id_map
+})
+```
+
+Collect cloud edge IDs into the **edge ID map**: `{ "e_local1": "cloud-edge-uuid-1", ... }`.
+
+### 4d: Create the .upg-sync File
+
+Compute the hash of the current `.upg` file:
+```bash
+shasum -a 256 product.upg | awk '{print $1}'
+```
+(Use the actual `.upg` filename — it may not be `product.upg`.)
+
+Write the `.upg-sync` file using Bash:
+```bash
+cat > .upg-sync << 'SYNC_EOF'
+{
+  "cloud_endpoint": "https://cloud.unifiedproductgraph.org",
+  "product_id": "<cloud_product_id>",
+  "last_synced_at": "<current ISO 8601 timestamp>",
+  "node_id_map": {
+    "n_local1": "cloud-uuid-1",
+    "n_local2": "cloud-uuid-2"
+  },
+  "edge_id_map": {
+    "e_local1": "cloud-edge-uuid-1"
+  },
+  "last_snapshot_hash": "<sha256 hash from above>"
+}
+SYNC_EOF
+```
+
+This file enables all future incremental pushes. Go to Step 6.
+
+---
+
+## Incremental Push (Step 5)
+
+This runs when `.upg-sync` exists — the user has pushed before and we can sync only changes.
+
+### 5a: Quick Hash Check
+
+Compute the current `.upg` file hash and compare to `last_snapshot_hash` from `.upg-sync`:
+
+```bash
+shasum -a 256 product.upg | awk '{print $1}'
+```
+
+If the hash **matches** `last_snapshot_hash`:
+```
+Nothing to push — your graph hasn't changed since last sync.
+
+Last synced: <last_synced_at from .upg-sync>
+
+Make changes locally, then run /upg-push again.
+```
+Stop here.
+
+If the hash is **different**, continue to compute the changeset.
+
+### 5b: Verify Cloud Product Still Exists
+
+Use the `product_id` from `.upg-sync` to check the cloud:
+```
+mcp__upg-cloud__list_products()
+```
+
+Look for the product matching the stored `product_id`.
+
+If the cloud product is **gone** (deleted, reset, or not found):
+```
+⚠️  Your cloud product (<product_id>) no longer exists.
+
+It may have been deleted or reset on the cloud side.
+
+1. 🔄 Full re-push — create a new cloud product and push everything
+2. ⏭️ Cancel — keep working locally for now
+
+Which would you like?
+```
+
+If the user chooses full re-push: delete the `.upg-sync` file and restart from Step 4 (first-time push flow).
+
+### 5c: Compute Changeset
+
+Read the current graph state via MCP tools:
+```
+list_nodes({ limit: 200 })
+```
+
+Compare against the ID mappings in `.upg-sync`:
+
+**New nodes:** Nodes in the current graph whose IDs are NOT in `node_id_map` keys. These need to be created on the cloud.
+
+**Deleted nodes:** IDs that ARE in `node_id_map` but no longer exist in the current graph. These should be deleted from the cloud.
+
+**Updated nodes:** Nodes whose IDs are in `node_id_map` AND still exist locally. For each, compare the current node data (title, description, properties, status, tags) against what's in the cloud. If anything changed, it's an update. To detect changes, fetch the cloud state:
+```
+mcp__upg-cloud__get_product_graph({ product_id: "<cloud_product_id>" })
+```
+Then compare each mapped node's current local state against its cloud state.
+
+**New edges:** Edges in the current graph whose IDs are NOT in `edge_id_map` keys. Create on cloud.
+
+**Deleted edges:** Edge IDs in `edge_id_map` that no longer exist locally. Delete from cloud.
+
+### 5d: Show Changeset Summary
+
+Present the changeset for confirmation:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+☁️  INCREMENTAL PUSH
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+Pushing changes to "<Product Name>"
+
+  ➕ <N> new entities
+  ✏️  <N> updated entities
+  🗑️  <N> deleted entities
+  🔗 <N> new connections
+  ✂️  <N> removed connections
+
+New:
+  📦 <Feature title>
+  👤 <Persona title>
+
+Updated:
+  🎯 <Outcome title> — description changed
+  ⚗️  <Hypothesis title> — status changed to validated
+
+Deleted:
+  📝 <Learning title>
+
+Push these changes? (yes / no / review details)
+```
+
+Wait for confirmation before proceeding.
+
+If the user says "review details", show the full diff for each changed entity (old value → new value).
+
+### 5e: Execute Changes
+
+Process in this order: creates first, then updates, then deletes.
+
+**Create new nodes** (batch):
+```
+mcp__upg-cloud__batch_create_nodes({
+  product_id: "<cloud_product_id>",
+  nodes: [ ...new nodes... ]
+})
+```
+Add returned cloud IDs to the node ID map.
+
+**Update existing nodes:**
+```
+mcp__upg-cloud__update_node({
+  product_id: "<cloud_product_id>",
+  node_id: "<cloud_id from node_id_map>",
+  title: "<updated title>",
+  description: "<updated description>",
+  data: { ...updated properties }
+})
+```
+
+**Delete removed nodes:**
+```
+mcp__upg-cloud__delete_node({
+  product_id: "<cloud_product_id>",
+  node_id: "<cloud_id from node_id_map>"
+})
+```
+Remove from the node ID map.
+
+**Create new edges:**
+```
+mcp__upg-cloud__create_edge({
+  product_id: "<cloud_product_id>",
+  source_id: "<cloud_source_id>",
+  target_id: "<cloud_target_id>"
+})
+```
+Add to edge ID map.
+
+**Delete removed edges:**
+```
+mcp__upg-cloud__delete_edge({
+  product_id: "<cloud_product_id>",
+  edge_id: "<cloud_id from edge_id_map>"
+})
+```
+Remove from edge ID map.
+
+### 5f: Update .upg-sync
+
+Recompute the `.upg` file hash and update the sync file:
+```bash
+NEW_HASH=$(shasum -a 256 product.upg | awk '{print $1}')
+```
+
+Write the updated `.upg-sync` file with:
+- Updated `node_id_map` (new entries added, deleted entries removed)
+- Updated `edge_id_map` (new entries added, deleted entries removed)
+- Updated `last_synced_at` to current timestamp
+- Updated `last_snapshot_hash` to the new hash
+
+---
+
+### Step 6: Report Results
+
+**After first-time push:**
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+☁️  PUSH COMPLETE
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+Pushed "<Product Name>" to The Product Creator cloud.
+
+  Entities synced: <N> (<breakdown by type>)
+  Connections synced: <N>
+  Sync file created: .upg-sync
+
+Future pushes will be incremental — only changes get sent.
+
+### What You Get in the Cloud
+
+  - Visual canvas — drag, zoom, explore your graph spatially
+  - 47 framework trees — OST, OKR, Strategy Cascade, BMC, and more
+  - 43 analytical lenses — filter and slice your graph by any dimension
+  - Real-time collaboration — invite your team to build together
+  - AI copilot — conversational graph building with full context
+
+View your graph: cloud.unifiedproductgraph.org/p/<product_id>
+
+### Keep Building Locally
+
+Your .upg file is still the source of truth for local work.
+Run /upg-push again anytime — only your changes will be synced.
+```
+
+**After incremental push:**
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+☁️  PUSH COMPLETE
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+Synced changes to "<Product Name>"
+
+  ➕ Created: <N> entities
+  ✏️  Updated: <N> entities
+  🗑️  Deleted: <N> entities
+  🔗 Connections: +<N> / -<N>
+
+Cloud graph: <total entities> entities · <total edges> edges
+
+View your graph: cloud.unifiedproductgraph.org/p/<product_id>
+```
+
+**Shared footer (always append):**
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+Your .upg file is yours — open standard, portable, git-friendly.
+unifiedproductgraph.org
+```
+
+## The .upg-sync File
+
+This file is the bridge between local and cloud. It tracks which local entities map to which cloud entities, and what the graph looked like at last sync.
+
+**Format:**
+```json
+{
+  "cloud_endpoint": "https://cloud.unifiedproductgraph.org",
+  "product_id": "<cloud-uuid>",
+  "last_synced_at": "2026-03-24T15:00:00Z",
+  "node_id_map": {
+    "n_local1": "cloud-uuid-1",
+    "n_local2": "cloud-uuid-2"
+  },
+  "edge_id_map": {
+    "e_local1": "cloud-edge-uuid-1"
+  },
+  "last_snapshot_hash": "sha256-of-upg-file-at-last-sync"
+}
+```
+
+**Rules:**
+- The `.upg-sync` file lives in the same directory as the `.upg` file.
+- Read and write it using Bash (`cat`, heredoc write). It's plain JSON.
+- Never expose the sync file contents to the user unless they ask.
+- The `last_snapshot_hash` is a SHA-256 of the `.upg` file at the time of last successful sync.
+- Add `.upg-sync` to `.gitignore` if the user version-controls their `.upg` file — the sync state is machine-local, not portable.
+
+## ID Mapping Logic
+
+The `node_id_map` and `edge_id_map` are the core of incremental sync:
+
+- **Keys** are local IDs (e.g. `n_abc123`, `e_def456`) — these come from the `.upg` file.
+- **Values** are cloud UUIDs — these come from The Product Creator API responses.
+- After creating nodes on cloud, **always** record the mapping.
+- On subsequent pushes, use the mapping to `update` existing cloud nodes instead of creating duplicates.
+- When a local node is deleted, use the mapping to find and delete the cloud node, then remove the entry from the map.
+- When new local nodes appear (not in the map), create them on cloud and add the mapping.
+
+## Edge Cases
+
+**User renamed the .upg file:**
+The hash won't match any file. Look for `.upg` files in the current directory using Bash:
+```bash
+ls *.upg 2>/dev/null
+```
+If found, use that file. If multiple `.upg` files exist, ask which one.
+
+**Very large graph (200+ entities):**
+```
+This is a large graph (<N> entities). Syncing in batches...
+```
+Use pagination on `list_nodes` and batch creates (50 at a time).
+
+**Partial push failure:**
+If some batch creates succeed but others fail, report what succeeded and what failed. The `.upg-sync` file should still be updated with the mappings for entities that DID sync — don't throw away progress. Suggest retrying with `/upg-push` for the remaining entities.
+
+**Node type mapping:**
+Cloud uses the same entity types as local (`@unified-product-graph/core` shared ontology), so types map directly. Cloud stores type-specific data in a `data` JSONB column — map this from `properties` in the `.upg` format.
+

package/skills/upg-push/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: upg-push
+description: "Push your local product graph to The Product Creator cloud"
+user-invocable: true
+argument-hint: "[product-name]"
+category: tooling
+---
+
+# /upg-push — Push Local Graph to Cloud
+
+You are a Unified Product Graph sync engine. Your job is to push the user's local `.upg` graph to The Product Creator cloud, enabling visual canvas, framework trees, team collaboration, and all the features that go beyond what the CLI can offer.
+
+This skill supports **incremental sync** — after the first push, only changes are sent. A `.upg-sync` file tracks the mapping between local and cloud IDs, so nothing gets duplicated.
+
+**Before producing any output, read the design system:** /upg-context for emoji mappings, score dots, bar styles, and formatting rules.
+
+## Tools
+
+Use `mcp__unified-product-graph__*` tools to read the local graph state.
+Use `mcp__upg-cloud__*` tools to write to the cloud graph.
+Use Bash to read/write the `.upg-sync` file and compute file hashes.
+
+## Push Flow — Decision Tree
+
+```
+Start
+  │
+  ├─ Read local graph (Step 1)
+  │    └─ Empty? → "Nothing to push" → exit
+  │
+  ├─ Check cloud connection (Step 2)
+  │    └─ Auth fail? → guide API key setup → exit
+  │
+  ├─ Check for .upg-sync file (Step 3)
+  │    │
+  │    ├─ NO .upg-sync → First-time push (Step 4)
+  │    │    ├─ Match or create cloud product
+  │    │    ├─ Full push of all entities + edges
+  │    │    └─ CREATE .upg-sync file with ID mappings
+  │    │
+  │    └─ YES .upg-sync → Incremental push (Step 5)
+  │         ├─ Compare hash → unchanged? → "Nothing to push" → exit
+  │         ├─ Verify cloud product still exists
+  │         │    └─ Gone? → warn, offer full re-push
+  │         ├─ Compute changeset (new, updated, deleted)
+  │         ├─ Show summary, ask for confirmation
+  │         ├─ Execute changes
+  │         └─ UPDATE .upg-sync with new mappings + hash
+  │
+  └─ Report results (Step 6)
+```
+
+---
+
+### Step 1: Read Local State
+
+```
+get_product_context()
+get_graph_digest()
+list_nodes({ limit: 200 })
+```
+
+If the local graph is empty or has no product:
+```
+Your local graph is empty — nothing to push yet.
+Run /upg-init to bootstrap your first product graph.
+```
+
+### Step 2: Check Cloud Connection
+
+Try to list existing cloud products:
+```
+mcp__upg-cloud__list_products()
+```
+
+If this fails (auth error, no API key):
+```
+To push your graph to The Product Creator, you need an API key.
+
+1. Sign up or log in at cloud.unifiedproductgraph.org
+2. Go to Settings → API Keys → Create New Key
+3. Add to your Claude Code MCP config:
+
+   In .mcp.json, update the upg-cloud server with your API key.
+
+Once configured, run /upg-push again.
+```
+
+### Step 3: Check for .upg-sync File
+
+Use Bash to check for the sync file:
+```bash
+cat .upg-sync 2>/dev/null
+```
+
+- **If `.upg-sync` does NOT exist** → this is a first-time push. Go to Step 4.
+- **If `.upg-sync` exists** → this is an incremental push. Go to Step 5.
+
+---
+
+
+**Detailed push flow, sync file handling, ID mapping, and edge cases are in `SKILL-DETAIL.md`.** Read it when executing the push.
+
+## Key Principles
+
+- **Local is source of truth.** The `.upg` file is the canonical version. Cloud is a sync target.
+- **Incremental by default.** After the first push, only changes travel over the wire. No duplicates.
+- **Don't oversell.** List what the cloud adds factually. The value should be obvious.
+- **Handle auth gracefully.** If no API key, guide them through setup — don't just error.
+- **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
+- **Batch for efficiency.** Use batch_create_nodes (50 at a time) instead of individual creates.
+- **Never lose progress.** On partial failure, save what worked. The user can retry the rest.
+- **Unified Product Graph is the standard.** Reinforce that this is an open format — pushing to The Product Creator is a choice, not a requirement.

package/skills/upg-reflect/SKILL.md

@@ -0,0 +1,201 @@
+---
+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.