@unified-product-graph/cli 0.6.0

package/skills/upg-hypothesis/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: upg-hypothesis
+description: "Structured Hypothesis Creation"
+user-invocable: true
+argument-hint: "[description]"
+category: cognitive
+approaches: [plan]
+playbooks: [discovery-validation-hypothesis-cycle]
+---
+
+# /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.
+
+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.
+
+**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 (create_node, create_edge, search_nodes, list_nodes, get_node).
+
+## Phase Map
+
+| Phase | Label | Steps |
+|-------|-------|-------|
+| 1 of 4 | What's your bet | Steps 1-2 |
+| 2 of 4 | Structuring it | Steps 2b-2c |
+| 3 of 4 | What's riskiest | Steps 3-4 |
+| 4 of 4 | How to test it | Steps 5-6 |
+
+## 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.
+
+**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)
+
+First, understand what this hypothesis is about:
+
+```
+search_nodes({ query: "<user's topic>" })
+list_nodes({ type: "solution" })
+```
+
+If there's an existing solution or opportunity this hypothesis relates to, note it for connection later.
+
+Ask: **"What's the bet you're making? What change or approach do you believe will work?"**
+
+### Step 2: Structure the Hypothesis
+
+Guide them through the three-part format:
+
+**"We believe that..."** (the change)
+Ask: **"Complete this sentence: 'We believe that [doing/building/changing X]...'"**
+
+This should be specific and actionable:
+- Good: "We believe that adding a guided onboarding wizard with 3 steps"
+- Bad: "We believe that improving onboarding"
+
+**"Will result in..."** (the measurable outcome)
+Ask: **"...will result in what measurable change?"**
+
+This should be a metric, not a feeling:
+- Good: "...will result in a 25% reduction in Day-1 drop-off"
+- Bad: "...will result in better user experience"
+
+**"We will know when..."** (the success criteria)
+Ask: **"How will you know this worked? What specific metric and threshold?"**
+
+This should be falsifiable:
+- Good: "We will know when the Day-1 activation rate exceeds 60% for a cohort of 200+ users"
+- Bad: "We will know when users are happier"
+
+### Step 3: Assess the Risk
+
+Ask: **"What's the riskiest assumption in this hypothesis? What's the one thing that, if wrong, kills the whole bet?"**
+
+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?"
+
+Then ask for success/failure thresholds: "What would convince you this is working? What number or signal?"
+
+### Step 4: Create the Hypothesis
+
+**Before creating the hypothesis, check if a solution node exists:**
+- If the hypothesis relates to an opportunity: ask "Does a solution already exist for this opportunity? If not, should I create one first?" Wait for the answer. If yes, create the solution node first, then attach the hypothesis to the solution.
+- The hierarchy is: opportunity → solution → hypothesis. Don't skip the solution layer.
+
+```
+create_node({
+  type: "hypothesis",
+  title: "<concise hypothesis — e.g. 'Onboarding wizard reduces Day-1 drop-off'>",
+  description: "<full narrative combining all three parts>",
+  properties: {
+    we_believe: "<the change>",
+    will_result_in: "<the measurable outcome>",
+    we_know_when: "<the success signal and threshold>",
+  },
+  // 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
+  // now lives on the linked experiment_plan via `hypothesis_requires_experiment_plan`.
+  status: "drafted"
+})
+```
+
+Connect to a parent. The canonical OST chain is
+**opportunity → solution → hypothesis**. There is no canonical
+`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
+solution via `solution_proposes_hypothesis`.
+
+- If related to a `solution` → use the `solution_proposes_hypothesis` edge (or `parent_id: <solution_id>` for parent_ref auto-chaining).
+- If related to an `opportunity` → create the intermediate solution first, then attach the hypothesis to that solution. Do not skip the solution layer.
+
+### Step 5: Show the Result
+
+```
+### ⚗️ <Title>                                    ⚪ untested
+
+**We believe that** <the change>
+**will result in** <the measurable outcome>.
+**We will know when** <the success signal>.
+
+Riskiest assumption: <what could kill this>
+Connected to: 🔧 <Solution Name>
+Domain: Validation
+```
+
+### Step 6: Bridge to Experiment
+
+Ask: **"How would you test this? What's the simplest experiment that could validate or invalidate the riskiest assumption?"**
+
+Offer experiment templates based on context:
+
+| Riskiest Assumption | Suggested Experiment |
+|---|---|
+| "Users want this" | Fake door test, landing page, survey |
+| "Users can use this" | Prototype usability test (5 users) |
+| "This will move the metric" | A/B test with control group |
+| "We can build this" | Technical spike / proof of concept |
+| "The market is big enough" | Market sizing research, competitor analysis |
+| "Users will trust/adopt this" | A/B test with behavioral tracking or longitudinal usage study |
+
+If they describe an experiment, create it:
+
+```
+create_node({
+  type: "experiment",
+  title: "<experiment name>",
+  description: "<what we're testing and how>",
+  properties: {
+    method: "<e.g. A/B test, usability test, fake door>",
+    status: "planned",
+    start_date: "<if known>",
+    end_date: "<if known>"
+  },
+  parent_id: "<hypothesis_id>"  // auto-creates hypothesis_has_experiment edge
+})
+```
+
+### Step 7: Close with Smart Ending
+
+Check the graph for the biggest gap across the 8 business areas. Recommend ONE next skill:
+
+> Based on what we built, your biggest gap is **[area]**. I'd suggest running `/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-hypothesis", recommendation: "<the next skill you recommended>" })`
+
+## Key Principles
+
+- **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.
+- **Always bridge to experiment.** A ⚗️ hypothesis without a 🧪 experiment plan is just a conversation.

package/skills/upg-impact/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: upg-impact
+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
+
+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.
+
+**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.
+
+## 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:
+  > 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:
+  > 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):
+> `<anchor title>` has no outgoing impact edges in the graph, so its blast radius is empty by definition. Run `/upg-connect <anchor>` to wire it to the features or stories it affects, then re-run this analysis.
+
+If the user is in the engineering lens, you may also consult `lens_digest.blockers` and `lens_digest.blocked_features` for a richer signal.
+
+Only proceed with the impact analysis if the graph passes these checks, or if the user explicitly wants to proceed anyway.
+
+## Tools
+
+Use `mcp__unified-product-graph__*` MCP tools.
+
+```
+get_session_context()
+search_nodes({ query: "<user's search term>" })   // if they gave a title, not an ID
+get_node({ node_id: "<id>" })                      // get the target entity + edges
+query({ from_id: "<id>", traverse: ["causes", "debt_blocks_feature", "bug_affects_feature", "root_cause_affects_feature", "blocks", "service_powers_feature"], depth: 5 })
+```
+
+For `--upstream` mode, traverse the same edge types in reverse (use `to_id` as the anchor or `query` with appropriate direction). For graph-wide upstream scans:
+
+```
+list_nodes({ type: "bug", include_edges: true })
+list_nodes({ type: "technical_debt_item", include_edges: true })
+list_nodes({ type: "root_cause", include_edges: true })
+list_nodes({ type: "investigation", include_edges: true })
+```
+
+After rendering, register this invocation:
+```
+update_session_context({ skill_invoked: "upg-impact", direction: "forward" | "upstream" })
+```
+
+## Flow
+
+### Step 1: Find the Entity
+
+If the user provided:
+- A node ID → use `get_node` directly
+- A search term → use `search_nodes` to find matches, pick the best one (or ask if ambiguous)
+
+### 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
+- Any edge containing `blocks` or `enables`
+
+### Step 3: Compute Blast Radius
+
+Count all transitively affected entities by type:
+- Features, user stories, tasks, outcomes, metrics
+- Group by depth (direct vs transitive)
+
+### Step 4: Future Awareness
+
+Look for planned features that depend on decisions made now:
+- Planned features connected to the target entity (even indirectly)
+- Architecture decisions that might need updating
+- Flag any assumptions that could be invalidated
+
+## Output Format
+
+Render as real markdown — NOT inside a code block:
+
+---
+
+## 💥 Impact Analysis: "[Entity Title]"
+
+**Type:** [entity type] · **Status:** [status] · **Severity:** [if applicable]
+
+### If Resolved, Enables
+
+(Show as an indented tree)
+
+```
+├─ 📦 [Feature] (status) — directly unblocked
+│  ├─ 📄 N user stories become startable
+│  └─ 📦 [Feature] (planned) — transitively unblocked
+│     └─ 🎯 [Outcome] — measurable
+└─ 📦 [Feature] (planned) — directly unblocked
+```
+
+### Blast Radius
+
+**Direct:** N features, M stories
+**Transitive:** N features, M stories, O outcomes
+**Total entities affected:** X
+
+### If NOT Resolved
+
+(What stays blocked and the consequences)
+
+→ [Feature] stays blocked — affects [outcome/metric]
+→ [Feature] stays blocked — affects [revenue/growth]
+
+### Future Awareness
+
+(Planned entities that depend on decisions being made now)
+
+⚠️ [Planned feature] assumes [current decision/architecture]
+⚠️ [Planned feature] depends on [this entity being resolved]
+→ Architecture decision needed: "[decision title]"
+
+---
+
+After displaying, optionally offer:
+
+> Want me to create a `decision` (layer: "engineering") for any of these future dependencies?
+
+## Key Principles (forward mode)
+
+- **Forward-looking.** This is about what happens NEXT, not what caused the problem.
+- **Blast radius is the key metric.** How many things are affected?
+- **Future awareness is the differentiator.** Show how today's work affects tomorrow's features.
+- **Offer to capture decisions.** If the analysis reveals needed decisions, offer to create them.
+- **Engineering emojis:** 🐛 bug, 🔧 debt, 🌿 root_cause, 💊 fix, 📦 feature, 🎯 outcome, 📋 task
+
+## Upstream Mode (`--upstream`)
+
+Switch direction. Instead of "what does fixing this enable?" the question becomes "what is blocking this from being resolved?" or, with no entity given, "what's blocking the product overall?"
+
+### 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.
+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.
+
+### 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.
+4. Identify orphan blockers (no fix, no resolution, no task).
+
+### Output (upstream mode)
+
+Render as real markdown — NOT inside a code block:
+
+---
+
+## 🔴 Blocker Analysis — [Entity Title or Product Name]
+
+**[N] blocking chains · [M] entities affected · [O] orphan blockers**
+
+### Causal Chains
+
+(Sorted by impact, highest first. Show up to 10 chains.)
+
+```
+Chain 1: [title] — Impact: HIGH (blocks N features)
+  🌿 "[root cause]" (severity 4)
+    → causes 🐛 "[bug]" (critical)
+      → affects 📦 "[feature]" (in_progress)
+        → 📋 3 user stories blocked
+```
+
+### Resolution Paths
+
+(Ranked by priority = impact / effort. Show effort estimate and unblocks.)
+
+| # | Fix | Effort | Unblocks | Priority |
+|---|-----|--------|----------|----------|
+| 1 | Fix [bug title] | ~2 days | [feature] + 3 stories | HIGH |
+| 2 | Resolve [debt title] | ~5 days | 2 features | CRITICAL |
+
+### Orphan Blockers
+
+(Blockers with no resolution plan)
+
+🔴 [title] — no linked fix or task
+→ Create a resolution with `/upg-explore task` or `/upg-explore fix`
+
+---
+
+After displaying, ask:
+
+> Want me to create resolution tasks for any of these blockers?
+
+If yes, use `create_node` to create task or fix entities and `create_edge` to link them.
+
+### Upstream-mode principles
+
+- **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.
+- **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.
+unifiedproductgraph.org

package/skills/upg-import/SKILL.md

@@ -0,0 +1,189 @@
+---
+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"
+user-invocable: true
+argument-hint: "[tool]"
+category: tooling
+---
+
+# /upg-import — Import Product Knowledge
+
+You are a UPG import engine. Pull structured product knowledge from external tools into the user's .upg graph.
+
+**Before producing any output, read context:** /upg-context for entity types, formatting rules, and interaction patterns.
+
+## Tools
+
+`mcp__unified-product-graph__*` — create_node, create_edge, list_nodes, get_product_context.
+
+## Time Estimate
+
+**2–5 minutes** for CLI imports. MCP-guided flows take 5–10 minutes.
+
+---
+
+## Step 1: Choose Source
+
+Skip if the user provided an argument (e.g. `/upg-import github`). Otherwise present the menu:
+
+```
+Where do you want to import from?
+
+── Fully wired (live API import today) ─────────────────
+
+  1. 📄 Markdown       upg import --from markdown
+  2. 🐙 GitHub         upg import --from github        GITHUB_TOKEN + GITHUB_REPO
+  3. 📋 Linear         upg import --from linear         LINEAR_API_KEY
+  4. 🗂️  Jira           upg import --from jira           JIRA_BASE_URL + JIRA_EMAIL + JIRA_API_TOKEN
+  5. 🔬 Dovetail        upg import --from dovetail       DOVETAIL_API_KEY
+  6. 🌲 Vistaly         upg import --from vistaly        VISTALY_API_KEY
+
+── MCP-guided (agent-driven, no CLI yet) ───────────────
+
+  7. 📝 Notion         — uses Notion MCP + upg-notion-sync
+  8. 🔀 Other (37 adapters available — see /integrations)
+```
+
+---
+
+## Step 2a: Markdown (fully implemented, no API key)
+
+```bash
+upg import --from markdown                    # scans current directory
+upg import --from markdown --file ./docs/     # specific folder
+upg import --from markdown --dry-run          # preview without writing
+```
+
+Parses headings and content. Infers entity types from keywords:
+- "persona/user/audience" → `persona`
+- "feature/capability" → `feature`
+- "pain point/problem/frustration" → `need`
+- "hypothesis/assumption" → `hypothesis_claim`
+- "metric/KPI/measure" → `metric`
+- "objective/OKR/goal" → `objective`
+- "opportunity/gap" → `opportunity`
+- "competitor/alternative" → `competitor`
+- "solution/approach" → `solution`
+- "epic/story" → `epic` / `story_statement`
+- "experiment/validation" → `experiment`
+- "insight/learning" → `insight`
+
+---
+
+## Step 2b: Live API tools (GitHub, Linear, Jira, Dovetail, Vistaly)
+
+All five use the same CLI flow:
+
+```bash
+upg import --from github      # prompts for GITHUB_TOKEN + repo if not in env
+upg import --from linear      # prompts for LINEAR_API_KEY if not in env
+upg import --from jira        # prompts for base URL + email + API token
+upg import --from dovetail    # prompts for DOVETAIL_API_KEY
+upg import --from vistaly     # prompts for VISTALY_API_KEY
+```
+
+**Env vars (set these to skip prompts):**
+
+| Tool | Env vars |
+|------|----------|
+| GitHub | `GITHUB_TOKEN`, `GITHUB_REPO` (owner/repo) |
+| Linear | `LINEAR_API_KEY` |
+| Jira | `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` |
+| Dovetail | `DOVETAIL_API_KEY` |
+| Vistaly | `VISTALY_API_KEY`, `VISTALY_WORKSPACE_ID` (optional) |
+
+**All five show the same flow:**
+1. Connects to the API (spinner)
+2. Fetches all entities
+3. Shows a preview: entity counts by type + any warnings
+4. Asks for confirmation before writing
+5. Writes to your `.upg` file (creates or appends)
+
+**Dry-run mode (preview without writing):**
+```bash
+upg import --from github --dry-run
+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.
+
+**Import (Notion → UPG):**
+```bash
+# Option A: via the MCP (recommended)
+# Ensure Notion MCP is configured in .claude/settings.json, then:
+# The NotionAdapter classifies your databases by name and maps them to UPG types
+
+# Option B: via Notion export
+# 1. In Notion: Settings → Export → Markdown & CSV
+# 2. upg import --from markdown --file ./notion-export/
+```
+
+**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
+```
+
+The sync package creates one Notion database per UPG entity type and maps edges to Notion relation properties.
+
+---
+
+## 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:
+
+**Strategy & Discovery:** Productboard, Aha!, Quantive, Shortcut, Chisel, Craft.io, Airfocus, ProdPad, Coda  
+**Delivery:** GitLab, Jira (via CLI above)  
+**Research:** Dovetail (via CLI above), Condens, Lookback, Sprig, Maze  
+**Analytics:** Amplitude, PostHog, Pendo  
+**Feedback:** Canny, Intercom, Zendesk  
+**CRM / CS:** HubSpot, Salesforce, Gainsight  
+**Design:** Figma, Miro, Storybook  
+**Docs:** Confluence, Slack  
+**OKR:** Lattice  
+
+For these, use the adapter directly in code:
+```typescript
+import { ProductboardAdapter } from '@unified-product-graph/adapters'
+const adapter = new ProductboardAdapter()
+const result = await adapter.convert(prefetchedItems)
+```
+
+Or see `/integrations` on unifiedproductgraph.org for the full schema mapping for each tool.
+
+Live CLI support for all adapters is in active development.
+
+---
+
+## Step 3: Post-import suggestions
+
+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
+```
+
+---
+
+## Key Principles
+
+- **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.
+- **Never auto-emit `insight_informs_opportunity`.** This edge always requires PM judgment. Emit a warning instead.
+
+---
+
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+37 adapters. Open standard. Your .upg file is portable and git-friendly.
+unifiedproductgraph.org/integrations