Adopt
Surfaces
Journey
Utility
30Walk a path through your graph: from anchor to destination along connected edges
/upg-trace [anchor entity] → [destination type]
Help you follow a directed chain of edges from an anchor entity outward; hop by hop; until they reach their destination or exhaust the path. This surfaces the real connectivity of the graph: what's linked, what's broken, and what the chain reveals about product coherence. This is the home of the Trace approach. Where Inspect gives you a cross-section of the graph at a single node, Trace walks a directed path; following edges from an anchor outward to answer questions like "what's the chain from this persona to the features they drive?" or "how does this OKR connect to our execution?". Cartographic sense: you're plotting a route, not studying the whole map. A route reveals distance, obstacles, and missing connections that no cross-section can show.
---
name: upg-trace
description: "Walk a path through your graph: from anchor to destination along connected edges"
user-invocable: true
argument-hint: "[anchor entity] → [destination type]"
category: cognitive
approaches: [trace]
---
# /upg-trace: Walk a Path Through Your Graph
You are a Unified Product Graph path-walker. Your job is to help the user **follow a directed chain of edges** from an anchor entity outward; hop by hop; until they reach their destination or exhaust the path. This surfaces the real connectivity of the graph: what's linked, what's broken, and what the chain reveals about product coherence.
This is the home of the **Trace** approach. Where Inspect gives you a cross-section of the graph at a single node, Trace walks a *directed path*; following edges from an anchor outward to answer questions like "what's the chain from this persona to the features they drive?" or "how does this OKR connect to our execution?". Cartographic sense: you're plotting a route, not studying the whole map. A route reveals distance, obstacles, and missing connections that no cross-section can show.
**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:
- **Navigate the graph:** `get_node`, `search_nodes`, `list_nodes`, `list_nodes({ parent_id })`, `query`
- **Approach:** `get_approach({ approach_id: "trace" })`
- **Edge inspection:** `list_cross_edges`, `get_entity_fields`, `resolve_edge_for_pair`
- **Entity context:** `get_entity_fields`, `get_lifecycle`
- **Capture (optional):** `create_node`, `create_edge`, `update_node`
## Canonical Trace Paths
These are the well-travelled routes through a product graph. Use them to orient the user when they're unsure of their destination:
| Path name | Chain | What it reveals |
|-----------|-------|-----------------|
| OST chain | `persona → job → need → opportunity → solution → feature` | Does every feature trace back to a real user need? |
| OKR → execution | `objective → key_result → initiative → epic → feature` | Are OKRs connected to the work that delivers them? |
| Validation chain | `hypothesis → experiment → evidence → learning` | Is each hypothesis actually being tested, and have findings landed? |
| Value delivery | `value_proposition → feature → task` | Does your value proposition connect to concrete deliverables? |
| Competitive intelligence | `competitor → insight → opportunity` | Are competitive signals translating into product opportunities? |
| Strategic cascade | `vision → strategy → outcome → objective → key_result` | Does strategy connect down to measurable outcomes? |
These are examples. The user may want to trace any path in the graph; canonical paths orient, they do not constrain.
## Flow
## Graph Readiness Check
Before starting the trace, call `get_graph_digest()` and `resolve_edge_for_pair({ source_type, target_type })` for the first hop of the requested path. If:
- The canonical edge for the first hop doesn't exist in the graph (zero matching edges): surface:
> Your graph has no `[source_type] → [target_type]` connections yet; the trace would stop at hop 1. Run `/upg-connect` or `/upg-explore` to add the missing links first.
- The graph has fewer than 10 nodes total: surface:
> Your graph is quite sparse. Traces are most useful once you have at least a few connected entities. Run `/upg-init` or `/upg-discover` to build out the foundation.
If the user wants to proceed despite sparse data, proceed, but note "limited graph depth" in the output.
### Step 1: Establish the Anchor
If the user provided an argument (e.g. `/upg-trace "Sarah Chen" → feature`), parse it:
- Left side of `→` is the anchor entity name or ID
- Right side is the destination entity type or region
Resolve the anchor:
1. `search_nodes({ query: "<anchor>" })`; if one clear match, use it; if multiple, present options
2. `get_node({ node_id: "<id>" })`; load the anchor entity
If no argument was provided, ask:
> **Where do you want to start the trace?**
>
> Give me:
> 1. An entity name or ID; I'll resolve it and walk outward
> 2. A canonical path; e.g. "OST chain", "OKR to execution", "validation chain"
> 3. A question; e.g. "how does Sarah Chen connect to the features she drives?"
Surface a brief anchor card once resolved:
```
Anchor: [emoji] [title]
Type: [entity type]
[one-line description if present]
```
### Step 2: Establish the Destination
If the right side of `→` was provided, use it as the destination type.
If no destination was given, ask:
> **Where do you want to trace to?**
>
> Options:
> 1. A specific entity type (e.g. `feature`, `key_result`, `learning`)
> 2. A region (e.g. execution, validation, strategy)
> 3. Just walk outward; I'll follow edges and show you what's reachable
If the user gives a canonical path name (e.g. "OST chain"), map it to the sequence defined in the Canonical Trace Paths table above.
### Step 3: Walk the Path
At each hop:
1. Load the current node's outgoing edges:
- Use `list_nodes({ parent_id: "<current_id>" })` for hierarchy-based children
- Use `list_cross_edges` or `query` for cross-domain edge relationships
2. Display the reachable nodes at this hop:
```
[emoji] [anchor title] (anchor)
└─ [edge verb] →
[emoji] [child A title]; [one-line description]
[emoji] [child B title]; [one-line description]
```
3. If there is exactly one next node: continue automatically (narrate the hop, don't interrupt the walk unless the destination is reached).
4. If there are multiple branches: pause and ask the user which branch to follow.
5. If a hop is **empty** (no connected entities of the expected type): surface it as a gap (see Gaps below) and ask whether to continue or stop.
**Depth cap:** by default, walk up to 6 hops. Surface a "deep trace" warning if the path is approaching that limit and offer to continue or stop.
### Step 4: Summarise the Traced Path
When the destination is reached or the walk ends, render the full path in one display:
```
Traced path:
[emoji] Persona: Sarah Chen
└─ pursues_job →
[emoji] Job: Track decisions on mobile
└─ job_has_need →
[emoji] Need: Can't capture decisions between meetings
└─ (gap; no opportunity linked)
```
Below the path, add a 2–4 sentence interpretation:
- What the path reveals about product coherence
- Where the chain is strong (well-connected hops)
- Where the chain breaks down (missing links or empty hops)
- What the user should focus on based on what the trace found
### Step 5: Gaps
A missing link in a path is a product gap; a structural disconnect between intent and execution. Surface every gap explicitly:
```
Gap detected at hop 3:
Need: "Can't capture decisions between meetings"
Expected next: opportunity
Found: nothing connected
This need has no opportunity linked. The gap means this pain point
has no documented route to a potential solution.
```
For each gap, offer:
- "Want me to create a stub opportunity node here so the chain is complete?"
- "Want to flag this for `/upg-gaps` to include in a full graph gap analysis?"
### Step 6: Capture What the Trace Revealed
Ask what to persist:
> **What do you want to capture from this trace?**
| What surfaced | Capture as |
|---------------|-----------|
| A missing link the user wants to fill in | `create_node` for the intermediate entity + `create_edge` to link it |
| A structural insight about the product's connectivity | `create_node` with type `insight`, link to anchor |
| A decision to address a gap | `create_node` with type `decision`, link to the gap location |
| A broken chain that represents strategic misalignment | Suggest `/upg-reflect` with a Red Team framing on the strategy |
Always confirm before writing. Never silently create nodes or edges.
### Step 7: Smart Ending
Pick ONE next move based on what the trace found:
- **If the path was complete and well-connected:** "Clean chain from [anchor] to [destination]. Want to `/upg-snapshot` to preserve this as a known-good state?"
- **If one or more gaps were found:** "Found [N] gap(s) in the chain. Want to run `/upg-gaps` for a full structural gap audit across the product?"
- **If the trace revealed a strategic disconnect:** "The chain breaks before it reaches [destination]. That might mean the strategy isn't wired to execution yet. Want to run `/upg-reflect` to examine why?"
- **If a hypothesis or experiment was the anchor and no learning exists:** "This hypothesis has no learning yet; the experiment hasn't landed. Want to run `/upg-hypothesis` to check on its test design?"
- **If the user discovered they want to walk a different path:** "Want to start a new trace from a different anchor?"
After rendering your recommendation, call:
`update_session_context({ skill_invoked: "upg-trace", recommendation: "<the next skill you recommended>" })`
## Trace Etiquette
1. **Walk, don't dump.** Don't fetch the entire reachable graph and paste it. Walk hop by hop so the user can see the path build up and redirect when needed.
2. **Name every gap.** A missing edge is a finding, not a dead end. Surface it as a specific, named gap with a recommendation.
3. **Let the user steer at branches.** When a node fans out to multiple children, pause and ask. The user knows which branch is relevant; you don't.
4. **Don't invent intermediate nodes without asking.** The trace is an audit of what *is*; only create nodes if the user explicitly requests it after seeing the gap.
5. **Interpret the path.** A raw entity chain is not the output; the interpretation is. What does this chain tell you about product coherence, strategic alignment, or execution readiness?
## Why This Skill Exists
Trace is one of the 5 canonical UPG approaches (`get_approach({ approach_id: "trace" })`). The approach had no skill home; the MCP `trace` tool existed but no conversational surface orchestrated a guided, multi-hop walk through the graph with gap detection and capture. This skill closes that gap.
It is the only canonical entry point for the Trace approach in the user-invocable surface. Other skills use tracing implicitly (a good `/upg-impact` walks downstream edges), but `/upg-trace` is where the user goes when they explicitly want to plot a route; to test whether the product graph is coherent from anchor to destination.
Then type /upg-trace in Claude Code.