alezmad/whyrating-engine-legacy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add complete URT v5.1 taxonomy framework (11 artifacts)

Browse Source 
Universal Review Taxonomy v5.1 implementation with:
- Track A (Training): A1 Quickstart, A2 QA Protocol, A3 Calibration Set, A4 Full Manual
- Track B (Engineering): B1 Code Registry, B2 Database Schema, B3 Owner Routing, B4 API Contract
- Track C (Analytics): C1 Issue Lifecycle, C2 KPI Mapping Guide
- Track D (Integration): D1 Dashboard Specification

Covers 7 domains, 28 categories, 138 subcodes, 16 causal codes, and 7 metadata dimensions.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
2026-01-24 10:51:41 +00:00
parent a540ab97b1
commit 3eda9bdbfa
13 changed files with 21264 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

627
urt-taxonomy/track-b-engineering/B3-owner-routing.md Normal file
View File

@@ -0,0 +1,627 @@
# B3: Owner Routing Matrix Documentation
## Universal Review Taxonomy v5.1
**Status**: Production Ready
**Release Date**: 2026-01-23
**Prerequisite**: B1-urt-codes.yaml (Code Registry)
**Configuration File**: B3-owner-routing.yaml
---
## Table of Contents
1. [Overview](#1-overview)
2. [Routing Resolution Logic](#2-routing-resolution-logic)
3. [SLA Definitions](#3-sla-definitions)
4. [Escalation Paths](#4-escalation-paths)
5. [On-Call Rotation](#5-on-call-rotation)
6. [Ticketing System Integration](#6-ticketing-system-integration)
7. [Configuration Examples](#7-configuration-examples)
8. [Multi-Location Override Patterns](#8-multi-location-override-patterns)
9. [Special Routing Rules](#9-special-routing-rules)
10. [Appendix: Domain-Team Mapping](#appendix-domain-team-mapping)
---
## 1. Overview
The Owner Routing Matrix maps URT codes to responsible teams and individuals. When feedback is classified using URT codes, the routing matrix determines:
- **Who owns the ticket** (primary team)
- **Who should be notified** (co-owners)
- **When to escalate** (SLA and intensity rules)
- **How quickly to respond** (priority-based SLA)
### Key Principles
1. **Specificity wins**: More specific routes override less specific ones
2. **Safety first**: E4 (Safety) issues always take priority
3. **Intensity drives urgency**: I3 (Strong) triggers auto-escalation
4. **Primary code determines owner**: Secondary codes add co-owners
---
## 2. Routing Resolution Logic
### Resolution Order
Routes are resolved in the following order (most specific first):
```
subcode_overrides > category_overrides > domain_defaults
(O1.01) (O1) (O)
```
### Resolution Algorithm
```
FUNCTION resolve_route(primary_code, secondary_codes, intensity, valence):
# Step 1: Check subcode-level override
IF primary_code IN subcode_overrides:
route = subcode_overrides[primary_code]
# Step 2: Check category-level override
ELSE IF category(primary_code) IN category_overrides:
route = category_overrides[category(primary_code)]
# Step 3: Fall back to domain default
ELSE:
route = domain_defaults[domain(primary_code)]
# Step 4: Apply intensity modifiers
IF intensity == "I3":
route.auto_escalate = TRUE
route.sla_hours = MIN(route.sla_hours, 4)
# Step 5: Add co-owners from secondary codes
FOR code IN secondary_codes:
co_owner = resolve_route(code, [], intensity, valence)
route.co_owners.append(co_owner.team)
# Step 6: Check cross-functional patterns
all_codes = [primary_code] + secondary_codes
FOR pattern IN cross_functional_patterns:
IF pattern.triggered_by(all_codes):
route = merge_routes(route, pattern.route)
RETURN route
```
### Example Resolutions
| Primary Code | Category | Domain | Resolution Path | Final Team |
|--------------|----------|--------|-----------------|------------|
| E2.02 | E2 | E | subcode_overrides["E2.02"] | engineering |
| O2.03 | O2 | O | category_overrides["O2"] | quality_control |
| R4.05 | R4 | R | category_overrides["R4"] | marketing |
| O3.02 | O3 | O | category_overrides["O3"] | fulfillment |
---
## 3. SLA Definitions
### Priority Levels
| Priority | Initial Response | Resolution Target | Update Frequency |
|----------|------------------|-------------------|------------------|
| **Critical** | 1 hour | 4 hours | Every hour |
| **High** | 4 hours | 24 hours | Every 4 hours |
| **Normal** | 24 hours | 72 hours | Daily |
| **Low** | 48 hours | 1 week | Every 2 days |
### Intensity-to-Priority Mapping
| Intensity | Valence | Priority | Auto-Escalate |
|-----------|---------|----------|---------------|
| I3 | V- | Critical | Yes |
| I3 | V+ | High | No |
| I2 | V- | High | No |
| I2 | V+ | Normal | No |
| I1 | V- | Normal | No |
| I1 | V+ | Low | No |
### SLA Override Rules
Certain subcodes have hardcoded SLA overrides that supersede intensity-based SLAs:
| Subcode | Override SLA | Reason |
|---------|--------------|--------|
| E4.01 | 1 hour | Physical safety |
| E4.02 | 2 hours | Health/hygiene |
| E4.03 | 1 hour | Security breach |
| E4.05 | 1 hour | Emergency readiness |
| A3.05 | 4 hours | Discrimination |
| R1.04 | 4 hours | Ethics violation |
---
## 4. Escalation Paths
### Escalation Hierarchy Diagram
```
+--------+
| CEO |
+--------+
|
+---------------------+---------------------+
| | |
+-------+ +-------+ +-------+
| CFO | | COO | | CTO |
+-------+ +-------+ +-------+
| | |
+---------------+ +---------------+ +---------------+
|Finance Director| |Ops Director | |Engineering Lead|
+---------------+ +---------------+ +---------------+
| | |
+---------------+ +---------------+ +---------------+
| Finance Mgr | | Ops Manager | | Tech Lead |
+---------------+ +---------------+ +---------------+
| | |
+---------------+ +---------------+ +---------------+
| Finance Team | | Ops Team | | Eng Team |
+---------------+ +---------------+ +---------------+
```
### Domain-Specific Escalation Paths
```
O (Offering):
Team -> Product Mgr -> Product Director -> VP Product -> COO -> CEO
P (People):
Team -> HR Manager -> HR Director -> CHRO -> CEO
J (Journey):
Team -> Ops Manager -> Ops Director -> COO -> CEO
E (Environment):
Physical: Team -> Facilities Mgr -> Facilities Dir -> COO -> CEO
Digital: Team -> Tech Lead -> Engineering Lead -> CTO -> CEO
A (Access):
Team -> Compliance Mgr -> Compliance Dir -> General Counsel -> CEO
V (Value):
Team -> Finance Mgr -> Finance Dir -> CFO -> CEO
R (Relationship):
Team -> CX Manager -> CX Director -> CMO -> CEO
(Integrity issues go directly to Leadership -> CEO)
```
### Auto-Escalation Triggers
| Trigger | Condition | Escalation Action |
|---------|-----------|-------------------|
| SLA Breach | >100% of SLA elapsed | Escalate +1 level |
| Repeated Issue | Same code 3x in 30 days | Escalate +1 level |
| VIP Customer | Flagged account | Notify director immediately |
| Safety Issue | E4.* with I2+ | Auto-escalate to safety officer |
| Ethics Issue | R1.04 | Auto-escalate to CEO |
---
## 5. On-Call Rotation
### Coverage Requirements
| Team | Coverage | Hours | Handles |
|------|----------|-------|---------|
| Support | 24/7 | All hours | I3, E4.*, security |
| Operations | Extended | 06:00-22:00 | J4, J1, high-priority ops |
| Engineering | On-call | After hours | E2.* critical, outages |
### On-Call Responsibilities
**Primary On-Call (Support)**:
- Monitor all incoming I3 (critical) tickets
- Triage E4 (safety) issues immediately
- Escalate security incidents (E4.03)
- Acknowledge all critical tickets within 15 minutes
**Secondary On-Call (Operations)**:
- Handle J4 (resolution) escalations
- Address J1 (timing) issues affecting active customers
- Coordinate with primary on-call for cross-functional issues
### Holiday Coverage
- Minimum: Support team on-call
- SLA multiplier: 1.5x (extended response times)
- Escalation: Only for critical/safety issues
- Other tickets: Queued for next business day
---
## 6. Ticketing System Integration
### Webhook Payload Structure
When integrating with ticketing systems, the routing matrix produces:
```json
{
"ticket": {
"urt_code": "P1.02",
"intensity": "I3",
"valence": "V-",
"routing": {
"primary_team": "hr",
"primary_email": "hr@example.com",
"escalation_contact": "hr_director",
"co_owners": ["training"],
"priority": "critical",
"sla_hours": 4,
"auto_escalate": true
},
"tags": ["people", "attitude", "respect", "critical"],
"metadata": {
"resolution_path": "subcode_override",
"pattern_matched": null
}
}
}
```
### Supported Integrations
| System | Integration Method | Notes |
|--------|-------------------|-------|
| Zendesk | Webhook + Triggers | Map teams to groups |
| Jira Service Management | REST API | Map to request types |
| Freshdesk | Webhook | Map teams to agent groups |
| Intercom | API | Map to team inboxes |
| Custom | Generic webhook | Use payload above |
### Field Mapping
| URT Field | Zendesk | Jira | Freshdesk |
|-----------|---------|------|-----------|
| primary_team | Group | Project | Group |
| priority | Priority | Priority | Priority |
| urt_code | Custom Field | Label | Tag |
| sla_hours | SLA Policy | SLA | SLA Policy |
| co_owners | CCs | Watchers | CCs |
---
## 7. Configuration Examples
### Restaurant Configuration
```yaml
# Restaurant-specific overrides
category_overrides:
O1:
team: "kitchen"
escalation: "head_chef"
notes: "Food function issues go to kitchen"
O2:
team: "kitchen"
escalation: "head_chef"
notes: "Food quality is kitchen responsibility"
E1:
team: "front_of_house"
escalation: "foh_manager"
notes: "Physical space is FOH concern"
P1:
team: "front_of_house"
escalation: "foh_manager"
notes: "Server attitude is FOH responsibility"
subcode_overrides:
J1.01: # Wait time
team: "host_station"
escalation: "foh_manager"
J1.05: # Pacing
team: "kitchen"
escalation: "head_chef"
notes: "Pacing often kitchen-driven"
```
### SaaS Company Configuration
```yaml
# SaaS-specific overrides
category_overrides:
O1:
team: "engineering"
escalation: "engineering_lead"
notes: "Product function is eng responsibility"
E2:
team: "product"
escalation: "product_director"
notes: "Digital experience is product"
J3:
team: "devops"
escalation: "sre_lead"
notes: "Reliability is SRE concern"
subcode_overrides:
E2.03: # Performance
team: "sre"
escalation: "sre_lead"
auto_escalate: true
notes: "Performance issues often infra"
J3.03: # System availability
team: "sre"
escalation: "sre_lead"
auto_escalate: true
sla_override_hours: 1
```
### Healthcare Provider Configuration
```yaml
# Healthcare-specific overrides
category_overrides:
O1:
team: "clinical"
escalation: "chief_medical_officer"
notes: "Treatment outcomes are clinical"
P2:
team: "clinical"
escalation: "chief_medical_officer"
notes: "Clinical competence"
E4:
team: "compliance"
escalation: "compliance_director"
auto_escalate: true
notes: "All safety issues are compliance"
subcode_overrides:
A3.03: # Dietary/Medical accommodations
team: "clinical"
escalation: "chief_nursing_officer"
notes: "Medical accommodations are clinical"
E4.02: # Health/Hygiene
team: "infection_control"
escalation: "chief_medical_officer"
auto_escalate: true
sla_override_hours: 1
```
### Retail Store Configuration
```yaml
# Retail-specific overrides
category_overrides:
O1:
team: "merchandising"
escalation: "merchandising_director"
O3:
team: "inventory"
escalation: "inventory_manager"
A1:
team: "store_ops"
escalation: "store_director"
P1:
team: "store_ops"
escalation: "store_manager"
subcode_overrides:
A1.03: # Inventory
team: "inventory"
escalation: "inventory_manager"
J1.01: # Wait time (checkout)
team: "store_ops"
escalation: "store_manager"
```
---
## 8. Multi-Location Override Patterns
### Location-Specific Routing
For businesses with multiple locations, use location prefixes:
```yaml
# Location-specific team definitions
teams:
store_001_ops:
name: "Store 001 Operations"
email: "store001-ops@example.com"
manager: "store_001_manager"
location: "store_001"
store_002_ops:
name: "Store 002 Operations"
email: "store002-ops@example.com"
manager: "store_002_manager"
location: "store_002"
# Location override rules
location_routing:
enabled: true
# Default: route to location team if exists
resolution_order:
1: "location_team" # e.g., store_001_ops
2: "regional_team" # e.g., west_region_ops
3: "central_team" # e.g., operations
# Escalation: location -> regional -> central
escalation_path:
location: "regional"
regional: "central"
central: "executive"
```
### Regional Aggregation
```yaml
regional_routing:
west_region:
locations: ["store_001", "store_002", "store_003"]
regional_team: "west_ops"
regional_director: "west_director"
east_region:
locations: ["store_004", "store_005", "store_006"]
regional_team: "east_ops"
regional_director: "east_director"
# Pattern: systemic issues across multiple locations escalate regionally
multi_location_patterns:
same_issue_multiple_locations:
threshold: 3
window_days: 7
action: "escalate_to_regional"
notes: "Same issue at 3+ locations triggers regional review"
```
### Franchise Model
```yaml
franchise_routing:
# Franchisee handles local issues
franchisee_owned:
- "P1" # Staff attitude
- "P2" # Staff competence
- "E1" # Physical space
- "J1" # Timing
# Franchisor handles brand/system issues
franchisor_owned:
- "O1" # Product function (brand standards)
- "O2" # Product quality (brand standards)
- "R1" # Integrity (brand reputation)
- "V2" # Transparency (policy)
# Shared responsibility
shared:
- "E4" # Safety (both)
- "A3" # Inclusivity (both)
```
---
## 9. Special Routing Rules
### Multi-Code Span Routing
When a span has multiple codes:
```
Primary: P1.02 (Respect) - I3
Secondary: V2.04 (Terms Fairness)
Resolution:
1. Primary team: HR (from P1.02)
2. Co-owner: Legal (from V2.04)
3. Priority: Critical (from I3)
4. Escalation: HR Director + General Counsel notified
```
**Priority Domain Order** (for conflict resolution):
1. E4 (Safety) - always first
2. R1 (Integrity/Ethics)
3. A3 (Discrimination)
4. P (People)
5. V (Value)
6. J (Journey)
7. O (Offering)
8. E (non-safety)
9. A (non-discrimination)
10. R (non-integrity)
### Valence Differentiation
| Valence | Routing Behavior |
|---------|------------------|
| V+ | Route to recognition workflow, lower priority |
| V- | Standard routing, priority by intensity |
| V0 | Log only, no ticket created |
| V+- | Route as V-, note positive elements |
**V+ Special Handling**:
- Positive feedback about staff (P domain, V+) routes to HR for recognition
- Positive feedback about product (O domain, V+) routes to marketing for testimonial potential
- SLA: 48 hours (acknowledgment, not resolution)
### Causal Code Routing
Causal codes indicate root cause and route to strategic teams:
| Layer | Codes | Typical Route | Purpose |
|-------|-------|---------------|---------|
| Conditions | CD-* | Operational teams | Fix immediate cause |
| Management | MG-* | Management | Address management gap |
| Systemic | SY-* | Leadership | Strategic intervention |
**Example**:
```
Review: "Staff seemed exhausted and made mistakes"
Primary: J3.05 (Error Rate)
Causal: CD-S (Staff State) -> MG-P (Planning) -> SY-H (Human Capital)
Routing:
- Ticket: Operations (for immediate errors)
- Root cause ticket: HR (staffing/wellness)
- Strategic flag: Leadership (compensation/retention review)
```
### Cross-Functional Triggers
Certain code combinations automatically involve multiple teams:
| Pattern | Trigger Codes | Teams Involved |
|---------|---------------|----------------|
| Security Breach | E4.03 + R1.04 | Security, Legal, Leadership |
| Discrimination | A3.05 + P1.02 | HR, Legal, DEI |
| Billing Dispute | V1.04 + V2.02 | Billing, Legal, CX |
| Product Failure (Critical) | O1.01 (I3) | Engineering, QA, CX |
| Systemic Issue | SY-* codes | Leadership, Operations |
---
## Appendix: Domain-Team Mapping
### Complete Domain-to-Team Matrix
| Domain | Category | Default Team | Escalation Path |
|--------|----------|--------------|-----------------|
| **O** | O1 Function | product_engineering | eng_lead -> product_dir |
| | O2 Quality | quality_control | qa_mgr -> product_dir |
| | O3 Completeness | fulfillment | fulfillment_mgr -> ops_dir |
| | O4 Fit | product | product_mgr -> product_dir |
| **P** | P1 Attitude | hr_training | hr_dir |
| | P2 Competence | training | training_mgr -> hr_dir |
| | P3 Responsiveness | operations | ops_mgr -> ops_dir |
| | P4 Communication | training | training_mgr -> hr_dir |
| **J** | J1 Timing | operations | ops_mgr -> ops_dir |
| | J2 Ease | process_improvement | ops_dir |
| | J3 Reliability | operations | ops_mgr -> ops_dir |
| | J4 Resolution | customer_service | cx_dir |
| **E** | E1 Physical | facilities | facilities_mgr -> facilities_dir |
| | E2 Digital | it | tech_lead -> cto |
| | E3 Ambiance | facilities | facilities_mgr -> facilities_dir |
| | E4 Safety | safety | safety_officer -> coo |
| **A** | A1 Availability | operations | ops_mgr -> ops_dir |
| | A2 Accessibility | accessibility | accessibility_lead -> compliance_dir |
| | A3 Inclusivity | dei | dei_dir -> hr_dir |
| | A4 Convenience | operations | ops_mgr -> ops_dir |
| **V** | V1 Price | pricing | pricing_mgr -> finance_dir |
| | V2 Transparency | legal | legal_counsel -> general_counsel |
| | V3 Effort | cx | cx_mgr -> cx_dir |
| | V4 Worth | leadership | cx_dir -> cmo -> ceo |
| **R** | R1 Integrity | leadership | legal -> ceo |
| | R2 Dependability | operations | ops_dir -> coo |
| | R3 Recovery | cx | cx_mgr -> cx_dir |
| | R4 Loyalty | marketing | marketing_mgr -> cmo |
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-01-23 | Initial release with URT v5.1 |
---
*This document is part of Track B (Engineering/Implementation) for the Universal Review Taxonomy v5.1.*