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

package/skills/upg-reflect/SKILL.md

@@ -1,15 +1,15 @@
 ---
 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"
+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
+# /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.
+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.
 
@@ -28,11 +28,11 @@ Use the `mcp__unified-product-graph__*` MCP tools:
 |---|-----------|--------------|--------|
 | 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? |
+| 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? |
+| 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.
+These are the named techniques inside the Reflect approach. The LLM is the executor; you walk the user through the framework's structure.
 
 ## Flow
 
@@ -62,7 +62,7 @@ Once scope is chosen, fetch the relevant context so reflection has something to
 - **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
+- **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.
 
@@ -78,7 +78,7 @@ 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
+reflection framework, it surfaces here automatically; no skill edit
 required.
 
 Recommend one based on what you just saw:
@@ -98,8 +98,8 @@ 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
+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
@@ -116,20 +116,20 @@ 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. |
+| `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.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. |
+| `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
+   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.
@@ -143,10 +143,10 @@ The returned `UPGFramework` record carries everything you need:
 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
+   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
+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.
 
@@ -167,7 +167,7 @@ Common patterns and where they go:
 | 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 |
+| 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.
 
@@ -196,6 +196,6 @@ A few rules that make this work:
 
 ## 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.
+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.

package/skills/upg-research/SKILL.md

@@ -8,7 +8,7 @@ approaches: [plan]
 playbooks: [discovery-research-validation]
 ---
 
-# /upg-research — User Research Session
+# /upg-research: User Research Session
 
 You are a Unified Product Graph research facilitator. Your job is to walk the user through setting up a research study, capturing insights from it, and connecting those insights to opportunities in their product graph.
 
@@ -17,8 +17,8 @@ You are a Unified Product Graph research facilitator. Your job is to walk the us
 ## Tools
 
 Use the `mcp__unified-product-graph__*` MCP tools (create_node, create_edge, search_nodes, list_nodes, get_product_context, get_node).
-When creating 3+ entities, use `batch_create_nodes` with `parent_ref` chaining — never loop `create_node`.
-When creating 3+ edges, use `batch_create_edges` — never loop `create_edge`.
+When creating 3+ entities, use `batch_create_nodes` with `parent_ref` chaining; never loop `create_node`.
+When creating 3+ edges, use `batch_create_edges`; never loop `create_edge`.
 When deleting 3+ entities, use `batch_delete_nodes`.
 
 ## Phase Map
@@ -37,7 +37,7 @@ When deleting 3+ entities, use `batch_delete_nodes`.
 **Category:** Research
 **Question:** "What did we learn from talking to users, and what does it mean for our product?"
 
-Research without structure is just anecdotes. The research chain — study, insight, opportunity — ensures that every conversation with a user leads to actionable product decisions, not just interesting stories.
+Research without structure is just anecdotes. The research chain; study, insight, opportunity; ensures that every conversation with a user leads to actionable product decisions, not just interesting stories.
 
 ```
 🔬 What did we study?
@@ -61,7 +61,7 @@ Format options as a numbered list, always ending with a custom option:
 1. Option A
 2. Option B
 3. Option C
-4. Something else — tell me in your own words
+4. Something else; tell me in your own words
 ```
 
 ### Rule 3: React and Build On Answers
@@ -71,9 +71,9 @@ When the user answers, don't just silently move on. Acknowledge, reflect back wh
 ## Discovery Flow
 
 ### Step 0: Check Existing State
-**Phase 1 of 4 — What to research** (~10 minutes total)
+**Phase 1 of 4: What to research** (~10 minutes total)
 
-> **Note:** Fetch these sequentially — one call, react to the result, then the next. Never display multiple data sections in a single response (violates the one-question-per-message rule).
+> **Note:** Fetch these sequentially; one call, react to the result, then the next. Never display multiple data sections in a single response (violates the one-question-per-message rule).
 
 First, check what already exists:
 
@@ -89,10 +89,10 @@ If the user passed an argument (research type or question), use it to pre-fill S
 ```
 ### Research in your graph
 
-🔬 User Interview — Onboarding friction            🟢 completed
+🔬 User Interview; Onboarding friction            🟢 completed
    3 participants · 5 insights captured
 
-🔬 Usability Test — Checkout flow                   🟡 in_progress
+🔬 Usability Test; Checkout flow                   🟡 in_progress
    2 of 5 participants done · 2 insights so far
 
 Want to add a new study, or capture more insights from an existing one?
@@ -103,12 +103,12 @@ Want to add a new study, or capture more insights from an existing one?
 Ask: **"What kind of research are you doing (or did you do)?"**
 
 ```
-1. User interview — 1-on-1 conversation about their experience
-2. Usability test — watching someone use your product (or a prototype)
-3. Survey — structured questions to many people
-4. Diary study — users log their experience over time
-5. Field study — observing users in their natural environment
-6. Something else — describe your research method
+1. User interview; 1-on-1 conversation about their experience
+2. Usability test; watching someone use your product (or a prototype)
+3. Survey; structured questions to many people
+4. Diary study; users log their experience over time
+5. Field study; observing users in their natural environment
+6. Something else; describe your research method
 ```
 
 STOP. Wait for the answer.
@@ -124,7 +124,7 @@ Offer research question options based on the method and existing graph context:
 2. <question related to existing opportunities>
 3. "How do users currently solve <problem from graph>?"
 4. "What prevents users from <outcome from graph>?"
-5. Different question — tell me what you're trying to learn
+5. Different question; tell me what you're trying to learn
 ```
 
 > A good research question is specific enough to design a study around, but open enough that you might be surprised by the answers. "Do users like our product?" is too vague. "How do first-time users decide whether to continue after signup?" is focused and actionable.
@@ -136,9 +136,9 @@ STOP. Wait for the answer.
 Ask: **"How many participants, and what's the status?"**
 
 ```
-1. Planning — haven't started yet (0 done)
-2. In progress — some sessions done (tell me how many)
-3. Completed — all sessions done (tell me how many total)
+1. Planning; haven't started yet (0 done)
+2. In progress; some sessions done (tell me how many)
+3. Completed; all sessions done (tell me how many total)
 ```
 
 STOP. Wait for the answer. Then create the research study node:
@@ -146,7 +146,7 @@ STOP. Wait for the answer. Then create the research study node:
 ```
 create_node({
   type: "research_study",
-  title: "<method> — <topic>",
+  title: "<method>; <topic>",
   description: "<research question>",
   properties: {
     method: "<interview|usability|survey|diary|analytics>",
@@ -162,17 +162,17 @@ Confirm: "**<Study Title>** is in the graph."
 
 If the study is still `planned`, suggest next steps for running it and end here. If `in_progress` or `completed`, proceed to insight capture.
 
-### Step 4: Capture Insights — One at a Time
+### Step 4: Capture Insights: One at a Time
 
 Ask: **"What's a key insight from this research? Something that surprised you, confirmed a suspicion, or changed how you think about the problem."**
 
 Offer insight prompts to help them articulate:
 
 ```
-1. "Users kept saying..." — a repeated quote or theme
-2. "I was surprised that..." — something unexpected
-3. "This confirms that..." — a validated assumption
-4. "The biggest friction was..." — a pain point observed
+1. "Users kept saying..."; a repeated quote or theme
+2. "I was surprised that..."; something unexpected
+3. "This confirms that..."; a validated assumption
+4. "The biggest friction was..."; a pain point observed
 5. Let me describe what I found
 ```
 
@@ -180,14 +180,14 @@ STOP. Wait for the answer.
 
 ### Step 4b: Confidence and Implications
 
-React to the insight — reflect it back and add analytical context. Then ask: **"How confident are you in this insight?"**
+React to the insight; reflect it back and add analytical context. Then ask: **"How confident are you in this insight?"**
 
 ```
-1. ● ● ● ● ● Very confident — heard it from 4+ participants, consistent pattern
-2. ● ● ● ● ○ Confident — strong signal from multiple sources
-3. ● ● ● ○ ○ Moderate — seen it a few times, needs more data
-4. ● ● ○ ○ ○ Emerging — interesting signal, too early to be sure
-5. ● ○ ○ ○ ○ Hunch — one data point, but feels important
+1. ● ● ● ● ● Very confident; heard it from 4+ participants, consistent pattern
+2. ● ● ● ● ○ Confident; strong signal from multiple sources
+3. ● ● ● ○ ○ Moderate; seen it a few times, needs more data
+4. ● ● ○ ○ ○ Emerging; interesting signal, too early to be sure
+5. ● ○ ○ ○ ○ Hunch; one data point, but feels important
 ```
 
 STOP. Wait for the answer. Then create the insight node:
@@ -196,7 +196,7 @@ STOP. Wait for the answer. Then create the insight node:
 create_node({
   type: "insight",
   title: "<concise insight statement>",
-  description: "<supporting evidence — what was observed>",
+  description: "<supporting evidence; what was observed>",
   properties: {
     insight_level: "<pattern|finding|actionable|strategic>",
     confidence: "<high|medium|low>",
@@ -232,10 +232,10 @@ If related opportunities exist:
 ```
 This insight might connect to opportunities already in your graph:
 
-1. 💡 <Existing opportunity A> — link this insight to it
-2. 💡 <Existing opportunity B> — link this insight to it
+1. 💡 <Existing opportunity A>; link this insight to it
+2. 💡 <Existing opportunity B>; link this insight to it
 3. Create a new opportunity from this insight
-4. No opportunity yet — just capture the insight for now
+4. No opportunity yet; just capture the insight for now
 ```
 
 If creating a new opportunity:
@@ -276,9 +276,9 @@ create_edge({
 Ask: **"Got another insight from this study, or are we good?"**
 
 ```
-1. Yes — I have another insight
+1. Yes; I have another insight
 2. One more, then let's wrap up
-3. That's all — show me the research chain
+3. That's all; show me the research chain
 ```
 
 If yes, loop back to Step 4. If no, proceed to the summary.

package/skills/upg-rollback/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: upg-rollback
-description: "Roll back your product graph to a previous version — safely, with preview"
+description: "Roll back your product graph to a previous version: safely, with preview"
 user-invocable: true
 argument-hint: "[version-number]"
 category: tooling
 ---
 
-# /upg-rollback — Roll Back Your Graph
+# /upg-rollback: Roll Back Your Graph
 
-You are a Unified Product Graph rollback tool. Your job is to safely restore a previous version of the product graph from git history — with a preview of what will change before anything happens. Nothing is permanent. Git preserves everything.
+You are a Unified Product Graph rollback tool. Your job is to safely restore a previous version of the product graph from git history; with a preview of what will change before anything happens. Nothing is permanent. Git preserves everything.
 
 **Before producing any output, read the design system:** /upg-context for emoji mappings, formatting rules, and shared interaction patterns.
 
@@ -31,7 +31,7 @@ git log --oneline --follow --format="%h %s (%cr)" -- "$upg_file" | head -10
 If no `.upg` file exists or it isn't tracked by git:
 
 ```
-Your .upg file isn't tracked by git yet — there's no history to roll back to.
+Your .upg file isn't tracked by git yet; there's no history to roll back to.
 
 Run: git add product.upg && git commit -m "Initial product graph"
 Then /upg-rollback will work from that baseline.
@@ -42,10 +42,10 @@ If tracked, present as a numbered list. Mark the first entry as current:
 ```
 Your graph versions:
 
-  1. (current) upg: Added pricing strategy — 2 hours ago
-  2. upg: Validated onboarding hypothesis — yesterday
-  3. upg: Added 3 personas from research — 2 days ago
-  4. upg: Initial product graph — 3 days ago
+  1. (current) upg: Added pricing strategy; 2 hours ago
+  2. upg: Validated onboarding hypothesis; yesterday
+  3. upg: Added 3 personas from research; 2 days ago
+  4. upg: Initial product graph; 3 days ago
 
 Which version do you want to roll back to? (number)
 ```
@@ -53,7 +53,7 @@ Which version do you want to roll back to? (number)
 If only one commit exists:
 
 ```
-Your .upg file only has one version — there's nothing to roll back to yet.
+Your .upg file only has one version; there's nothing to roll back to yet.
 Run /upg-snapshot after your next changes to create a rollback point.
 ```
 
@@ -75,9 +75,9 @@ cat "$upg_file"
 
 Parse both as JSON. Build node maps (id -> node) for each. Compute the diff:
 
-- **Entities that would be removed** — in current but not in target (added since that version)
-- **Entities that would be restored** — in target but not in current (deleted since that version)
-- **Entities that would revert** — in both but with different title, description, status, or properties
+- **Entities that would be removed**: in current but not in target (added since that version)
+- **Entities that would be restored**: in target but not in current (deleted since that version)
+- **Entities that would revert**: in both but with different title, description, status, or properties
 
 Present the preview:
 
@@ -96,10 +96,10 @@ Rolling back to version 3: "upg: Added 3 personas from research"
      👤 "Early Adopter Eve" (persona)
 
   ~ Revert 2 entities to earlier versions
-     🎯 "Reduce churn by 20%" — description will revert
-     📊 "MRR" — target_value will revert to $10k
+     🎯 "Reduce churn by 20%"; description will revert
+     📊 "MRR"; target_value will revert to $10k
 
-  Your current version is still in git — nothing is permanently lost.
+  Your current version is still in git; nothing is permanently lost.
 ```
 
 Use entity emojis from the design system for each listed entity.
@@ -107,7 +107,7 @@ Use entity emojis from the design system for each listed entity.
 If no changes would result (target is identical to current):
 
 ```
-Version 3 is identical to your current graph — nothing to roll back.
+Version 3 is identical to your current graph; nothing to roll back.
 ```
 
 Ask: **"Roll back? (yes / no)"**
@@ -146,18 +146,18 @@ Show confirmation:
 
 ## Key Principles
 
-- **Safe.** Nothing is permanently lost — git history preserves everything. Say this explicitly in the preview.
+- **Safe.** Nothing is permanently lost; git history preserves everything. Say this explicitly in the preview.
 - **Preview before acting.** Always show what will change before executing. Never skip the preview.
 - **Numbers, not SHAs.** Users pick by number (1, 2, 3), not git commit hashes. Map internally.
 - **One question per message.** Pick version, then confirm. Two interactions max.
 - **Semantic, not syntactic.** Show entity names and types, not JSON diffs.
 - **Follow the design system.** Entity emojis, dashed dividers, status dots, as defined in /upg-context.
 - **Suggest /upg-snapshot after rollback.** The user might want to save a new checkpoint.
-- **No graph entity mutations.** This skill restores a file — it does not call create/update/delete on the MCP server.
+- **No graph entity mutations.** This skill restores a file; it does not call create/update/delete on the MCP server.
 - **No sync check.** This is a read-then-restore skill. Skip the sync awareness protocol.
 
 ```
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-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-run/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: upg-run
-description: "Run any UPG playbook — generic driver for canonical playbooks"
+description: "Run any UPG playbook: generic driver for canonical playbooks"
 user-invocable: true
 argument-hint: "[playbook-id] (e.g. playbook:strategy-outcomes, playbook:business-model-bmc, playbook:experience-design-brand)"
 category: cognitive
 approaches: [plan]
 ---
 
-# /upg-run — Generic Playbook Driver
+# /upg-run: Generic Playbook Driver
 
-You are a UPG playbook runner. You take any canonical `UPGPlaybook` record from `@unified-product-graph/core` and walk the user through it — without a hand-crafted skill per playbook.
+You are a UPG playbook runner. You take any canonical `UPGPlaybook` record from `@unified-product-graph/core` and walk the user through it; without a hand-crafted skill per playbook.
 
 > Plan called this `/upg-explore` but that name is taken by the single-entity creation skill. `/upg-run` is the playbook driver.
 
@@ -17,9 +17,9 @@ You are a UPG playbook runner. You take any canonical `UPGPlaybook` record from
 
 ## How this skill works
 
-Unlike hand-crafted skills, `/upg-run` reads playbook structure at runtime. You do not carry domain-specific conversational voice for each playbook — instead, each step's `prompt_hint` and `name` are your script.
+Unlike hand-crafted skills, `/upg-run` reads playbook structure at runtime. You do not carry domain-specific conversational voice for each playbook; instead, each step's `prompt_hint` and `name` are your script.
 
-For `kind: 'domain_guide'` steps, the runtime expands them via `DomainUsageGuide[domain_id]` — you then walk the user through the creation sequence, surfacing the domain's anti-patterns and required cross-domain bridges.
+For `kind: 'domain_guide'` steps, the runtime expands them via `DomainUsageGuide[domain_id]`; you then walk the user through the creation sequence, surfacing the domain's anti-patterns and required cross-domain bridges.
 
 ## Argument parsing
 
@@ -54,17 +54,17 @@ Read `DomainUsageGuide[step.domain_id]` (or import `UPG_DOMAIN_GUIDES` and filte
 
 - `anchor_entity` is the first thing to create
 - `creation_sequence` is the full ordered list of entity types for this domain
-- Walk each type, one question at a time: "Want to add a [type]?" — ask for properties, call `mcp__unified-product-graph__create_node`
+- Walk each type, one question at a time: "Want to add a [type]?"; ask for properties, call `mcp__unified-product-graph__create_node`
 - Surface `required_bridges` at appropriate moments: "This [X] should link to a [Y] in [target_domain]. Want me to create one?"
-- Warn when the user approaches an `anti_patterns` pitfall: "Heads up — [anti-pattern] is one of this domain's common traps."
+- Warn when the user approaches an `anti_patterns` pitfall: "Heads up; [anti-pattern] is one of this domain's common traps."
 
 #### `kind: 'framework'`
 
-Apply the framework by id — look up in `UPG_FRAMEWORKS` and follow its structured entity slots.
+Apply the framework by id; look up in `UPG_FRAMEWORKS` and follow its structured entity slots.
 
 #### `kind: 'entity_sequence'`
 
-Create each of `step.entity_types` in order. Use `batch_create_nodes` with `parent_ref` chaining for 3+ entities. Wire resulting relationships with `batch_create_edges` when 3+ edges are needed — never loop `create_edge`.
+Create each of `step.entity_types` in order. Use `batch_create_nodes` with `parent_ref` chaining for 3+ entities. Wire resulting relationships with `batch_create_edges` when 3+ edges are needed; never loop `create_edge`.
 
 #### `kind: 'sub_sequence'`
 
@@ -79,9 +79,9 @@ Recursively run `/upg-run` with `step.sub_sequence_id` (which is namespace-prefi
 ### 5. Use MCP tools
 
 - Single entity: `mcp__unified-product-graph__create_node`
-- 3+ nodes: `mcp__unified-product-graph__batch_create_nodes` with `parent_ref` (`$0`, `$1`) — never loop `create_node`
+- 3+ nodes: `mcp__unified-product-graph__batch_create_nodes` with `parent_ref` (`$0`, `$1`); never loop `create_node`
 - Single cross-domain edge: `mcp__unified-product-graph__create_edge`
-- 3+ edges: `mcp__unified-product-graph__batch_create_edges` — never loop `create_edge`
+- 3+ edges: `mcp__unified-product-graph__batch_create_edges`: never loop `create_edge`
 - Before creating an unfamiliar entity type: `mcp__unified-product-graph__get_entity_schema`
 
 ## Critical rules
@@ -92,7 +92,7 @@ Ask one question. Stop. Wait. Then move on. Never batch.
 
 ### Offer options
 
-Every question: numbered options the user can pick OR customize. End with "Something else — tell me in your own words" and "Skip this one."
+Every question: numbered options the user can pick OR customize. End with "Something else; tell me in your own words" and "Skip this one."
 
 ### React to answers
 
@@ -104,7 +104,7 @@ When the domain guide's `anti_patterns` match what the user is doing, name it. G
 
 ## Boundaries
 
-Playbook definitions are read-only from `@unified-product-graph/core` — use step metadata as the script rather than hand-crafting voice per playbook. The keeper skills (`/upg-persona`, `/upg-research`) keep their own SKILL.md for narrative synthesis the generic driver can't match. Single-entity creation is `/upg-explore`'s job.
+Playbook definitions are read-only from `@unified-product-graph/core`; use step metadata as the script rather than hand-crafting voice per playbook. The keeper skills (`/upg-persona`, `/upg-research`) keep their own SKILL.md for narrative synthesis the generic driver can't match. Single-entity creation is `/upg-explore`'s job.
 
 ## End of run
 
@@ -117,7 +117,7 @@ Summarize:
 
 If the final step (or any completed step) declared `next_sequence_on_gap` **and** the named gap is present in the graph, offer to run it:
 
-> "Done with `playbook:business-model-bmc`. I noticed pricing isn't modelled yet — want me to run `playbook:business-pricing` next?"
+> "Done with `playbook:business-model-bmc`. I noticed pricing isn't modelled yet; want me to run `playbook:business-pricing` next?"
 
 The user picks yes/no/different playbook. On yes, invoke `/upg-run <chained-id>` directly.
 

package/skills/upg-schema-changelog/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: upg-schema-changelog
-description: "Generate a schema changelog — what changed between versions, migration notes, breaking changes"
+description: "Generate a schema changelog: what changed between versions, migration notes, breaking changes"
 user-invocable: false
 audience: advanced
 argument-hint: "[from_version] [to_version] or 'latest'"
 category: schema
 ---
 
-> ⚠️ **Advanced skill** — intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
+> ⚠️ **Advanced skill**: intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
 
-# /upg-schema-changelog — Schema Changelog Generator
+# /upg-schema-changelog: Schema Changelog Generator
 
 You are a schema changelog generator. Your job is to diff the UPG schema between versions and produce a human-readable changelog that tells adopters what changed, why, and how to migrate.
 
@@ -17,7 +17,7 @@ You are a schema changelog generator. Your job is to diff the UPG schema between
 
 ## When to Use
 
-- After a batch of schema changes — before cutting a release
+- After a batch of schema changes; before cutting a release
 - When preparing documentation for external adopters
 - When someone asks "what changed in v0.2.0?"
 - Before merging a PR that touches `packages/upg-spec/src/`
@@ -112,10 +112,10 @@ For each change, classify as:
 
 | Classification | Meaning | Migration impact |
 |----------------|---------|-----------------|
-| **Additive** | New types, edges, properties, or domains | None — old files still valid |
+| **Additive** | New types, edges, properties, or domains | None; old files still valid |
 | **Deprecation** | Type marked deprecated with replacement | Warn on load, auto-migrate if possible |
 | **Breaking** | Type removed, property renamed, edge direction changed | Old files need migration |
-| **Enhancement** | New optional fields on existing interfaces | None — backwards compatible |
+| **Enhancement** | New optional fields on existing interfaces | None; backwards compatible |
 
 ## Output Format
 
@@ -124,40 +124,40 @@ Generate a markdown changelog:
 ```markdown
 # UPG Schema Changelog
 
-## [0.2.0] — YYYY-MM-DD
+## [0.2.0]: YYYY-MM-DD
 
 ### Summary
-One paragraph describing the theme of this release (e.g., "Engineering lens support —
+One paragraph describing the theme of this release (e.g., "Engineering lens support;
 four new entity types for debugging workflows, causal edge vocabulary, and edge confidence.")
 
 ### Added
 
 #### Entity Types
-- `investigation` (Engineering) — Active thread of inquiry for debugging and architecture exploration
-- `root_cause` (Engineering) — Underlying architectural or systemic issue
-- `symptom` (Engineering) — Observable behavior produced by a root cause
-- `fix` (Engineering) — Specific change that resolved an issue
-- (Note: v0.2.0 consolidated `design_decision`, `architecture_decision`, and `product_decision` into the single `decision` type with a `layer` property — see 0.2.0 migration entry.)
+- `investigation` (Engineering): Active thread of inquiry for debugging and architecture exploration
+- `root_cause` (Engineering): Underlying architectural or systemic issue
+- `symptom` (Engineering): Observable behavior produced by a root cause
+- `fix` (Engineering): Specific change that resolved an issue
+- (Note: v0.2.0 consolidated `design_decision`, `architecture_decision`, and `product_decision` into the single `decision` type with a `layer` property; see 0.2.0 migration entry.)
 
 #### Edge Types
-- `causes` — root_cause → symptom/bug (causal production)
-- `revealed_by` — investigation/fix → bug/root_cause (discovery)
-- `same_root_cause` — symptom ↔ symptom (shared cause)
-- `subsumes` — root_cause → bug (architectural fix eliminates quick-fix)
-- `affects` — bug/root_cause → service/feature (impact)
-- `screen_implements_feature` — screen → feature (design-to-spec bridge)
+- `causes`: root_cause → symptom/bug (causal production)
+- `revealed_by`: investigation/fix → bug/root_cause (discovery)
+- `same_root_cause`: symptom ↔ symptom (shared cause)
+- `subsumes`: root_cause → bug (architectural fix eliminates quick-fix)
+- `affects`: bug/root_cause → service/feature (impact)
+- `screen_implements_feature`: screen → feature (design-to-spec bridge)
   [... and others]
 
 #### Properties
-- `InvestigationProperties` — investigation_status, hypothesis, findings, session_id, category
-- `RootCauseProperties` — severity, category, affected_area, verified
-- `SymptomProperties` — reproducibility, frequency, steps_to_reproduce
-- `FixProperties` — commit, files_changed, verified, fixed_date
-- `DecisionProperties` — layer ('engineering' | 'design' | 'product'), status, context, decision, consequences
+- `InvestigationProperties`: investigation_status, hypothesis, findings, session_id, category
+- `RootCauseProperties`: severity, category, affected_area, verified
+- `SymptomProperties`: reproducibility, frequency, steps_to_reproduce
+- `FixProperties`: commit, files_changed, verified, fixed_date
+- `DecisionProperties`: layer ('engineering' | 'design' | 'product'), status, context, decision, consequences
 
 #### Edge Interface
-- `UPGEdge.confidence` — Optional causal confidence: `'verified' | 'likely' | 'speculative'`
-- `UPGEdge.note` — Optional note explaining why this relationship exists
+- `UPGEdge.confidence`: Optional causal confidence: `'verified' | 'likely' | 'speculative'`
+- `UPGEdge.note`: Optional note explaining why this relationship exists
 
 ### Changed
 - Engineering domain expanded from 22 to 26 entity types
@@ -170,7 +170,7 @@ four new entity types for debugging workflows, causal edge vocabulary, and edge
 (none in this release)
 
 ### Migration Guide
-No migration needed — all changes are additive. Existing .upg files are fully compatible.
+No migration needed; all changes are additive. Existing .upg files are fully compatible.
 Old tools that don't recognise new types will preserve them as opaque nodes (type stored as string).
 
 ### Cascade Status
@@ -187,8 +187,8 @@ Old tools that don't recognise new types will preserve them as opaque nodes (typ
 
 Save the changelog in two places:
 
-1. **`packages/upg-spec/CHANGELOG.md`** — Cumulative, all versions. Append new version at the top.
-2. **PR description** — Include the summary section in the PR body for review.
+1. **`packages/upg-spec/CHANGELOG.md`**: Cumulative, all versions. Append new version at the top.
+2. **PR description**: Include the summary section in the PR body for review.
 
 If the file doesn't exist yet, create it with a header: