@unified-product-graph/cli 0.6.0

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

@@ -0,0 +1,231 @@
+---
+name: upg-schema-changelog
+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.
+
+# /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.
+
+**This is an internal development skill for schema governance and external communication.**
+
+## When to Use
+
+- 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/`
+
+## Input Modes
+
+**Mode 1: Diff against git**
+```
+/upg-schema-changelog latest
+```
+Compares current working state against the last tagged version.
+
+**Mode 2: Between specific versions**
+```
+/upg-schema-changelog 0.1.0 0.2.0
+```
+
+**Mode 3: Current PR changes**
+```
+/upg-schema-changelog pr
+```
+Compares current branch against `origin/dev`.
+
+## Data Sources
+
+### Entity Types
+```bash
+# Current state
+grep "name:" packages/upg-spec/src/registry/entity-meta.ts
+
+# Previous state (from git)
+git show origin/dev:packages/upg-spec/src/registry/entity-meta.ts | grep "name:"
+```
+
+### Edge Types
+```bash
+# Current edge catalog entries
+grep -cE "^  [a-z_]+: \{" packages/upg-spec/src/catalog/edge-catalog.ts
+git show origin/dev:packages/upg-spec/src/catalog/edge-catalog.ts | grep -cE "^  [a-z_]+: \{"
+```
+
+### Properties
+```bash
+# Current property interfaces
+grep "export interface.*Properties" packages/upg-spec/src/properties/domains/*.ts
+```
+
+### UPGEdge / UPGBaseNode
+```bash
+# Check for structural shape changes
+git diff origin/dev -- packages/upg-spec/src/shapes/
+```
+
+## Analysis Steps
+
+### Step 1: Diff Entity Types
+
+Compare `entity-meta.ts` between versions:
+
+**Added types:** New entries (new `type_id` values)
+**Deprecated types:** Entries where `maturity` changed to `'deprecated'`
+**Removed types:** Entries where `maturity` changed to `'removed'`
+**Renamed types:** Entries where `name` changed but `type_id` stayed the same
+
+### Step 2: Diff Edge Types
+
+Compare the `UPG_EDGE_CATALOG` in `catalog/edge-catalog.ts` (and the derived `UPG_EDGE_PAIR_MAP`):
+
+**Added edges:** New key-value pairs
+**Removed edges:** Pairs that existed before but don't now
+**Renamed edges:** Same key, different value (semantic rename)
+
+### Step 3: Diff Properties
+
+Compare property interfaces in `properties/*.ts`:
+
+**New interfaces:** New `export interface XxxProperties`
+**Modified interfaces:** Changed fields in existing interfaces
+**New base fields:** Changes to `UPGBaseNode` or `UPGEdge` in `schema.ts` / `types.ts`
+
+### Step 4: Diff Domains
+
+Compare `domains.ts`:
+
+**New domains:** New entries in `UPG_DOMAINS`
+**Modified domains:** Types added or removed from existing domains
+**Domain renames:** Same types, different domain id/label
+
+### Step 5: Classify Changes
+
+For each change, classify as:
+
+| Classification | Meaning | Migration impact |
+|----------------|---------|-----------------|
+| **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 |
+
+## Output Format
+
+Generate a markdown changelog:
+
+```markdown
+# UPG Schema Changelog
+
+## [0.2.0] — YYYY-MM-DD
+
+### Summary
+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.)
+
+#### 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)
+  [... 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
+
+#### Edge Interface
+- `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
+- Design domain expanded from 21 to 22 entity types
+
+### Deprecated
+(none in this release)
+
+### Breaking Changes
+(none in this release)
+
+### Migration Guide
+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
+| Layer | Status |
+|-------|--------|
+| @unified-product-graph/core | ✅ Updated |
+| upg-mcp-server | ✅ Updated (lens-aware context) |
+| apps/graph | ✅ Updated (all registries) |
+| upg-cloud-server | 🟡 Edge confidence/note not persisted yet |
+| apps/upg-site | ⏸️ Docs update deferred |
+```
+
+## Where to Save
+
+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.
+
+If the file doesn't exist yet, create it with a header:
+
+```markdown
+# UPG Schema Changelog
+
+All notable changes to the UPG specification are documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+---
+```
+
+## Automation Hooks
+
+### Pre-release Check
+
+Before tagging a release, run this skill to ensure the changelog is up to date:
+
+```bash
+# Compare current vs last tag
+git diff $(git describe --tags --abbrev=0) -- packages/upg-spec/src/
+```
+
+If there are schema changes not reflected in CHANGELOG.md, flag them.
+
+### PR Template Integration
+
+When a PR touches `packages/upg-spec/src/`, the changelog section should be included in the PR description. The skill can generate this automatically.
+
+## Key Principles
+
+- **Theme over list.** Start with a one-paragraph summary that tells the story ("Engineering lens support"), not just a list of changes.
+- **Migration is the most important section.** External adopters care most about "will my files break?"
+- **Cascade status shows completeness.** A schema change isn't done until all layers are updated.
+- **Additive changes are safe.** Any change that only adds new types, edges, or optional properties is backwards compatible. Say so explicitly.
+- **Breaking changes need a migration guide.** Step-by-step instructions, not just "things changed."
+- **Keep it diffable.** The changelog should itself be git-friendly. Each version is a section with clear headers.
+
+---
+Internal development skill for UPG schema governance.

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

@@ -0,0 +1,243 @@
+---
+name: upg-schema-consolidate
+description: "Evaluate whether entity types should merge — shared properties, structural analysis, migration path"
+user-invocable: false
+audience: advanced
+argument-hint: "[type_a] [type_b] or [domain]"
+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.
+
+# /upg-schema-consolidate — Entity Type Consolidation
+
+You are a schema analyst. Your job is to evaluate whether two or more entity types should be consolidated into a single type with a discriminator property, or kept separate. You do this through structured analysis — not gut feeling.
+
+**This is an internal development skill for schema governance.**
+
+## When to Use
+
+- Someone notices two types that "feel the same" (e.g., `architecture_decision` and `design_decision`)
+- Schema review reveals types with >70% property overlap
+- User feedback suggests confusion between similar types
+- Domain audit surfaces redundancy
+- Before adding a new type that resembles an existing one
+
+## Input Modes
+
+**Mode 1: Compare specific types**
+```
+/upg-schema-consolidate architecture_decision design_decision
+```
+
+**Mode 2: Scan a domain for candidates**
+```
+/upg-schema-consolidate engineering
+```
+
+## Analysis Framework
+
+### Step 1: Property Overlap Analysis
+
+Read the property interfaces from `packages/upg-spec/src/properties/`. Compare field by field:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+PROPERTY OVERLAP: [type_a] vs [type_b]
+
+| Property | type_a | type_b | Shared? |
+|----------|--------|--------|---------|
+| status   | ✓ (proposed/accepted/deprecated/superseded) | ✓ (proposed/accepted/deprecated/superseded) | ✓ identical |
+| context  | ✓ string | ✓ string | ✓ identical |
+| severity | ✓ UPGAssessment | ✗ | ✗ |
+
+Overlap: X/Y properties shared (Z%)
+```
+
+**Threshold:** >70% overlap = consolidation candidate. <40% = keep separate. 40-70% = needs deeper analysis.
+
+### Step 2: Structural Position Analysis
+
+This is the critical test. Check 4 structural dimensions:
+
+**2a. Parent types** — Do they have the same canonical parent?
+```
+Read UPG_VALID_CHILDREN in grammar/hierarchy.ts
+- type_a parent: bounded_context
+- type_b parent: design_system
+→ DIFFERENT parents = structural divergence
+```
+
+**2b. Child types** — Do they have the same children?
+```
+Search UPG_VALID_CHILDREN for entries where value = type_a or type_b
+- type_a children: technical_debt_item
+- type_b children: (none)
+→ DIFFERENT children = structural divergence
+```
+
+**2c. Edge types** — Do they participate in the same relationships?
+```
+Search UPG_EDGE_CATALOG in catalog/edge-catalog.ts for both types
+- type_a edges: context_has_decision, decision_has_technical_debt_item
+- type_b edges: decision_informs_decision, decision_affects_component
+→ DIFFERENT edges = semantic divergence
+```
+
+**2d. Domain membership** — Are they in the same domain?
+```
+Check registry/domains.ts
+- type_a: engineering
+- type_b: design
+→ DIFFERENT domains = role divergence
+```
+
+**Score the structural analysis:**
+- 4/4 same → Strong consolidation candidate
+- 3/4 same → Likely consolidation candidate
+- 2/4 same → Probably keep separate, but discuss
+- 0-1/4 same → Keep separate
+
+### Step 3: Usage Context Analysis
+
+Check how each type is used in practice:
+
+**3a. Skill references** — Which skills create/reference each type?
+```
+grep -r "type_a\|type_b" packages/upg-mcp-server/skills/
+```
+
+**3b. Lens relevance** — Do they appear in different lenses?
+If type_a is surfaced in the engineering lens and type_b in the design lens, consolidation would muddy lens clarity.
+
+**3c. Real-world mental models** — Would users think of these as "the same thing with a label" or "fundamentally different activities"?
+
+This is where you engage the human. Ask:
+
+> When you think about [type_a] and [type_b], do they feel like:
+> 1. The same thing in different contexts (like "meeting" whether it's a standup or a retro)
+> 2. Related but distinct activities (like "writing" vs "editing")
+> 3. Completely different things that happen to share some fields
+
+### Step 4: Consolidation Decision
+
+Present the verdict as a structured recommendation:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+VERDICT: [CONSOLIDATE | KEEP SEPARATE | NEEDS DISCUSSION]
+
+Property overlap: X% [HIGH/MEDIUM/LOW]
+Structural alignment: Y/4 [ALIGNED/DIVERGENT]
+Usage context: [SAME/DIFFERENT]
+
+Recommendation: [explanation]
+```
+
+### Step 5: If Consolidating — Migration Design
+
+If the decision is to consolidate:
+
+**5a. Define the unified type:**
+```
+Unified type: decision
+Discriminator: layer: 'engineering' | 'design' | 'product'
+Properties: union of both property sets
+  - Shared properties remain as-is
+  - Type-specific properties become optional (only relevant when discriminator matches)
+```
+
+**5b. Define the migration:**
+```
+Deprecated types: architecture_decision → decision (layer: 'engineering')
+                  design_decision      → decision (layer: 'design')
+                  product_decision     → decision (layer: 'product')
+
+Edge migrations (v0.2.0):
+  context_has_architecture_decision           → context_has_decision
+  design_decision_informs_architecture_decision → decision_informs_decision
+
+Parent migration:
+  architecture_decision parent=bounded_context → decision parent=bounded_context (when layer='engineering')
+  design_decision       parent=design_system   → decision parent=design_system   (when layer='design')
+```
+
+**5c. Backwards compatibility:**
+- Old types stay in `DeprecatedUPGEntityType` in types.ts
+- `entity-meta.ts` marks them as `deprecated` with `replacement: 'decision'`
+- `upg-migrate` skill handles the retyping
+- Old `.upg` files with `architecture_decision` still parse and auto-migrate
+
+**5d. Cascade the change** using `/upg-schema-update`
+
+### Step 5 (Alternative): If Keeping Separate — Document Why
+
+If the decision is to keep separate, create a brief decision record:
+
+```
+## Schema Decision: [type_a] vs [type_b]
+
+**Date:** YYYY-MM-DD
+**Decision:** Keep separate
+**Why:** [structural divergence explanation]
+**Revisit when:** [conditions that would change this decision]
+```
+
+Save to a decisions log in your project (wherever your team keeps ADRs) for future reference.
+
+## Domain Scan Mode
+
+When called with a domain name instead of specific types:
+
+1. List all types in the domain (from `domains.ts`)
+2. For each pair, compute property overlap percentage
+3. Flag pairs with >60% overlap as candidates
+4. Present a summary table:
+
+```
+CONSOLIDATION CANDIDATES IN [DOMAIN]
+
+| Pair | Overlap | Parents | Verdict |
+|------|---------|---------|---------|
+| type_a ↔ type_b | 85% | Same | 🟡 Review |
+| type_c ↔ type_d | 45% | Different | ✅ Keep |
+| type_e ↔ type_f | 92% | Same | 🔴 Consolidate |
+```
+
+Then deep-dive into any pair the user wants to investigate.
+
+## Known Consolidation Precedents
+
+These consolidations have already happened in UPG and can be referenced as patterns:
+
+| Old Types | Unified As | Discriminator | Version |
+|-----------|-----------|---------------|---------|
+| `pain_point`, `user_need` | `need` | `valence: 'pain' \| 'gap' \| 'desire' \| 'constraint'` | 0.1.0 |
+| `north_star_metric`, `input_metric`, `kpi`, `metric_definition` | `metric` | `designation` property | 0.1.0 |
+| `research_insight`, `finding`, `ux_insight` | `insight` | `source_domain` / `insight_level` | 0.1.0 |
+| `ab_test`, `growth_experiment`, `pricing_experiment` | `experiment` | `experiment_type` | 0.1.0 |
+| `security_incident` | `incident` | `incident_type: 'security'` | 0.1.0 |
+| `defect_report` | `support_ticket` | `ticket_designation: 'defect'` | 0.1.0 |
+| `onboarding_flow` | `user_flow` | `flow_type: 'onboarding'` | 0.1.0 |
+| `risk_item` | `risk` | `risk_domain: 'program'` | 0.1.0 |
+| `architecture_decision`, `design_decision`, `product_decision` | `decision` | `layer: 'engineering' \| 'design' \| 'product'` | 0.2.0 |
+| `jtbd` | `job` | (renamed, no discriminator) | 0.2.0 |
+| `how_might_we` | `design_question` | (renamed — framework-neutral) | 0.2.0 |
+| `sli`, `slo`, `sla` | `service_level_indicator`, `service_level_objective`, `service_level_agreement` | (acronyms expanded) | 0.2.0 |
+| `customer_segment_bm`, `target_customer_segment` | `market_segment` | — | 0.2.0 |
+| `channel_bm` | `distribution_channel` | — | 0.2.0 |
+| `campaign` | `growth_campaign` | (disambiguated from marketing_campaign_plan) | 0.2.0 |
+| `segment` | `behavioral_segment` | (disambiguated from market_segment) | 0.2.0 |
+| `package` | `pricing_tier` | — | 0.2.0 |
+| `internal_doc` | `document` | `document_type` — audience=internal | 0.2.0 |
+
+## Key Principles
+
+- **Structure trumps semantics.** Two types with the same name but different parents, children, and edges are genuinely different. Two types with different names but identical structural positions should merge.
+- **The discriminator must be a property, not a tag.** Tags are freeform; properties are typed. Use an enum property (e.g., `decision_domain: 'architecture' | 'design'`).
+- **Migration is non-negotiable.** Every consolidation must preserve existing data. Old types become deprecated, not deleted.
+- **Ask the user.** The mental model test (Step 3c) can't be automated. Engage.
+- **Document the decision either way.** Whether you consolidate or keep separate, record why.
+
+---
+Internal development skill for UPG schema governance.