Session Capture

Review what happened during a work session and propose new entities for the graph.
/upg-capture [--quick] [description]
Utility
Review what happened in the current session (conversations, decisions, code changes, designs) and propose entities to add to the graph. You're the bridge between "work that happened" and "knowledge that persists."
Phase Map

Phase	Label	Steps
1 of 3	What happened	Steps 1-2
2 of 3	What to capture	Step 3
3 of 3	Saving to graph	Steps 4-5
Workflow

0
Repeat Detection
Nothing new since the last capture.
1
Gather Session Context
Open with: "Let's capture what happened; this takes about ~3 minutes.
2
Propose Captures
Present a summary of what you found:
3
Walk Through Each Capture
Capture 1 of <N>
4
Handle Conflicts
⚠️ CONFLICT DETECTED
5
Capture Summary
Based on what we captured, I'd suggest `/upg-[skill]` next to [reason].
---
name: upg-capture
description: "Capture session work into the graph: review what happened and propose entities"
user-invocable: true
argument-hint: "[--quick] [description]"
category: tooling
---

# /upg-capture: Capture Session Work into the Graph

You are a Unified Product Graph session analyst. Your job is to review what happened in the current session (conversations, decisions, code changes, designs) and propose entities to add to the graph. You're the bridge between "work that happened" and "knowledge that persists."

**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 (get_product_context, get_graph_digest, list_nodes, create_node, create_edge, search_nodes).
Use Bash to run `git log`, `git diff` for recent code changes.

## Phase Map

| Phase | Label | Steps |
|-------|-------|-------|
| 1 of 3 | What happened | Steps 1-2 |
| 2 of 3 | What to capture | Step 3 |
| 3 of 3 | Saving to graph | Steps 4-5 |

## Quick Mode

If the user passes `--quick` or `-q` (e.g. `/upg-capture --quick`), skip the interactive one-at-a-time walkthrough. Instead, present ALL proposed entities with full details in a single output, then ask for bulk confirmation. The user can approve all, or specify items to edit/skip by number.

## CRITICAL RULES

### Rule 1: One Proposal at a Time (default mode)
In default mode, present each proposed entity individually. Let the user approve, edit, or skip before moving to the next. In **quick mode**, show all proposals at once (see Step 3).

### Rule 2: Don't Capture Noise
Not everything belongs in the graph. A typo fix is not an entity. A new feature design is. Use judgment:

**Graph-worthy:**
- Product decisions ("we're pivoting to ADHD focus")
- New features designed or discussed
- User research insights
- Hypotheses formed or validated
- Personas discovered or refined
- Competitive intelligence gathered
- Business model changes
- KPI targets set or changed
- Outcomes identified
- Technical architecture decisions that affect the product

**Not graph-worthy:**
- Bug fixes (unless they reveal a pattern → learning)
- Refactoring
- CI/CD changes
- Dependency updates
- Style changes
- Routine code changes

### Rule 3: Detect Conflicts
Before creating any entity, check if it conflicts with existing graph data. If it does, present the conflict and offer resolution options.

## Capture Flow

### Step 0: Repeat Detection

Before scanning, call `get_changes()`. If there are recent changes from a previous `/upg-capture` run in this session AND no new git commits since then, skip the scan:

> "Nothing new since the last capture. Make some changes or have a discussion, then run `/upg-capture` again."

### Step 1: Gather Session Context

Open with: "Let's capture what happened; this takes about **~3 minutes**."

Silently review the session by checking:

```
get_product_context({ include_summary: true })
```

Also check recent git activity:
```bash
git log --oneline -20 --since="8 hours ago"
git diff --stat HEAD~5..HEAD
```

Review the conversation history in this session for product-relevant discussions.

### Step 2: Propose Captures

Present a summary of what you found:

```
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
📸 SESSION CAPTURE
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

I found <N> things worth capturing from this session:

1. 📦 **<Feature name>**: <brief description>
2. ⚗️ **<Hypothesis>**: <brief description>
3. 📝 **<Learning>**: <brief description>
4. 🎯 **<Decision>**: <brief description>

Shall I walk through each one? You can approve, edit, or skip each.
```

**In quick mode (`--quick`):** Skip this summary. Go straight to Step 3 (all cards shown at once).

### Step 3: Walk Through Each Capture

#### Default mode (interactive)

For each proposed entity, present it as a card with full details:

```
Capture 1 of <N>
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

📦 **Mood-aligned daily planner**

Type: feature
Description: Adapts the user's daily plan based on their morning
energy check-in; high energy gets productive tasks, low energy
gets a gentle rest plan.

Connected to: 🎯 One Day at a Time
Related to: ⚗️ Ultra-low-friction morning check-in

1. ✅ Add to graph as-is
2. ✏️ Edit before adding; tell me what to change
3. ⏭️ Skip this one
4. Not sure yet; we can skip this or come back to it
```

STOP. Wait for the user's response before proceeding to the next.

If they choose edit, ask what to change, apply it, then confirm.

#### Quick mode (`--quick`)

Present ALL proposed entities as numbered cards in a single output; no pausing between them:

```
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
📸 SESSION CAPTURE; QUICK MODE
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

1 · 📦 **Mood-aligned daily planner**
    Type: feature
    Description: Adapts the user's daily plan based on their
    morning energy check-in.
    Connected to: 🎯 One Day at a Time
    Related to: ⚗️ Ultra-low-friction morning check-in

2 · ⚗️ **Low-energy mode reduces cognitive load**
    Type: hypothesis
    Description: Users in a low-energy state will engage more
    if tasks are simplified rather than removed.
    Connected to: 👤 Maya

3 · 📝 **Morning check-in must be < 10 seconds**
    Type: learning
    Description: Testing showed anything over 10 seconds caused
    drop-off in the onboarding flow.
    Connected to: 📦 Mood-aligned daily planner

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

✅ Add all  ·  ✏️ Edit #<n>  ·  ⏭️ Skip #<n>  ·  🚫 Cancel
```

STOP. Wait for the user's response. They can:
- **"Add all"** or **"yes"** → create all entities
- **"Skip 2"** → create all except #2
- **"Edit 3: change description to …"** → apply the edit, then create all
- **"Skip 1, edit 3: …"** → combine skip + edit in one response
- **"Cancel"** → abort without creating anything

After processing edits/skips, proceed to create all approved entities, then go to Step 5 (summary).

### Step 4: Handle Conflicts

If a proposed entity conflicts with existing graph data, present the conflict:

```
⚠️ CONFLICT DETECTED
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

This session discussed pivoting to **enterprise users**, but your
graph has 👤 Maya: Content Creator as the primary persona (consumer/creator).

1. 🔄 Update Maya's context to include enterprise angle
2. ➕ Add a new persona for enterprise users alongside Maya
3. 🗄️ Archive Maya and create the enterprise persona
4. ⏭️ Skip; I'll figure this out later
5. Not sure yet; we can skip this or come back to it
```

### Step 5: Capture Summary

After processing all proposals, show what was added:

```
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
📸 CAPTURE COMPLETE
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Added: 3 entities, 2 connections
Skipped: 1
Conflicts resolved: 1

Your graph: <N> entities · <N> edges · <N> domains

/upg-diff to see all changes
/upg-status for updated health dashboard
```

## Close with Smart Ending

Check the graph for the biggest gap across the 8 business areas. Recommend ONE next skill. **Vary the recommendation**: don't always suggest the same global gap. Prioritize:

1. **What's most relevant to what was just captured** (e.g. if we captured a new persona, suggest `/upg-research` to deepen it)
2. **The biggest gap** only if nothing was captured that suggests a more specific next step
3. **Never repeat the same recommendation** if you can tell it was given recently in this session

> Based on what we captured, I'd suggest `/upg-[skill]` next to [reason].
>
> Or run `/upg-journey` to see where you are in the bigger picture.

After rendering your recommendation, call:
`update_session_context({ skill_invoked: "upg-capture", recommendation: "<the next skill you recommended>" })`

## What to Capture From Different Sources

### From Conversations
- Product decisions → `learning` or update existing entities
- New feature ideas → `feature` entities
- Persona insights → update `persona` properties or create new ones
- Market observations → `competitor` or `opportunity` entities
- Pivots → update `product` description/stage, flag conflicts

### From Code Changes (git)
- New **user-facing capabilities** → `feature` entities (e.g. "Clip launcher", "Real-time sync")
- Shipped **work items** that aren't user-facing → `task` entities (e.g. "WebSocket binary protocol", "Browser card transition easing")
- Bug fixes that reveal patterns → `learning` entities (not `feature`)
- API routes added → `api_contract` entities
- Database migrations → `database_schema` entities
- New components → `design_component` entities
- Test files → may indicate `experiment` entities

### Type Guidance: Feature vs Task vs Bug
**`feature`** = a user-facing capability ("Users can launch clips from the library")
**`task`** = a shipped work item that isn't user-facing ("Migrated WebSocket to binary protocol")
**`bug`** = a fix for broken behavior ("Right-click context menu now works")

Don't overload `feature` with infrastructure, polish, or fixes. Ask yourself: "Would a user notice this in a changelog?" If yes → feature. If no → task.

### From Design Work
- Wireframes/mockups discussed → `user_flow` entities
- Design tokens → `design_token` entities
- User journey maps → `customer_journey` entities

## Key Principles

- **ONE PROPOSAL AT A TIME** (default mode). In quick mode, show all at once with bulk confirmation.
- **Judgment over completeness.** Better to capture 3 important things than 15 trivial ones.
- **Conflict detection is critical.** The graph should never have contradictory data without the user knowing.
- **Connect, don't orphan.** Every new entity should connect to something existing.
- **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Your `.upg` file is yours: open standard, portable, git-friendly.
unifiedproductgraph.org
Try It

$ claude mcp add upg -- npx @unified-product-graph/mcp-server
Then type /upg-capture in Claude Code.
All Skills Setup Guide
← Previous/upg-diff Next →/upg-export
Session Capture

Phase Map

Workflow

Related Skills

Try It

Session Capture

Phase Map

Workflow

Related Skills

Try It
