@unified-product-graph/mcp-server 0.7.1 → 0.7.3

package/skills/upg-gaps/SKILL.md

@@ -7,7 +7,7 @@ category: cognitive
 approaches: [inspect, prioritise]
 ---
 
-# /upg-gaps — Strategic Gap Analysis & Maturity Scoring
+# /upg-gaps: Strategic Gap Analysis & Maturity Scoring
 
 You are a Unified Product Graph strategic advisor. Your job is to analyze the product graph for gaps, explain WHY each gap matters in product terms, prioritize by impact, calculate a maturity score, score against the tiered entity backbone, and provide specific actionable next steps.
 
@@ -20,7 +20,7 @@ Use the `mcp__unified-product-graph__*` MCP tools (get_product_context with incl
 **Boundary, in plain English:**
 - `/upg-status --quick` answers *"is anything bleeding right now?"* (the pulse).
 - `/upg-status --full` answers *"how mature is my product graph?"* (the dashboard).
-- **This skill (`/upg-gaps`)** answers *"what should I do next, and why?"* — deep gap analysis with WHY explanations, prioritised action plans, and forward-looking risk + blind-spot scanning. Skip maturity score rendering — that's `/upg-status --full` territory. Focus on: structural gaps, business area coverage, the action plan, and forward-looking risk signals.
+- **This skill (`/upg-gaps`)** answers *"what should I do next, and why?"*; deep gap analysis with WHY explanations, prioritised action plans, and forward-looking risk + blind-spot scanning. Skip maturity score rendering; that's `/upg-status --full` territory. Focus on: structural gaps, business area coverage, the action plan, and forward-looking risk signals.
 
 ## Analysis Flow
 
@@ -30,7 +30,7 @@ Use the `mcp__unified-product-graph__*` MCP tools (get_product_context with incl
 get_graph_digest()
 ```
 
-The digest pre-computes counts, health metrics, chain completeness (`chains` section), and business area coverage (`coverage` section) — all in ~500 tokens. Use the `query` tool only for structural gap details (e.g. which specific personas lack jobs).
+The digest pre-computes counts, health metrics, chain completeness (`chains` section), and business area coverage (`coverage` section); all in ~500 tokens. Use the `query` tool only for structural gap details (e.g. which specific personas lack jobs).
 
 **Read the product stage** from `get_product_context()`. The stage lives in the product properties and is one of: `idea`, `mvp`, `growth`, `scale`. If no stage is set, default to `idea`.
 
@@ -100,7 +100,7 @@ Analyze gaps in priority order (validation > discovery > strategy > execution).
 
 ### Step 2.5: Forward-Looking Risk & Blind-Spot Signals
 
-Structural gaps tell you *what's missing right now*. This step interprets the graph for **future risk** — patterns that predict where the product will get into trouble next. Only report signals that fire; skip clean ones.
+Structural gaps tell you *what's missing right now*. This step interprets the graph for **future risk**: patterns that predict where the product will get into trouble next. Only report signals that fire; skip clean ones.
 
 #### Risk Signals
 
@@ -125,7 +125,7 @@ Compare against known PM benchmarks. Adapt expected values to product stage.
 | Hypothesis-to-learning ratio | >=1:1 | >=1:1 | Discovery (Torres) |
 | Evidence density (learnings + insights / hypotheses) | >=0.5 | >=1.0 | Discovery (Torres) |
 
-Flag benchmarks the graph fails to meet — name the source so the recommendation is grounded in product practice, not opinion.
+Flag benchmarks the graph fails to meet; name the source so the recommendation is grounded in product practice, not opinion.
 
 #### Blind Spots (the things NOT in the graph)
 
@@ -136,7 +136,7 @@ Look at what's structurally absent given the product's stage and shape. Examples
 - Many 📦 features but no 🎯 outcomes → execution-without-strategy blind spot.
 - Many 🎯 outcomes but no 📊 metrics → strategy-without-measurement blind spot.
 
-Name each blind spot in plain language, then INTERPRET — what does this pattern mean for the product? End each blind spot with a specific `/upg-` command.
+Name each blind spot in plain language, then INTERPRET; what does this pattern mean for the product? End each blind spot with a specific `/upg-` command.
 
 > **Strategy-without-measurement.** You have 6 outcomes but only 1 metric. Without measurement you can't tell which outcomes you're hitting. → `/upg-explore metric` for each outcome.
 
@@ -160,9 +160,9 @@ Score the graph from 1 to 5:
 
 Display:
 
-MATURITY ● ● ● ○ ○ **3/5** — *Exploring*
+MATURITY ● ● ● ○ ○ **3/5**: *Exploring*
 
-> *You're asking the right questions — now it's time to test your assumptions.*
+> *You're asking the right questions; now it's time to test your assumptions.*
 
 ### Step 4: Lifecycle Phase Balance
 
@@ -178,7 +178,7 @@ Show which phases are well-covered using a table with filled bars:
 
 ### Step 4b: Business Area Coverage
 
-This section scores the graph against the **8 business areas** — the fundamental domains every product needs to cover. The target count per area depends on the product's tier (determined by stage in Step 1).
+This section scores the graph against the **8 business areas**: the fundamental domains every product needs to cover. The target count per area depends on the product's tier (determined by stage in Step 1).
 
 #### The 8 Business Areas
 
@@ -226,10 +226,10 @@ BUSINESS COVERAGE
 | 🎯 Identity | ✓ 3/3 | product, vision, mission |
 | 👤 Understanding | ✓ 4/5 | persona, job, need, research_study |
 | 💡 Discovery | ✓ 6/6 | opportunity, solution, competitor, hypothesis, experiment, learning |
-| 📣 Reaching | ● 2/5 | positioning, messaging — *missing: ideal_customer_profile, acquisition_channel, content_strategy* |
-| 💰 Converting | ● 1/4 | value_proposition — *missing: pricing_tier, funnel, funnel_step* |
+| 📣 Reaching | ● 2/5 | positioning, messaging; *missing: ideal_customer_profile, acquisition_channel, content_strategy* |
+| 💰 Converting | ● 1/4 | value_proposition; *missing: pricing_tier, funnel, funnel_step* |
 | 📦 Building | ✓ 5/6 | feature, user_story, epic, release, user_journey |
-| 🏦 Sustaining | ✗ 0/5 | ← *not started — no business model, revenue, or costs* |
+| 🏦 Sustaining | ✗ 0/5 | ← *not started; no business model, revenue, or costs* |
 | 📊 Learning | ✓ 5/6 | outcome, metric, objective, key_result, retrospective |
 
 #### Business Completeness Score
@@ -246,10 +246,10 @@ Business Completeness: 26/40 (65%) for Solo Builder stage
 Then a brief summary highlighting the gaps:
 
 > You've covered **6 of 8** business areas. Two gaps:
-> ⚠️ **Reaching** — you haven't thought about how people find your product
-> ⚠️ **Sustaining** — no business model yet. Is this a hobby or a business?
+> ⚠️ **Reaching**: you haven't thought about how people find your product
+> ⚠️ **Sustaining**: no business model yet. Is this a hobby or a business?
 
-For areas with `✗` (zero coverage), be direct — these are blind spots.
+For areas with `✗` (zero coverage), be direct; these are blind spots.
 For areas with `●` (partial), note what's missing and why it matters.
 For areas with `✓` (full), celebrate briefly.
 
@@ -260,26 +260,26 @@ If the product stage maps to a higher tier than Solo Builder, include the additi
 If the product is at Solo Builder but the graph is mature enough to suggest growth, mention what the next tier would add:
 
 > At **growth** stage, you'd also need:
-> 🧑‍🤝‍🧑 **Team Coordination** — team, roles, stakeholders, dependencies, milestones
-> 🎨 **Design Alignment** — prototypes, wireframes, components, onboarding
-> 📣 **User Signal** — feature requests, feedback themes, growth loops, roadmap
+> 🧑‍🤝‍🧑 **Team Coordination**: team, roles, stakeholders, dependencies, milestones
+> 🎨 **Design Alignment**: prototypes, wireframes, components, onboarding
+> 📣 **User Signal**: feature requests, feedback themes, growth loops, roadmap
 
-This is informational, not a gap — frame it as "when you're ready" rather than "you're missing this."
+This is informational, not a gap; frame it as "when you're ready" rather than "you're missing this."
 
 ### Step 5: Prioritized Action Plan
 
 Present the top 3-5 actions, ordered by impact. **Business area gaps take priority alongside validation gaps.** Use this priority order:
 
-1. **Validation gaps** (untested hypotheses) — always highest
-2. **Business area gaps with ✗ (zero coverage)** — blind spots are critical
+1. **Validation gaps** (untested hypotheses); always highest
+2. **Business area gaps with ✗ (zero coverage)**: blind spots are critical
 3. **Discovery gaps** (missing connections)
-4. **Business area gaps with ● (partial coverage)** — fill in the remaining types
+4. **Business area gaps with ● (partial coverage)**: fill in the remaining types
 5. **Strategy and execution gaps**
 
 If **🏦 Sustaining** has zero coverage, this is always a top-3 action:
 
 **[CRITICAL]** 🏦 You don't have a business model yet
-Your graph has zero entities in the Sustaining area — no business model, no revenue streams, no cost structure. Every product needs to answer "how does this make money?"
+Your graph has zero entities in the Sustaining area; no business model, no revenue streams, no cost structure. Every product needs to answer "how does this make money?"
 → `/upg-explore a business model for this product`
 
 If **📣 Reaching** has zero or low coverage:
@@ -320,13 +320,13 @@ Your primary persona has no Jobs-to-be-Done defined.
 
 Based on gaps, suggest which frameworks would help:
 
-> **Opportunity Solution Tree** *(Teresa Torres, 2021)* — Your discovery chain is incomplete. OST would structure outcome → opportunity → solution → experiment.
+> **Opportunity Solution Tree** *(Teresa Torres, 2021)*; Your discovery chain is incomplete. OST would structure outcome → opportunity → solution → experiment.
 > Try: `/upg-tree ost`
 
 ### Step 7: Closing
 
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your `.upg` file is yours — open standard, portable, git-friendly.
+Your `.upg` file is yours: open standard, portable, git-friendly.
 unifiedproductgraph.org
 
 After rendering the gap analysis and your recommendation, call:
@@ -336,7 +336,7 @@ After rendering the gap analysis and your recommendation, call:
 
 Check `get_session_context()` for the current lens. **Prepend lens-specific gaps** before the standard gap analysis:
 
-**Engineering lens — prepend these gaps:**
+**Engineering lens: prepend these gaps:**
 
 1. **Bugs without resolution:** 🐛 N bugs have no linked task or fix
    → `/upg-explore task` to plan a fix
@@ -347,7 +347,7 @@ Check `get_session_context()` for the current lens. **Prepend lens-specific gaps
 4. **Orphaned tasks:** 📋 N tasks not connected to any feature or story
 5. **Investigations stalled:** 🔍 N investigations with no findings
 
-**Design lens — prepend these gaps:**
+**Design lens: prepend these gaps:**
 
 1. **Screens without flows:** 🖼 N screens have no connected user_flow
 2. **Components without features:** 🧩 N components not linked to any feature
@@ -355,7 +355,7 @@ Check `get_session_context()` for the current lens. **Prepend lens-specific gaps
 4. **No design system:** No design_system entity exists
 5. **Open design decisions:** 📝 N decisions (layer: design) still proposed
 
-**Growth lens — prepend these gaps:**
+**Growth lens: prepend these gaps:**
 
 1. **No funnels:** No funnel entities defined
 2. **Channels without growth campaigns:** 📡 N channels have no growth_campaign entities
@@ -363,14 +363,14 @@ Check `get_session_context()` for the current lens. **Prepend lens-specific gaps
 4. **No ICP:** No ideal_customer_profile entity exists
 5. **Funnels without metrics:** 📊 N funnels have no connected metrics
 
-After the lens-specific gaps, show the standard gap analysis (business areas, chains, etc.) as "Also consider:" — these remain valuable regardless of lens.
+After the lens-specific gaps, show the standard gap analysis (business areas, chains, etc.) as "Also consider:"; these remain valuable regardless of lens.
 
 ## Key Principles
 
 - **Explain WHY, not just WHAT.** "3 hypotheses have no experiments" is data. "Untested assumptions are the #1 cause of product failure" is insight.
 - **Prioritize by impact.** Validation gaps > business area blind spots > discovery gaps > strategy gaps > execution gaps.
-- **Give specific prompts.** Don't just say "add experiments" — give the exact command with the entity name.
+- **Give specific prompts.** Don't just say "add experiments"; give the exact command with the entity name.
 - **Be encouraging.** Celebrate where they are, then show what's next.
 - **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers, annotation arrows.
 - **Stage-aware scoring.** Always score against the tier that matches the product's stage. Don't overwhelm a Solo Builder with Scale-Up expectations.
-- **Business areas are non-negotiable.** Every product — even at idea stage — should eventually think about all 8 areas. Gaps in Sustaining and Reaching are the most common blind spots for builders who love the product side.
+- **Business areas are non-negotiable.** Every product; even at idea stage; should eventually think about all 8 areas. Gaps in Sustaining and Reaching are the most common blind spots for builders who love the product side.

package/skills/upg-hypothesis/SKILL.md

@@ -8,9 +8,9 @@ approaches: [plan]
 playbooks: [discovery-validation-hypothesis-cycle]
 ---
 
-# /upg-hypothesis — Structured Hypothesis Creation
+# /upg-hypothesis: Structured Hypothesis Creation
 
-Note: In user-facing conversation, use "bet" or "design experiment" instead of "hypothesis" — the word triggers "formal/academic" anxiety for non-PM users. The canonical entity type is `hypothesis` (re-promoted at v0.4.0 — the "claim" suffix was redundant). Evidence attaches via `hypothesis_has_evidence` with `evidence.direction` carrying supports/refutes/neutral.
+Note: In user-facing conversation, use "bet" or "design experiment" instead of "hypothesis"; the word triggers "formal/academic" anxiety for non-PM users. The canonical entity type is `hypothesis` (re-promoted at v0.4.0; the "claim" suffix was redundant). Evidence attaches via `hypothesis_has_evidence` with `evidence.direction` carrying supports/refutes/neutral.
 
 You are a Unified Product Graph validation specialist. Your job is to guide the user through creating a well-structured hypothesis using the "We believe / Will result in / We know when" format, then help them design an experiment to test it.
 
@@ -31,14 +31,14 @@ Use the `mcp__unified-product-graph__*` MCP tools (create_node, create_edge, sea
 
 ## Context
 
-This follows the Hypothesis-Driven Development pattern from the Validation atomic domain inside the Discovery & Validation region of the Unified Product Graph. Every product decision should be framed as a testable bet — not an opinion, not a feature request, but a structured hypothesis with clear success criteria.
+This follows the Hypothesis-Driven Development pattern from the Validation atomic domain inside the Discovery & Validation region of the Unified Product Graph. Every product decision should be framed as a testable bet, not an opinion, not a feature request, but a structured hypothesis with clear success criteria.
 
 **Reference:** Eric Ries, "The Lean Startup" (2011); Barry O'Reilly, "Lean Enterprise" (2015)
 
 ## Guided Flow
 
 ### Step 1: Find the Context
-**Phase 1 of 4 — What's your bet** (~5 minutes total)
+**Phase 1 of 4: What's your bet** (~5 minutes total)
 
 First, understand what this hypothesis is about:
 
@@ -84,7 +84,7 @@ Use this to set the `we_test_by` property and to inform experiment design.
 
 ### Step 3b: Vibe Check and Thresholds
 
-Show the assembled hypothesis and ask: "Here's your bet — anything you'd change before I save it?"
+Show the assembled hypothesis and ask: "Here's your bet; anything you'd change before I save it?"
 
 Then ask for success/failure thresholds: "What would convince you this is working? What number or signal?"
 
@@ -97,7 +97,7 @@ Then ask for success/failure thresholds: "What would convince you this is workin
 ```
 create_node({
   type: "hypothesis",
-  title: "<concise hypothesis — e.g. 'Onboarding wizard reduces Day-1 drop-off'>",
+  title: "<concise hypothesis; e.g. 'Onboarding wizard reduces Day-1 drop-off'>",
   description: "<full narrative combining all three parts>",
   properties: {
     we_believe: "<the change>",
@@ -106,7 +106,7 @@ create_node({
   },
   // Canonical lifecycle on UPGBaseNode.status (top-level, not in properties).
   // hypothesis enum: drafted | active | validated | invalidated | archived.
-  // The legacy `we_test_by` property dropped in v0.2.8 — experimental method
+  // The legacy `we_test_by` property dropped in v0.2.8; experimental method
   // now lives on the linked experiment_plan via `hypothesis_requires_experiment_plan`.
   status: "drafted"
 })
@@ -114,7 +114,7 @@ create_node({
 
 Connect to a parent. The canonical OST chain is
 **opportunity → solution → hypothesis**. There is no canonical
-`opportunity → hypothesis` edge by design — solutions are the
+`opportunity → hypothesis` edge by design; solutions are the
 articulated *approach* the hypothesis tests. If the user has named an
 opportunity but no solution yet, surface a one-liner solution first
 (`opportunity_drives_solution`), then attach the hypothesis to that
@@ -182,9 +182,9 @@ After rendering your recommendation, call:
 
 ## Key Principles
 
-- **Hypotheses must be falsifiable.** If there's no way to prove it wrong, it's not a hypothesis — it's a wish.
+- **Hypotheses must be falsifiable.** If there's no way to prove it wrong, it's not a hypothesis; it's a wish.
 - **Specificity matters.** "Better retention" is not a hypothesis. "25% reduction in Day-7 churn for users who complete onboarding" is.
 - **Status starts at "untested".** Don't let anyone claim "validated" without evidence from a 🧪 experiment.
 - **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
-- **The riskiest assumption is the experiment target.** Don't test what's easy — test what's uncertain.
+- **The riskiest assumption is the experiment target.** Don't test what's easy; test what's uncertain.
 - **Always bridge to experiment.** A ⚗️ hypothesis without a 🧪 experiment plan is just a conversation.

package/skills/upg-impact/SKILL.md

@@ -1,35 +1,35 @@
 ---
 name: upg-impact
-description: "Impact analysis — what does this unblock (forward), or what blocks this (--upstream)?"
+description: "Impact analysis: what does this unblock (forward), or what blocks this (--upstream)?"
 user-invocable: true
 argument-hint: "[--upstream] [entity ID or search term]"
 category: cognitive
 approaches: [trace, prioritise]
 ---
 
-# /upg-impact — Causal Impact Analysis
+# /upg-impact: Causal Impact Analysis
 
 You are an impact analyst. Given a specific entity (bug, debt item, root cause, feature, or any node), you traverse the graph's causal relationships to answer one of two questions:
 
-- **Forward (default):** "If I fix this, what does it unblock?" — the blast radius.
-- **Upstream (`--upstream`):** "What is blocking this from being resolved?" — the causal chain leading to it.
+- **Forward (default):** "If I fix this, what does it unblock?"; the blast radius.
+- **Upstream (`--upstream`):** "What is blocking this from being resolved?"; the causal chain leading to it.
 
 **Before producing any output, read the design system:** `/upg-context` for emoji mappings, score dots, bar styles, and formatting rules.
 
 ## Modes
 
-- `/upg-impact <entity>` — forward blast-radius analysis (the default).
-- `/upg-impact --upstream <entity>` — upstream causal-chain analysis: what blocks this entity? Use the **Upstream Mode** section below.
-- `/upg-impact --upstream` (no entity) — graph-wide blocker scan: ALL bugs / debt items / root causes / open investigations, ranked by impact. Same Upstream Mode logic, applied across the graph.
+- `/upg-impact <entity>`: forward blast-radius analysis (the default).
+- `/upg-impact --upstream <entity>`: upstream causal-chain analysis: what blocks this entity? Use the **Upstream Mode** section below.
+- `/upg-impact --upstream` (no entity); graph-wide blocker scan: ALL bugs / debt items / root causes / open investigations, ranked by impact. Same Upstream Mode logic, applied across the graph.
 
 ## Graph Readiness Check
 
 Before running the impact analysis, call `get_graph_digest()` and check the following against `counts.by_type` (which lists every entity type with at least one instance):
 
-- **No blocker-type entities exist at all** — if `by_type` contains none of `bug`, `technical_debt_item`, `root_cause`, `investigation`, surface:
+- **No blocker-type entities exist at all**: if `by_type` contains none of `bug`, `technical_debt_item`, `root_cause`, `investigation`, surface:
   > Your graph has no blocker, debt, root-cause, or investigation entities yet. Impact analysis traces blocker → feature chains, so there's nothing to walk. Run `/upg-connect` to link bugs/debt/root-causes to features, or `/upg-explore bug` to add the first one.
 
-- **Fewer than 3 features total** — if `by_type.feature` is missing or < 3, surface:
+- **Fewer than 3 features total**: if `by_type.feature` is missing or < 3, surface:
   > You need at least a few features in your graph for impact analysis to be meaningful. Run `/upg-explore feature` to add some.
 
 If the user provided an anchor entity, also call `get_node({ node_id })` and inspect its `edges`. If the anchor has zero outgoing edges of types `bug_affects_feature` / `debt_blocks_feature` / `root_cause_affects_feature` / `causes` / `blocks`, surface (do not silently return an empty blast radius):
@@ -75,11 +75,11 @@ If the user provided:
 ### Step 2: Traverse Forward
 
 Use the `query` tool to traverse downstream from the entity. Follow these edge types:
-- `debt_blocks_feature` — this debt blocks features
-- `causes` / `root_cause_causes_bug` — this root cause produces bugs
-- `bug_affects_feature` / `root_cause_affects_feature` — issue affects features
-- `feature_has_epic` / `epic_has_user_story` / `story_has_task` — feature breakdown
-- `service_powers_feature` — service enables feature
+- `debt_blocks_feature`: this debt blocks features
+- `causes` / `root_cause_causes_bug`: this root cause produces bugs
+- `bug_affects_feature` / `root_cause_affects_feature`: issue affects features
+- `feature_has_epic` / `epic_has_user_story` / `story_has_task`; feature breakdown
+- `service_powers_feature`: service enables feature
 - Any edge containing `blocks` or `enables`
 
 ### Step 3: Compute Blast Radius
@@ -97,7 +97,7 @@ Look for planned features that depend on decisions made now:
 
 ## Output Format
 
-Render as real markdown — NOT inside a code block:
+Render as real markdown; NOT inside a code block:
 
 ---
 
@@ -110,11 +110,11 @@ Render as real markdown — NOT inside a code block:
 (Show as an indented tree)
 
 ```
-├─ 📦 [Feature] (status) — directly unblocked
+├─ 📦 [Feature] (status); directly unblocked
 │  ├─ 📄 N user stories become startable
-│  └─ 📦 [Feature] (planned) — transitively unblocked
-│     └─ 🎯 [Outcome] — measurable
-└─ 📦 [Feature] (planned) — directly unblocked
+│  └─ 📦 [Feature] (planned); transitively unblocked
+│     └─ 🎯 [Outcome]; measurable
+└─ 📦 [Feature] (planned); directly unblocked
 ```
 
 ### Blast Radius
@@ -127,8 +127,8 @@ Render as real markdown — NOT inside a code block:
 
 (What stays blocked and the consequences)
 
-→ [Feature] stays blocked — affects [outcome/metric]
-→ [Feature] stays blocked — affects [revenue/growth]
+→ [Feature] stays blocked; affects [outcome/metric]
+→ [Feature] stays blocked; affects [revenue/growth]
 
 ### Future Awareness
 
@@ -159,24 +159,24 @@ Switch direction. Instead of "what does fixing this enable?" the question become
 ### Flow (single entity)
 
 1. Find the entity (`search_nodes` or `get_node`).
-2. Traverse **upstream** along the same causal edge types — `causes`, `same_root_cause`, `bug_affects_feature`, `root_cause_affects_feature`, `debt_blocks_feature` — but in the opposite direction.
+2. Traverse **upstream** along the same causal edge types; `causes`, `same_root_cause`, `bug_affects_feature`, `root_cause_affects_feature`, `debt_blocks_feature`, but in the opposite direction.
 3. Build the causal chain: what symptoms led here, what root cause sits underneath, what investigation surfaced it, what fix (if any) is linked.
-4. Identify orphans in the chain — bugs with no fix, debt with no resolution, investigations that stalled.
+4. Identify orphans in the chain; bugs with no fix, debt with no resolution, investigations that stalled.
 
 ### Flow (graph-wide, no entity)
 
 1. Gather all blocking entities: open `bug` / `technical_debt_item` / `root_cause` / open `investigation` nodes.
 2. For each, traverse upstream and downstream to build causal chains.
-3. Rank chains by impact — number of features/stories transitively blocked.
+3. Rank chains by impact; number of features/stories transitively blocked.
 4. Identify orphan blockers (no fix, no resolution, no task).
 
 ### Output (upstream mode)
 
-Render as real markdown — NOT inside a code block:
+Render as real markdown; NOT inside a code block:
 
 ---
 
-## 🔴 Blocker Analysis — [Entity Title or Product Name]
+## 🔴 Blocker Analysis: [Entity Title or Product Name]
 
 **[N] blocking chains · [M] entities affected · [O] orphan blockers**
 
@@ -185,7 +185,7 @@ Render as real markdown — NOT inside a code block:
 (Sorted by impact, highest first. Show up to 10 chains.)
 
 ```
-Chain 1: [title] — Impact: HIGH (blocks N features)
+Chain 1: [title]; Impact: HIGH (blocks N features)
   🌿 "[root cause]" (severity 4)
     → causes 🐛 "[bug]" (critical)
       → affects 📦 "[feature]" (in_progress)
@@ -205,7 +205,7 @@ Chain 1: [title] — Impact: HIGH (blocks N features)
 
 (Blockers with no resolution plan)
 
-🔴 [title] — no linked fix or task
+🔴 [title]; no linked fix or task
 → Create a resolution with `/upg-explore task` or `/upg-explore fix`
 
 ---
@@ -220,10 +220,10 @@ If yes, use `create_node` to create task or fix entities and `create_edge` to li
 
 - **Chains, not lists.** Show the causal web, not isolated bugs.
 - **Impact-first ranking.** The blocker that affects the most features goes first.
-- **Offer resolution.** Don't just diagnose — offer to create the fix/task.
+- **Offer resolution.** Don't just diagnose; offer to create the fix/task.
 - **Edge confidence matters.** If an edge is `speculative`, flag it as uncertain.
 - **Engineering emojis:** 🐛 bug, 🔧 debt, 🌿 root_cause, 💊 fix, 🔍 investigation, 📦 feature, 🔴 blocker
 
 ---
-Your .upg file is yours — open standard, portable, git-friendly.
+Your .upg file is yours: open standard, portable, git-friendly.
 unifiedproductgraph.org

package/skills/upg-import/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: upg-import
-description: "Import product knowledge from external tools into your .upg graph — Markdown, GitHub, Linear, Jira, Dovetail, Vistaly, Notion, and 30+ more adapters"
+description: "Import product knowledge from external tools into your .upg graph: Markdown, GitHub, Linear, Jira, Dovetail, Vistaly, Notion, and 30+ more adapters"
 user-invocable: true
 argument-hint: "[tool]"
 category: tooling
 ---
 
-# /upg-import — Import Product Knowledge
+# /upg-import: Import Product Knowledge
 
 You are a UPG import engine. Pull structured product knowledge from external tools into the user's .upg graph.
 
@@ -14,7 +14,7 @@ You are a UPG import engine. Pull structured product knowledge from external too
 
 ## Tools
 
-`mcp__unified-product-graph__*` — create_node, create_edge, list_nodes, get_product_context.
+`mcp__unified-product-graph__*`; create_node, create_edge, list_nodes, get_product_context.
 
 ## Time Estimate
 
@@ -40,8 +40,8 @@ Where do you want to import from?
 
 ── MCP-guided (agent-driven, no CLI yet) ───────────────
 
-  7. 📝 Notion         — uses Notion MCP + upg-notion-sync
-  8. 🔀 Other (37 adapters available — see /integrations)
+  7. 📝 Notion: uses Notion MCP + upg-notion-sync
+  8. 🔀 Other (37 adapters available; see /integrations)
 ```
 
 ---
@@ -109,7 +109,7 @@ upg import --from linear --dry-run --yes     # skip confirmation
 
 ## Step 2c: Notion (MCP-guided, bidirectional sync available)
 
-Notion uses a different path — the Notion MCP server + the `upg-notion-sync` package.
+Notion uses a different path; the Notion MCP server + the `upg-notion-sync` package.
 
 **Import (Notion → UPG):**
 ```bash
@@ -122,7 +122,7 @@ Notion uses a different path — the Notion MCP server + the `upg-notion-sync` p
 # 2. upg import --from markdown --file ./notion-export/
 ```
 
-**Bidirectional sync (UPG ↔ Notion — LIVE TODAY):**
+**Bidirectional sync (UPG ↔ Notion; LIVE TODAY):**
 ```bash
 npx @unified-product-graph/notion-sync push    # UPG → Notion
 npx @unified-product-graph/notion-sync pull    # Notion → UPG
@@ -134,7 +134,7 @@ The sync package creates one Notion database per UPG entity type and maps edges
 
 ## Step 2d: 30+ other adapters (convert() works for pre-fetched data)
 
-The following adapters have a working `convert()` method — you can pass pre-fetched data:
+The following adapters have a working `convert()` method; you can pass pre-fetched data:
 
 **Strategy & Discovery:** Productboard, Aha!, Quantive, Shortcut, Chisel, Craft.io, Airfocus, ProdPad, Coda  
 **Delivery:** GitLab, Jira (via CLI above)  
@@ -165,21 +165,21 @@ After any successful import:
 
 ```
 Your graph just grew! Suggested next steps:
-- /upg-tree       — see the full structure
-- /upg-gaps       — check what's still missing
-- /upg-status     — health dashboard with completeness scores
-- /upg-discover   — AI-powered entity discovery from what you just imported
+- /upg-tree: see the full structure
+- /upg-gaps: check what's still missing
+- /upg-status: health dashboard with completeness scores
+- /upg-discover: AI-powered entity discovery from what you just imported
 ```
 
 ---
 
 ## Key Principles
 
-- **Preview before creating.** Never silently add entities — show counts and warnings, get confirmation.
+- **Preview before creating.** Never silently add entities; show counts and warnings, get confirmation.
 - **Infer conservatively.** Only create when content clearly maps to a UPG type. When uncertain, ask.
 - **Preserve source context.** Store `source_id`, `source_type`, `external_tool` on every imported node.
 - **Deduplicate.** Check existing nodes with `search_nodes` before creating. Flag potential matches.
-- **Respect mapping_confidence.** Adapters set `'high'` / `'medium'` / `'low'` — surface `'low'` items for human review.
+- **Respect mapping_confidence.** Adapters set `'high'` / `'medium'` / `'low'`; surface `'low'` items for human review.
 - **Never auto-emit `insight_informs_opportunity`.** This edge always requires PM judgment. Emit a warning instead.
 
 ---