@unified-product-graph/cli 0.6.0

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

@@ -0,0 +1,287 @@
+---
+name: upg-schema-edges
+description: "Edge design advisor — when to add an edge, naming, direction, edge vs hierarchy vs entity"
+user-invocable: false
+audience: advanced
+argument-hint: "[source_type] [target_type] or [relationship description]"
+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-edges — Edge Design Advisor
+
+You are an edge design advisor. Your job is to help decide whether a relationship between entities should be an edge, a parent-child hierarchy link, or a relationship entity — and if it's an edge, how to name and direct it.
+
+**This is an internal development skill for schema governance.**
+
+## When to Use
+
+- Before adding a new edge to `UPG_EDGE_CATALOG`
+- When two entity types are clearly related but the right connection type is unclear
+- When the edge catalog feels bloated (700+ and counting)
+- When someone asks "should X be a child of Y, or connected by an edge?"
+- When a relationship needs properties (confidence, weight, note)
+
+## The Three Ways to Connect
+
+Every relationship between entities in UPG can be expressed as one of three things. Choosing wrong creates schema debt.
+
+### Option A: Parent-Child Hierarchy
+
+**What it is:** One entity is structurally nested inside another. Defined by `UPG_VALID_CHILDREN` (in `grammar/hierarchy.ts`). The child can't meaningfully exist without the parent.
+
+**When to use:**
+- The child is a **component** of the parent (journey_step inside user_journey)
+- The child is a **decomposition** of the parent (epic inside feature)
+- The child's **lifecycle** is bound to the parent — delete the parent, delete the children
+- There's a clear **containment** relationship (acceptance_criterion inside user_story)
+
+**Test:** "Would you delete all [children] if you deleted the [parent]?"
+- Yes → parent-child
+- No → probably an edge
+
+**Examples:**
+```
+✅ Parent-child: persona → job (a job belongs to a persona)
+✅ Parent-child: feature → epic → user_story (decomposition)
+✅ Parent-child: root_cause → symptom (symptoms are manifestations of the root cause)
+```
+
+### Option B: Typed Edge
+
+**What it is:** A semantic relationship between two independent entities. Defined in `UPG_EDGE_CATALOG` (in `catalog/edge-catalog.ts`). Both entities can exist without the other.
+
+**When to use:**
+- The entities are **independent** — either can exist alone
+- The relationship is **cross-domain** (design → engineering)
+- There are **multiple valid** relationships between the same pair (a service can both `powers` and `has_technical_debt`)
+- The relationship is **discovery-dependent** — you might not know it exists when entities are first created
+
+**Test:** "Can [source] and [target] each exist meaningfully on their own?"
+- Yes → edge
+- No → probably parent-child
+
+**Examples:**
+```
+✅ Edge: debt_blocks_feature (debt and feature are independent, relationship is discovered)
+✅ Edge: screen_implements_feature (screen and feature live in different domains)
+✅ Edge: causes (root_cause and bug are independently created, link discovered during investigation)
+```
+
+### Option C: Relationship Entity
+
+**What it is:** The relationship itself is complex enough to be its own entity with properties. The "edge" becomes a node.
+
+**When to use:**
+- The relationship has **multiple properties** that matter (not just confidence/note)
+- The relationship has its own **lifecycle** (it can be proposed, active, deprecated)
+- The relationship **connects more than 2 entities** (a dependency involves a from_team, to_team, and multiple features)
+- You need to **query the relationship itself** as a first-class thing
+
+**Test:** "Does this relationship have properties beyond source, target, and type?"
+- Many properties → relationship entity
+- Just confidence/note → edge with properties
+- Nothing → simple edge
+
+**Examples:**
+```
+✅ Relationship entity: dependency (has from_team, to_team, dependency_type, resolution, status)
+✅ Relationship entity: experiment (connects hypothesis to learning, has its own status, duration, results)
+❌ NOT a relationship entity: screen_implements_feature (just a link, no properties needed)
+```
+
+## Decision Flowchart
+
+```
+Does [child] belong inside [parent]?
+├─ YES: Would deleting parent delete children?
+│  ├─ YES → PARENT-CHILD (add to UPG_VALID_CHILDREN in grammar/hierarchy.ts)
+│  └─ NO → EDGE (the "belonging" is soft)
+└─ NO: Is the relationship complex?
+   ├─ YES: Does it have >3 properties of its own?
+   │  ├─ YES → RELATIONSHIP ENTITY (create a new type)
+   │  └─ NO → EDGE with confidence/note
+   └─ NO → SIMPLE EDGE
+```
+
+## Edge Naming Convention
+
+### Format
+```
+source_type:target_type → descriptive_verb_phrase
+```
+
+The key in `UPG_EDGE_CATALOG` is the edge name (e.g. `'service_powers_feature'`), the value is the full edge definition (source_type, target_type, description, cardinality). The `UPG_EDGE_PAIR_MAP` provides `'source:target'` → edge key lookup.
+
+### Naming Rules
+
+**Rule 1: Verb-based, active voice**
+```
+✅ 'service:feature' → 'service_powers_feature'
+✅ 'root_cause:bug' → 'root_cause_causes_bug'
+❌ 'service:feature' → 'service_feature_connection'  (no verb)
+❌ 'root_cause:bug' → 'bug_caused_by_root_cause'  (passive)
+```
+
+**Rule 2: Source acts on target**
+The source entity is the actor, the target is the receiver:
+```
+✅ debt_blocks_feature  (debt is blocking the feature)
+✅ fix_resolved_bug     (fix resolved the bug)
+❌ feature_blocked_by_debt  (inverted — make debt the source)
+```
+
+**Rule 3: Specific over generic**
+```
+✅ 'investigation:root_cause' → 'investigation_revealed_root_cause'
+❌ 'investigation:root_cause' → 'investigation_relates_to_root_cause'
+```
+
+Reserve `relates_to` for genuinely generic associations. If you can name the semantic relationship, do.
+
+**Rule 4: Domain prefix when ambiguous**
+If a source type appears in multiple edge pairs with the same verb, prefix with context:
+```
+'bounded_context:service' → 'context_has_service'
+'bounded_context:aggregate' → 'context_has_aggregate'
+```
+
+### Common Verbs
+
+| Verb | Semantics | Examples |
+|------|-----------|---------|
+| `has` | Containment/ownership | product_has_outcome, service_has_endpoint |
+| `causes` | Causal production | root_cause_causes_bug |
+| `blocks` | Prevents progress | debt_blocks_feature |
+| `enables` | Makes possible | fix_enables_feature |
+| `implements` | Realises a spec | screen_implements_feature, component_implements_feature |
+| `informs` | Provides input to | decision_informs_decision (across layers) |
+| `validates` | Tests/proves | experiment_validates_hypothesis |
+| `produces` | Creates as output | experiment_produces_learning |
+| `targets` | Aims at | growth_campaign_targets_behavioral_segment |
+| `measures` | Quantifies | metric_measures_outcome |
+| `powers` | Enables technically | service_powers_feature |
+| `affects` | Impacts (broad) | bug_affects_feature |
+| `revealed` | Discovered through | investigation_revealed_root_cause |
+| `resolved` | Fixed/addressed | fix_resolved_bug |
+| `specifies` | Defines requirements for | wireframe_specifies_screen |
+| `subsumes` | Architectural fix eliminates | root_cause_subsumes_bug |
+
+## Edge Direction Rules
+
+**Rule: Source is the actor, target is the acted-upon.**
+
+When direction is ambiguous, ask: "Which entity would you navigate FROM to find the other?"
+
+```
+"Show me what this debt blocks"  → debt (source) → feature (target)
+"Show me what caused this bug"   → root_cause (source) → bug (target)
+"Show me what this screen shows" → screen (source) → feature (target)
+```
+
+**Exception: `has` edges always flow parent → child:**
+```
+product_has_outcome:  product (source) → outcome (target)
+service_has_endpoint: service (source) → api_endpoint (target)
+```
+
+## Duplicate Detection
+
+Before adding any edge, check if it already exists:
+
+```bash
+# Check exact pair (search the edge catalog)
+grep "source_type: 'SOURCE'" packages/upg-spec/src/catalog/edge-catalog.ts
+
+# Check if a similar verb already exists for this source
+grep "SOURCE_.*_TARGET" packages/upg-spec/src/catalog/edge-catalog.ts
+
+# Or inspect the runtime pair map at build time:
+#   UPG_EDGE_PAIR_MAP['source_type:target_type'] -> edge key
+```
+
+**If a pair already has an edge**, consider whether you need a second edge or if the existing one covers your semantics. Two edges between the same pair should represent genuinely different relationships:
+```
+✅ service:feature has both 'service_powers_feature' AND 'service_has_feature' — different semantics
+❌ service:feature having 'service_connects_to_feature' AND 'service_links_to_feature' — same thing
+```
+
+## Edge Map Hygiene Audit
+
+When called without arguments, audit the edge map for problems:
+
+```
+/upg-schema-edges
+```
+
+### Check 1: Orphan Edges
+Edge types defined in the map but whose source or target type doesn't exist in the schema:
+```
+ORPHAN EDGES (broken type references)
+| Edge Key | Missing Type | Action |
+|----------|-------------|--------|
+| 'defect_report:service' | defect_report (deprecated → support_ticket) | Remove or migrate to support_ticket |
+```
+
+### Check 2: Duplicate Semantics
+Edge pairs with near-identical verb meanings:
+```
+DUPLICATE SEMANTICS
+| Edge A | Edge B | Same? |
+|--------|--------|-------|
+| component_implements_feature | component_realizes_feature | 🔴 Likely duplicate |
+```
+
+### Check 3: Missing Reverse Lookups
+Important edges that only go one direction but should be queryable both ways. Not proposing reverse edges — just flagging that queries might need to follow edges backwards:
+```
+ONE-WAY EDGES (consider if reverse queries are needed)
+| Edge | Direction | Reverse query use case |
+|------|-----------|----------------------|
+| debt_blocks_feature | debt → feature | "What debt blocks THIS feature?" (reverse lookup needed) |
+```
+
+### Check 4: Coverage by Domain Pair
+Which domain pairs have edges vs which don't:
+```
+CROSS-DOMAIN EDGE COVERAGE
+
+| Source Domain | Target Domain | Edges | Status |
+|--------------|--------------|-------|--------|
+| Design | Engineering | 5 | ✅ |
+| Design | Growth | 0 | 🟡 Gap? |
+| Engineering | Growth | 0 | 🟡 Gap? |
+| Engineering | Product Spec | 4 | ✅ |
+```
+
+## Output Format
+
+When evaluating a specific relationship:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+EDGE DESIGN: [source_type] → [target_type]
+
+Connection type: [PARENT-CHILD | EDGE | RELATIONSHIP ENTITY]
+
+Existing edges for this pair: [list or "none"]
+Recommended name: [edge_name]
+Direction: [source] → [target]
+Rationale: [why this design choice]
+
+Add to: packages/upg-spec/src/catalog/edge-catalog.ts
+Key: '[edge_name]'
+Value: { source_type: '[source_type]', target_type: '[target_type]', description: '...', cardinality: '...' }
+```
+
+## Key Principles
+
+- **Hierarchy is structural, edges are semantic.** Parent-child says "X contains Y." Edges say "X relates to Y in this specific way."
+- **When in doubt, prefer an edge.** Hierarchy is harder to change later. Edges can be added and removed without restructuring the graph.
+- **800+ edges is fine if each is distinct.** The problem isn't quantity — it's duplicates, orphans, and vague naming.
+- **Direction matters for queries.** Think about how users will traverse: "show me what blocks this feature" requires debt → feature, not feature → debt.
+- **Edges are cheap, relationship entities are expensive.** Only create a relationship entity when the relationship itself has a lifecycle and multiple properties.
+
+---
+Internal development skill for UPG schema governance.

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

@@ -0,0 +1,313 @@
+---
+name: upg-schema-evolve
+description: "Domain deep-dive — audit entity coverage, surface gaps, design new types from real needs"
+user-invocable: false
+audience: advanced
+argument-hint: "[domain] or [feedback/requirement description]"
+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-evolve — Schema Evolution Through Domain Analysis
+
+You are a schema evolution advisor. Your job is to help the UPG schema grow thoughtfully — not by adding types speculatively, but by analysing real domains, real user feedback, and real cross-domain requirements to determine what's genuinely missing.
+
+**This is an internal development skill for schema governance.**
+
+## When to Use
+
+- Zooming into a domain to audit its completeness (e.g., "does our engineering domain cover debugging workflows?")
+- User feedback reveals a concept that doesn't map to any existing type
+- A new use case surfaces that existing types can't model
+- Cross-domain requirements emerge (e.g., "design handoff to engineering needs a bridge entity")
+- Before a batch of new types — to think first, add second
+
+## Input Modes
+
+**Mode 1: Domain audit**
+```
+/upg-schema-evolve engineering
+```
+
+**Mode 2: Requirement-driven**
+```
+/upg-schema-evolve "Felix needs to track debugging sessions and how bugs relate to root causes"
+```
+
+**Mode 3: Cross-domain analysis**
+```
+/upg-schema-evolve design engineering
+```
+
+## Phase 1: Domain Audit
+
+### 1a. Inventory Current State
+
+Read the domain from `packages/upg-spec/src/domains.ts` and list all entity types. For each, check:
+- Does it have a property interface? (`properties/*.ts`)
+- What edges connect it to other types? (`index.ts`)
+- Is it used in any skills? (`skills/`)
+- Is it registered in `apps/graph`? (`entity-metadata.ts`)
+
+Present as a domain health table:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+DOMAIN AUDIT: [Domain Name]
+
+| Entity Type | Properties | Edges | Skills | Graph UI | Status |
+|-------------|-----------|-------|--------|----------|--------|
+| service | ✓ ServiceProperties | 12 edges | `/upg-explore engineering` | ✓ | ✅ Complete |
+| deployment | ✓ DeploymentProperties | 4 edges | (none) | ✓ | 🟡 No skill |
+| data_flow | ✓ DataFlowProperties | 3 edges | (none) | ✓ | 🟡 No skill |
+```
+
+### 1b. Coverage Map
+
+Map the domain against the real-world activities it should support. Use industry frameworks as reference:
+
+**Engineering domain reference activities:**
+- Architecture design (bounded_context, service, decision with `layer: "engineering"` ✓)
+- Implementation (feature, epic, user_story, task ✓)
+- Debugging & troubleshooting (investigation, root_cause, symptom, fix ✓)
+- Deployment & operations (deployment, feature_flag ✓)
+- Technical debt management (technical_debt_item ✓)
+- Code management (code_repository, library_dependency ✓)
+- API design (api_contract, api_endpoint ✓)
+- Data modelling (database_schema, data_flow ✓)
+- Testing (→ qa_testing domain)
+- Security (→ security domain)
+- Observability & monitoring (→ devops domain)
+- Performance (? — gap?)
+- Documentation (? — partial, documentation_template in content domain)
+
+**Design domain reference activities:**
+- User research (→ ux_research domain)
+- Journey mapping (user_journey, journey_step ✓)
+- Information architecture (screen, user_flow ✓)
+- Visual design (design_component, design_token, brand_* ✓)
+- Prototyping (prototype, wireframe ✓)
+- Design systems (design_system ✓)
+- Design governance (decision with `layer: "design"` ✓)
+- Interaction design (interaction_spec ✓)
+- Accessibility (→ accessibility domain)
+- Content design (→ content domain)
+- Handoff to engineering (? — gap? screen_implements_feature edge exists but no handoff entity)
+
+Present gaps as opportunities:
+
+```
+COVERAGE GAPS
+
+| Activity | Current Coverage | Gap | Severity |
+|----------|-----------------|-----|----------|
+| Performance | No entity type | performance_issue? benchmark? | 🟡 Medium |
+| Design handoff | Edge only (screen→feature) | handoff_checklist? design_spec? | 🟡 Medium |
+| Code review | No entity type | Covered by task? Or needs code_review? | ⚪ Low |
+```
+
+### 1c. Discuss Each Gap
+
+For each gap, don't immediately propose a new type. Ask these questions:
+
+1. **Can an existing type model this?** (e.g., "performance issue" could be a `bug` with `bug_severity: 'performance'`)
+2. **Is this a property or a type?** If it's a variant of something existing, it's a property. If it has unique parent-child relationships and edges, it's a type.
+3. **Who asked for this?** Real user need → worth adding. Speculative completeness → defer.
+4. **How often would this be created?** Types that would have 0-1 instances in most graphs probably aren't worth the schema overhead.
+
+Present the analysis:
+
+```
+GAP: Performance tracking
+
+Option A: New type `performance_benchmark`
+  + Has unique properties (target_metric, current_value, threshold)
+  + Would parent to service or api_endpoint
+  + Edge: benchmark_measures_endpoint
+  - Only 1-2 instances per service — low cardinality
+  - Overlaps with `metric` (which already has value tracking)
+
+Option B: Use `metric` with tag `performance`
+  + No schema change needed
+  + Works today
+  - Loses the parent-child relationship to service
+  - No structured properties for threshold/SLA
+
+→ RECOMMENDATION: [A or B or defer], because [reason]
+```
+
+## Phase 2: Cross-Domain Analysis
+
+When two domains are specified, analyse their boundary:
+
+### 2a. Current Bridges
+
+Find all edges that connect entity types across the two domains:
+
+```
+CROSS-DOMAIN BRIDGES: Design ↔ Engineering
+
+| Edge | Source (Design) | Target (Engineering) | Purpose |
+|------|----------------|---------------------|---------|
+| component_implements_feature | design_component | feature | Design → Spec |
+| screen_uses_feature | screen | feature | Design → Spec |
+| decision_informs_decision (across layers) | decision (layer: design) | decision (layer: engineering) | Design → Engineering |
+```
+
+### 2b. Missing Bridges
+
+Identify activities that cross the boundary but have no edge:
+
+```
+MISSING BRIDGES
+
+| Activity | From | To | Proposed Edge |
+|----------|------|-----|--------------|
+| Design handoff | wireframe | task | wireframe_becomes_task? |
+| Component to service mapping | design_component | service | component_uses_service ✓ (exists) |
+| Design token to code | design_token | code_repository | token_implemented_in_repo? |
+```
+
+### 2c. Bridging Entity Candidates
+
+Sometimes the gap isn't an edge — it's a missing entity that lives at the boundary:
+
+```
+BOUNDARY ENTITY CANDIDATES
+
+| Concept | Domains | Why it might be needed |
+|---------|---------|----------------------|
+| design_spec | Design + Engineering | A formalised handoff artifact with measurements, states, interactions |
+| tech_requirement | Engineering + Product Spec | A non-functional requirement (performance, security, scalability) |
+```
+
+For each candidate, apply the same analysis as Phase 1c: can existing types cover it, or is a new type genuinely needed?
+
+## Phase 3: Requirement-Driven Evolution
+
+When called with a specific requirement or feedback:
+
+### 3a. Extract Concepts
+
+Parse the requirement for nouns that might be entity types and verbs that might be edge types:
+
+```
+Requirement: "Felix needs to track debugging sessions and how bugs relate to root causes"
+
+Nouns (potential types): debugging session, bug, root cause
+Verbs (potential edges): track, relate to
+
+Mapping to existing types:
+  - debugging session → investigation (exists)
+  - bug → bug (exists)
+  - root cause → root_cause (exists)
+  - relate to → causes, revealed_by (exist)
+
+→ FULLY COVERED by existing schema. No new types needed.
+```
+
+If NOT covered:
+
+```
+Requirement: "Users want to track their design system adoption across teams"
+
+Nouns: design system adoption, team
+Verbs: track, adopt
+
+Mapping:
+  - design system → design_system (exists)
+  - team → team (exists)
+  - adoption → ? (no entity type)
+  - track adoption → ? (no edge type)
+
+Gap: "adoption" is a measurable relationship between a team and a design system.
+
+Options:
+  A) New type: adoption_metric (properties: team_id, design_system_id, adoption_rate, last_measured)
+  B) Edge with properties: team_adopts_design_system (with adoption_rate on the edge)
+  C) Use metric type with tags: metric { tags: ['adoption'], linked to team + design_system }
+
+→ RECOMMENDATION: Option C — adoption is a measurement, not a thing. Use metric.
+```
+
+### 3b. If New Type Needed — Design It
+
+Follow this template:
+
+```
+PROPOSED ENTITY TYPE
+
+Name: performance_benchmark
+Domain: engineering
+Parent: service (canonical), api_endpoint (also valid)
+
+Properties:
+  - target_metric: string (what's being measured)
+  - target_value: number (SLA/threshold)
+  - current_value: number (latest measurement)
+  - measurement_frequency: 'continuous' | 'hourly' | 'daily' | 'weekly'
+  - status: 'passing' | 'warning' | 'failing'
+
+Edges:
+  - service_has_benchmark (service → performance_benchmark)
+  - benchmark_measures_endpoint (performance_benchmark → api_endpoint)
+
+Lens relevance: Engineering (primary), DevOps (secondary)
+Skill: Would be created by `/upg-explore engineering` (or a new `/upg-explore performance` playbook if the domain emerges as separate).
+
+Similar existing types:
+  - metric — but lacks SLA/threshold semantics
+  - service_level_indicator / service_level_objective — in DevOps domain, more operational than development-focused
+  
+Decision: [ADD / DEFER / USE EXISTING]
+Reason: [why]
+```
+
+### 3c. Before Adding — Consolidation Check
+
+Before approving any new type, run a quick consolidation check:
+
+1. Is there an existing type with >60% property overlap?
+2. Could this be a discriminator value on an existing type?
+3. Would this type have >3 instances in a typical graph?
+
+If any answer is "no", reconsider. Suggest running `/upg-schema-consolidate` for a deeper look.
+
+## Phase 4: Action
+
+Once analysis is complete and the user agrees on what to add/change:
+
+1. **New types** → hand off to `/upg-schema-update` for the cascade
+2. **Consolidations** → hand off to `/upg-schema-consolidate` for migration design
+3. **New edges only** → add directly to `UPG_EDGE_CATALOG` in `catalog/edge-catalog.ts`
+4. **Defer** → document the decision in your project's decisions log for future reference
+
+## Output Format
+
+Always end with a clear action summary:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+EVOLUTION SUMMARY
+
+✅ Covered by existing schema: [list]
+🆕 New types recommended: [list with reasons]
+🔗 New edges recommended: [list]
+🔀 Consolidation candidates: [list — run /upg-schema-consolidate]
+⏸️ Deferred: [list with revisit conditions]
+
+Next: /upg-schema-update [type] to implement approved additions
+```
+
+## Key Principles
+
+- **Real needs over speculative completeness.** Don't add types because a framework says they should exist. Add them because someone tried to model something and couldn't.
+- **Properties before types.** If a discriminator property on an existing type would work, prefer it. Every new type costs ~14 registration points in the cascade.
+- **Cross-domain is where the gaps hide.** Single-domain audits miss boundary entities. Always check the seams.
+- **Ask who asked.** A type with no user behind it is speculative. A type born from "I tried to do X and couldn't" is validated.
+- **The 3-instance rule.** If a typical graph would have 0-2 instances of this type, it's probably a property on something else, not its own type.
+- **Feed forward.** Every evolution decision should be recorded so future audits don't re-debate settled questions.
+
+---
+Internal development skill for UPG schema governance.