From 3eda9bdbfaa1c038e9fa4d7ebee25e5de4effa91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Guti=C3=A9rrez?= <35082514+alezmad@users.noreply.github.com> Date: Sat, 24 Jan 2026 10:51:41 +0000 Subject: [PATCH] Add complete URT v5.1 taxonomy framework (11 artifacts) 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 --- urt-taxonomy/spec/URT-Specification-v5.1.md | 1997 +++++++ .../A1-Annotator-Quickstart.md | 925 ++++ .../track-a-training/A2-QA-Protocol.md | 476 ++ .../A3-Calibration-Test-Set.md | 1925 +++++++ .../A4-Full-Annotation-Manual.md | 4578 +++++++++++++++++ .../track-b-engineering/B1-urt-codes.yaml | 1766 +++++++ .../B2-database-schema.sql | 1126 ++++ .../track-b-engineering/B3-owner-routing.md | 627 +++ .../track-b-engineering/B3-owner-routing.yaml | 692 +++ .../track-b-engineering/B4-api-contract.yaml | 2895 +++++++++++ .../C1-Issue-Lifecycle-Framework.md | 1204 +++++ .../track-c-analytics/C2-KPI-Mapping-Guide.md | 1148 +++++ .../D1-Dashboard-Specification.md | 1905 +++++++ 13 files changed, 21264 insertions(+) create mode 100644 urt-taxonomy/spec/URT-Specification-v5.1.md create mode 100644 urt-taxonomy/track-a-training/A1-Annotator-Quickstart.md create mode 100644 urt-taxonomy/track-a-training/A2-QA-Protocol.md create mode 100644 urt-taxonomy/track-a-training/A3-Calibration-Test-Set.md create mode 100644 urt-taxonomy/track-a-training/A4-Full-Annotation-Manual.md create mode 100644 urt-taxonomy/track-b-engineering/B1-urt-codes.yaml create mode 100644 urt-taxonomy/track-b-engineering/B2-database-schema.sql create mode 100644 urt-taxonomy/track-b-engineering/B3-owner-routing.md create mode 100644 urt-taxonomy/track-b-engineering/B3-owner-routing.yaml create mode 100644 urt-taxonomy/track-b-engineering/B4-api-contract.yaml create mode 100644 urt-taxonomy/track-c-analytics/C1-Issue-Lifecycle-Framework.md create mode 100644 urt-taxonomy/track-c-analytics/C2-KPI-Mapping-Guide.md create mode 100644 urt-taxonomy/track-d-integration/D1-Dashboard-Specification.md diff --git a/urt-taxonomy/spec/URT-Specification-v5.1.md b/urt-taxonomy/spec/URT-Specification-v5.1.md new file mode 100644 index 0000000..6c57a39 --- /dev/null +++ b/urt-taxonomy/spec/URT-Specification-v5.1.md @@ -0,0 +1,1997 @@ +# Universal Review Taxonomy (URT) +## Implementation Specification v5.1 + +A comprehensive framework for classifying customer feedback across all business sectors, scales, and contexts. + +> **Canonical Counts**: URT v5.1 defines **7 experience domains**, **28 categories**, **140 subcodes**, **16 causal codes**, and **7 metadata dimensions with 24 total values**. +> +> **Classification codes = 156** (140 diagnostic subcodes + 16 causal codes). Domains and categories are structural/organizational tiers used for navigation and rollup — they are not counted as classification codes. + +--- + +# Document Information + +| Field | Value | +|-------|-------| +| **Version** | 5.1 | +| **Status** | Frozen — Production Ready | +| **Release Date** | 2026-01-23 | +| **Supersedes** | v5.0 | + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-01 | Initial 15-category flat taxonomy | +| 2.0 | 2026-01 | Added domains, subcodes, coding system | +| 3.0 | 2026-01 | HFACS-style 4-tier causal hierarchy | +| 4.0 | 2026-01 | Synthesis: 7 domains, optional causal depth | +| 4.1 | 2026-01 | Secondary coding, owner routing, disambiguation rules, annotation schema | +| 4.2 | 2026-01 | Causal prohibition rule, V vs R anchor, implementation profiles | +| 5.0 | 2026-01 | Production release: Added Comparative Reference (CR) dimension | +| **5.1** | **2026-01** | **Freeze release: Schema supports all profiles, R3/J4 disambiguation, CR implicit decline rule, criminal metaphor mapping** | + +--- + +# Executive Summary + +The Universal Review Taxonomy (URT) provides a standardized system for analyzing customer feedback that: + +- **Works universally**: Any industry, any size, any geography +- **Handles all valence**: Praise, complaints, and mixed feedback equally well +- **Scales gracefully**: Four implementation profiles from micro-business to enterprise +- **Enables action**: Every classification connects to who should act and how +- **Supports span-level analysis**: Composite reviews decomposed into distinct feedback units +- **Tracks change over time**: Comparative Reference dimension captures improvement/decline signals + +--- + +# Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ UNIVERSAL REVIEW TAXONOMY v5.1 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ PRIMARY STRUCTURE: EXPERIENCE DOMAINS │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ │ +│ │ │ O │ │ P │ │ J │ │ E │ │ A │ │ V │ │ R │ │ │ +│ │ └───┘ └───┘ └───┘ └───┘ └───┘ └───┘ └───┘ │ │ +│ │ Offering People Journey Environ Access Value Relation │ │ +│ │ │ │ +│ │ TIER 1: 7 Domains (Executive View) │ │ +│ │ TIER 2: 28 Categories (Operational View) │ │ +│ │ TIER 3: 140 Subcodes (Diagnostic View) │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ METADATA DIMENSIONS (7 dimensions, 24 values) │ +│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ +│ │Valence │ │Intensity│ │Specific│ │Action- │ │Temporal│ │Evidence│ │ +│ │ + - 0 ±│ │ 1-3 │ │ 1-3 │ │ability │ │ C R H F│ │ S I C │ │ +│ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ +│ ┌────────┐ │ +│ │Compar- │ ← Tracks explicit improvement/decline signals │ +│ │ative │ │ +│ │N B W S │ │ +│ └────────┘ │ +│ │ +│ OPTIONAL: CAUSAL DEPTH (16 codes across 3 layers) │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Conditions (CD-) → Management (MG-) → Systemic (SY-) │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +# Code Statistics Summary + +| Component | Count | +|-----------|-------| +| **Tier 1: Domains** | 7 | +| **Tier 2: Categories** | 28 | +| **Tier 3: Subcodes** | 140 | +| **Causal Codes** | 16 | +| **Metadata Dimensions** | 7 | +| **Metadata Values** | 24 | +| **Total Classification Codes** | 156 | + +> **Count Note**: 156 = 140 diagnostic subcodes + 16 causal codes. Domains and categories are organizational tiers, not counted separately in the total. + +--- + +# Part 1: Experience Domains + +## Domain Summary + +| Code | Domain | Core Question | Default Owner | +|------|--------|---------------|---------------| +| **O** | Offering | Does the core product/service deliver? | Product / Operations | +| **P** | People | How do personnel behave and perform? | HR / Training | +| **J** | Journey | Is the process smooth and timely? | Operations / Process | +| **E** | Environment | Is the space functional and pleasant? | Facilities / IT | +| **A** | Access | Can everyone participate fully? | Compliance / Design | +| **V** | Value | Is the exchange fair and transparent? | Finance / Pricing | +| **R** | Relationship | Is trust built and maintained? | Leadership / CX | + +## Owner Routing Rules + +**Rule 1: Primary code determines default owner.** +The primary code's domain owner is responsible for triage and initial response. + +**Rule 2: Secondary codes add co-owners.** +When secondary codes are assigned, their domain owners are notified as co-owners but do not own the ticket. + +**Rule 3: Override by severity.** +If a secondary code has higher intensity (I3) than the primary code, escalate to both owners jointly. + +**Example:** +> "Support was rude and refund policy is unfair" +- Primary: P1.02 (Respect) → Owner: HR/Training +- Secondary: V2.04 (Terms Fairness) → Co-owner: Finance/Policy +- Routing: HR leads, Finance consulted + +--- + +## O – OFFERING +*The core product, service, or outcome delivered* + +**Core Question**: Does what we provide actually work and meet expectations? + +### Categories + +| Code | Category | Definition | +|------|----------|------------| +| **O1** | Function | Does it do what it's supposed to do? | +| **O2** | Quality | How well is it made or executed? | +| **O3** | Completeness | Is everything included that should be? | +| **O4** | Fit | Does it match the customer's specific needs? | + +### Subcodes + +#### O1: Function +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| O1.01 | **Works/Doesn't Work** | Basic functionality success or failure | "Software runs perfectly" | "Car won't start" | J3.03 (system uptime) | +| O1.02 | **Performance Level** | How well it operates | "Incredibly fast processor" | "Sluggish and laggy" | E2.03 (interface speed) | +| O1.03 | **Durability** | Longevity and resistance to wear | "Still perfect after 5 years" | "Fell apart in a month" | O2.01 (material quality) | +| O1.04 | **Reliability** | Consistency of function over time | "Never fails me" | "Works sometimes, not others" | J3.01 (process consistency) | +| O1.05 | **Outcome Achievement** | Did customer accomplish their goal? | "Passed my exam!" | "Treatment didn't work" | V4.03 (satisfaction) | + +#### O2: Quality +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| O2.01 | **Materials/Inputs** | Quality of components or ingredients | "Real leather, premium feel" | "Cheap plastic parts" | O1.03 (durability) | +| O2.02 | **Craftsmanship** | Skill of construction or execution | "Beautifully sewn seams" | "Sloppy assembly" | P2.02 (staff skill) | +| O2.03 | **Presentation** | Visual and aesthetic quality | "Gorgeous plating" | "Looked thrown together" | E3.05 (space aesthetics) | +| O2.04 | **Attention to Detail** | Finishing touches and refinement | "Every corner perfect" | "Full of typos" | O3.01 (completeness) | +| O2.05 | **Condition at Delivery** | State when received | "Still warm from oven" | "Arrived damaged" | J3.02 (process accuracy) | + +#### O3: Completeness +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| O3.01 | **All Components Present** | Nothing missing from what was promised | "Everything in the box" | "Missing the charger" | O4.01 (spec match) | +| O3.02 | **Feature Availability** | Promised features actually work | "All menu items available" | "Half the features disabled" | A1.03 (inventory) | +| O3.03 | **Scope Delivery** | Full scope of work completed | "Cleaned entire house" | "Left the bathrooms" | J4.04 (resolution quality) | +| O3.04 | **Documentation** | Supporting materials provided | "Great user manual" | "No instructions at all" | J2.01 (process simplicity)* | + +*Documentation Rule: Use O3.04 when docs are a product artifact ("manual was helpful"). Use J2.01 when docs affect onboarding friction ("couldn't figure out how to start").* + +#### O4: Fit +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| O4.01 | **Specification Match** | Matches what was ordered | "Exactly what I ordered" | "Wrong size delivered" | J3.02 (accuracy) | +| O4.02 | **Personalization** | Adapted to individual preferences | "Remembered my usual" | "No way to save prefs" | P3.01 (attentiveness) | +| O4.03 | **Flexibility** | Can be modified or adjusted | "Happy to substitute" | "No modifications allowed" | V2.04 (policy fairness) | +| O4.04 | **Appropriateness** | Right solution for the need | "Perfect recommendation" | "Sold me wrong thing" | P2.01 (knowledge) | + +--- + +## P – PEOPLE +*Human interactions and personnel behavior* + +**Core Question**: How do the people we interact with treat us and perform their roles? + +### Categories + +| Code | Category | Definition | +|------|----------|------------| +| **P1** | Attitude | Disposition, manner, and emotional tone | +| **P2** | Competence | Knowledge, skill, and professional capability | +| **P3** | Responsiveness | Attentiveness, initiative, and follow-through | +| **P4** | Communication | Quality of information exchange | + +### Subcodes + +#### P1: Attitude +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| P1.01 | **Warmth/Friendliness** | Approachability and pleasantness | "So welcoming and kind" | "Cold and unfriendly" | R4.03 (relationship building) | +| P1.02 | **Respect** | Treating customer with dignity | "Made me feel valued" | "Talked down to me" | A3.05 (discrimination) | +| P1.03 | **Empathy** | Understanding customer's situation | "Really got my frustration" | "Couldn't care less" | P4.02 (listening) | +| P1.04 | **Patience** | Tolerance and calm under pressure | "Never rushed me" | "Visibly annoyed" | J1.05 (pacing) | +| P1.05 | **Enthusiasm** | Energy and genuine interest | "Passionate about helping" | "Going through motions" | P2.05 (experience) | + +#### P2: Competence +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| P2.01 | **Knowledge** | Understanding of products/services | "Knew every detail" | "Couldn't answer basics" | O3.04 (documentation) | +| P2.02 | **Technical Skill** | Ability to perform required tasks | "Masterful technique" | "Clearly undertrained" | O2.02 (craftsmanship) | +| P2.03 | **Problem-Solving** | Ability to address issues | "Found creative solution" | "Just said 'can't'" | J4.02 (resolution process) | +| P2.04 | **Professionalism** | Appropriate conduct and standards | "Very professional" | "Inappropriate jokes" | P1.02 (respect) | +| P2.05 | **Experience** | Depth of expertise | "Clearly an expert" | "Like talking to beginner" | R2.01 (track record) | + +#### P3: Responsiveness +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| P3.01 | **Attentiveness** | Awareness of customer needs | "Always checking in" | "Had to flag them down" | O4.02 (personalization) | +| P3.02 | **Initiative** | Proactive assistance | "Offered help unprompted" | "Did bare minimum" | P4.03 (proactive updates) | +| P3.03 | **Availability** | Present when needed | "Easy to find someone" | "Impossible to reach" | A1.04 (staffing levels) | +| P3.04 | **Follow-Through** | Completing promised actions | "Did exactly as promised" | "Never followed up" | R1.02 (promise keeping)* | +| P3.05 | **Urgency** | Appropriate prioritization | "Treated as priority" | "No sense of urgency" | J1.03 (response time) | + +*Follow-Through vs Promise-Keeping: Use P3.04 for a specific interaction ("said they'd call back, didn't"). Use R1.02 when framed as trust/pattern ("they never keep their word").* + +#### P4: Communication +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| P4.01 | **Clarity** | Understandable information | "Explained clearly" | "Confusing jargon" | O3.04 (documentation) | +| P4.02 | **Listening** | Hearing and understanding customer | "Really heard me" | "Kept interrupting" | P1.03 (empathy) | +| P4.03 | **Proactive Updates** | Keeping customer informed | "Regular status updates" | "Radio silence for weeks" | J4.01 (acknowledgment) | +| P4.04 | **Accuracy** | Correctness of information | "Everything accurate" | "Given wrong info" | V2.05 (honest representation) | +| P4.05 | **Tone** | Appropriate communication style | "Professional but warm" | "Condescending tone" | P1.02 (respect) | + +--- + +## J – JOURNEY +*The process, timing, and operational flow* + +**Core Question**: Is the experience smooth, timely, and friction-free? + +### Categories + +| Code | Category | Definition | +|------|----------|------------| +| **J1** | Timing | Speed, punctuality, and time management | +| **J2** | Ease | Effort required and friction encountered | +| **J3** | Reliability | Consistency and predictability of process | +| **J4** | Resolution | How problems are handled when they arise | + +### Subcodes + +#### J1: Timing +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| J1.01 | **Wait Time** | Time spent waiting | "Seated immediately" | "45 min past appointment" | A1.02 (booking access) | +| J1.02 | **Service Speed** | Time for delivery/completion | "Next day delivery" | "Took three weeks" | J4.03 (resolution speed) | +| J1.03 | **Response Time** | Time to address inquiries | "Replied in minutes" | "Days for a response" | P3.05 (urgency) | +| J1.04 | **Punctuality** | Meeting scheduled times | "Always on time" | "Two hours late" | R2.02 (consistency) | +| J1.05 | **Pacing** | Appropriate speed (not rushed/dragged) | "Perfect timing" | "Rushed us out" | P1.04 (patience) | + +#### J2: Ease +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| J2.01 | **Simplicity** | Straightforward processes | "So easy to do" | "Needlessly complicated" | E2.04 (interface navigation)* | +| J2.02 | **Navigation** | Finding what's needed | "Found it instantly" | "Couldn't find anything" | E1.03 (physical layout) | +| J2.03 | **Paperwork/Forms** | Documentation burden | "Minimal forms" | "Endless paperwork" | V3.02 (mental effort) | +| J2.04 | **Handoffs** | Transitions between steps/people | "Seamless transfer" | "Explained to 5 people" | P4.03 (proactive updates) | +| J2.05 | **Self-Service** | Customer autonomy options | "Great online portal" | "Forced to call" | E2.02 (digital functionality) | + +*J2 vs E2 Rule: J2 = effort/friction in the process itself ("too many steps"). E2 = qualities of the digital interface ("buttons don't work", "ugly design").* + +#### J3: Reliability +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| J3.01 | **Consistency** | Same result each time | "Always reliable" | "Hit or miss quality" | O1.04 (product reliability)* | +| J3.02 | **Accuracy** | Correct execution of requests | "Order exactly right" | "Wrong items delivered" | O4.01 (spec match) | +| J3.03 | **Availability** | System/service uptime | "Never goes down" | "Constant outages" | A1.03 (inventory) | +| J3.04 | **Predictability** | Expectations matched | "No surprises" | "Never know what to expect" | V2.01 (pricing clarity) | +| J3.05 | **Error Rate** | Frequency of mistakes | "Rarely makes mistakes" | "Something wrong every time" | R2.02 (dependability) | + +*J3.01 vs O1.04: J3.01 = process delivers same result each time. O1.04 = the product itself works consistently. "Pizza is always good" = J3.01. "Phone always connects" = O1.04.* + +#### J4: Resolution +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| J4.01 | **Problem Acknowledgment** | Recognition of issues | "Immediately recognized" | "Denied any problem" | R3.01 (admitting failures) | +| J4.02 | **Resolution Process** | How problems are handled | "Clear escalation path" | "Transferred in circles" | P2.03 (problem-solving) | +| J4.03 | **Resolution Speed** | Time to fix | "Fixed same day" | "Took weeks to resolve" | J1.02 (service speed) | +| J4.04 | **Resolution Quality** | Adequacy of solution | "Completely fixed" | "Band-aid fix" | R3.03 (compensation) | +| J4.05 | **Prevention** | Efforts to avoid recurrence | "Changed their process" | "Same issue happened again" | R3.04 (improvement) | + +### Billing/Returns/Refunds Guidance + +| Feedback Type | Primary Code | Secondary Code | +|---------------|--------------|----------------| +| Returns process was easy/hard | J4.02 (Resolution Process) | — | +| Refund took too long | J4.03 (Resolution Speed) | — | +| Refund policy is unfair | V2.04 (Terms Fairness) | — | +| They refused to refund (trust framing) | R3.03 (Compensation) | V2.04 | +| Wrong amount refunded | J3.02 (Accuracy) | V1.04 (Hidden Costs) | + +--- + +## E – ENVIRONMENT +*Physical, digital, and ambient context* + +**Core Question**: Is the space where the experience occurs functional, safe, and pleasant? + +### Categories + +| Code | Category | Definition | +|------|----------|------------| +| **E1** | Physical Space | Tangible environment attributes | +| **E2** | Digital Space | Online and application interface | +| **E3** | Ambiance | Intangible environmental qualities | +| **E4** | Safety | Security and wellbeing factors | + +### Subcodes + +#### E1: Physical Space +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| E1.01 | **Cleanliness** | Hygiene and tidiness | "Spotless facilities" | "Filthy bathrooms" | E4.02 (health/hygiene) | +| E1.02 | **Maintenance** | Condition and upkeep | "Everything works" | "Broken equipment" | O1.01 (product function) | +| E1.03 | **Layout/Design** | Functional arrangement | "Easy to navigate" | "Confusing layout" | J2.02 (finding things) | +| E1.04 | **Equipment** | Tools and amenities | "Modern machines" | "Outdated everything" | O1.02 (product performance) | +| E1.05 | **Signage** | Navigation aids | "Clear directions" | "No signs anywhere" | A4.01 (location) | + +#### E2: Digital Space +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| E2.01 | **Interface Design** | Visual and interaction quality | "Beautiful app" | "Cluttered mess" | O2.03 (product presentation) | +| E2.02 | **Functionality** | Features working correctly | "Everything works" | "Buttons broken" | O1.01 (product function) | +| E2.03 | **Performance** | Speed and responsiveness | "Lightning fast" | "Painfully slow" | O1.02 (product performance)* | +| E2.04 | **Navigation** | Ease of finding things | "Intuitive menus" | "Buried in submenus" | J2.01 (process simplicity) | +| E2.05 | **Mobile Experience** | Smartphone optimization | "Great on phone" | "Unusable on mobile" | A2.05 (digital accessibility) | + +*E2.03 vs O1.02: E2.03 = the interface/app is slow. O1.02 = the core product performs poorly ("car accelerates slowly").* + +#### E3: Ambiance +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| E3.01 | **Atmosphere/Vibe** | Overall mood of space | "Calm and relaxing" | "Stressful chaos" | P1 (staff attitude) | +| E3.02 | **Noise Level** | Sound environment | "Pleasantly quiet" | "Deafening noise" | E4.04 (comfort) | +| E3.03 | **Temperature/Climate** | Thermal comfort | "Perfect temperature" | "Freezing cold" | E4.04 (comfort) | +| E3.04 | **Crowding** | Density and personal space | "Plenty of room" | "Packed like sardines" | A1.03 (capacity) | +| E3.05 | **Aesthetics** | Beauty and visual appeal | "Beautiful décor" | "Depressing space" | O2.03 (product presentation) | + +#### E4: Safety +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| E4.01 | **Physical Safety** | Protection from harm | "Felt completely safe" | "Dangerous conditions" | A2.01 (physical accessibility) | +| E4.02 | **Health/Hygiene** | Sanitation standards | "Strict protocols" | "Questionable handling" | E1.01 (cleanliness) | +| E4.03 | **Security** | Protection of person/property | "Secure facility" | "Things were stolen" | R1.03 (transparency)* | +| E4.04 | **Comfort** | Physical ease and wellbeing | "Comfortable seating" | "Torture chairs" | E3 (ambiance) | +| E4.05 | **Emergency Readiness** | Preparedness for incidents | "Clear exits marked" | "No safety measures" | E1.05 (signage) | + +*Data Privacy/Security Rule:* +| Feedback Type | Primary Code | Secondary Code | +|---------------|--------------|----------------| +| Security incident occurred | E4.03 (Security) | — | +| "I don't trust them with my data" | R1.03 (Transparency) or R1.04 (Ethics) | E4.03 | +| Data breach notification | E4.03 (Security) | R1.03 (Transparency) | +| Privacy policy concerns | V2.04 (Terms Fairness) | R1.04 (Ethics) | + +--- + +## A – ACCESS +*Availability, accessibility, and inclusivity* + +**Core Question**: Can everyone who wants to participate do so fully and fairly? + +### Categories + +| Code | Category | Definition | +|------|----------|------------| +| **A1** | Availability | Can you get it when you need it? | +| **A2** | Accessibility | Can everyone use it regardless of ability? | +| **A3** | Inclusivity | Does it work for diverse backgrounds? | +| **A4** | Convenience | Is it easy to reach and engage with? | + +### A Domain Disambiguation + +The Access domain covers three distinct concerns: + +| Category | Focus | Key Question | Example Feedback | +|----------|-------|--------------|------------------| +| **A1/A4** | Operational convenience | Can I get there, book it, reach it? | "Hard to park," "Never in stock" | +| **A2** | Disability/ability barriers | Can people with disabilities use it? | "No wheelchair ramp," "Screen reader fails" | +| **A3** | Cultural/social inclusion | Does it work for diverse backgrounds? | "English only," "Felt discriminated against" | + +### A vs J vs E2 Rule of Thumb + +| Domain | Focus | Example | +|--------|-------|---------| +| **J2** | Effort/friction in process | "Too many steps to check out" | +| **E2** | Interface qualities (UX/UI) | "App is ugly and confusing" | +| **A2** | Ability-based barriers | "Doesn't work with screen reader" | +| **A3** | Culture/identity barriers | "No language support" | + +### Subcodes + +#### A1: Availability +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| A1.01 | **Operating Hours** | When service is accessible | "Open 24/7" | "Banker's hours only" | P3.03 (staff availability) | +| A1.02 | **Booking Access** | Ability to schedule | "Easy online booking" | "3 weeks for appointment" | J1.01 (wait time) | +| A1.03 | **Inventory/Capacity** | Product/service available | "Always in stock" | "Perpetually sold out" | E3.04 (crowding) | +| A1.04 | **Staffing Levels** | Personnel available | "Plenty of staff" | "Severely understaffed" | P3.03 (availability) | +| A1.05 | **Geographic Reach** | Service area coverage | "Serves my area" | "Not available here" | A4.01 (location) | + +#### A2: Accessibility (Ability-Based) +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| A2.01 | **Physical Accessibility** | Mobility accommodations | "Wheelchair accessible" | "No ramps or elevators" | E4.01 (physical safety) | +| A2.02 | **Visual Accessibility** | Sight accommodations | "Great alt text" | "Can't use with screen reader" | E2.01 (interface design) | +| A2.03 | **Hearing Accessibility** | Audio accommodations | "Captions available" | "No transcripts" | E2.02 (functionality) | +| A2.04 | **Cognitive Accessibility** | Mental/learning accommodations | "Clear simple language" | "Unnecessarily complex" | J2.01 (simplicity) | +| A2.05 | **Digital Accessibility** | Assistive technology support | "Works with JAWS" | "Inaccessible app" | E2.05 (mobile experience) | + +#### A3: Inclusivity (Culture/Identity-Based) +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| A3.01 | **Language Support** | Multiple language options | "Staff spoke my language" | "English only, no help" | P2.01 (knowledge) | +| A3.02 | **Cultural Sensitivity** | Respect for backgrounds | "Understood our customs" | "Insensitive comments" | P1.02 (respect) | +| A3.03 | **Dietary/Medical** | Restriction accommodations | "Handled allergies well" | "No options for me" | O4.03 (flexibility) | +| A3.04 | **Family Friendly** | Children/family accommodation | "Great for kids" | "Not child-friendly" | E3.01 (atmosphere) | +| A3.05 | **Equal Treatment** | Non-discrimination | "Treated same as everyone" | "Felt discriminated against" | P1.02 (respect)* | + +*A3.05 vs P1.02: Use A3.05 when feedback suggests identity-based discrimination ("treated differently because of X"). Use P1.02 for general disrespect without identity framing.* + +#### A4: Convenience +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| A4.01 | **Location** | Physical accessibility | "Convenient location" | "Middle of nowhere" | A1.05 (geographic reach) | +| A4.02 | **Parking** | Vehicle accommodation | "Easy free parking" | "Parking nightmare" | E4.03 (security) | +| A4.03 | **Transit Access** | Public transport options | "Right by subway" | "No transit options" | A4.01 (location) | +| A4.04 | **Payment Options** | How you can pay | "Takes all payments" | "Cash only" | V1.05 (payment flexibility) | +| A4.05 | **Contact Options** | Ways to reach business | "Chat, phone, email" | "Phone only, long hold" | J2.05 (self-service) | + +--- + +## V – VALUE +*Cost, pricing, and worth of the exchange* + +**Core Question**: Is what I'm giving up fair for what I'm getting? + +### Categories + +| Code | Category | Definition | +|------|----------|------------| +| **V1** | Price | The monetary cost | +| **V2** | Transparency | Clarity and honesty about costs | +| **V3** | Effort | Non-monetary costs (time, hassle) | +| **V4** | Worth | Overall value assessment | + +### Subcodes + +#### V1: Price +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| V1.01 | **Absolute Price** | The actual cost | "Very affordable" | "Outrageously expensive" | V4.02 (quality-price ratio) | +| V1.02 | **Price vs. Expectation** | Compared to anticipated | "Cheaper than expected" | "Sticker shock" | V2.01 (pricing clarity) | +| V1.03 | **Price vs. Market** | Compared to competitors | "Best prices around" | "Overpriced vs. others" | V4.01 (overall value) | +| V1.04 | **Hidden Costs** | Unexpected charges | "No hidden fees" | "Surprise $50 charge" | V2.02 (fee disclosure) | +| V1.05 | **Payment Flexibility** | Terms and options | "Great financing" | "All upfront required" | A4.04 (payment options) | + +#### V2: Transparency +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| V2.01 | **Pricing Clarity** | Understanding what costs what | "Clear price list" | "Impossible to understand" | J3.04 (predictability) | +| V2.02 | **Fee Disclosure** | Upfront about all charges | "Full disclosure" | "Hidden in fine print" | V1.04 (hidden costs) | +| V2.03 | **Advertising Accuracy** | Marketing matches reality | "As advertised" | "Bait and switch" | R1.01 (truthfulness) | +| V2.04 | **Terms Fairness** | Contract/policy reasonableness | "Fair cancellation policy" | "Predatory contract" | R1.05 (fair dealing) | +| V2.05 | **Honest Representation** | Truthful claims | "Accurate description" | "Totally misleading" | R1.01 (truthfulness)* | + +*V2 vs R1: Use V2 when feedback is about pricing/terms/advertising specifically. Use R1 when framed as trust/integrity/organizational character.* + +#### V3: Effort +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| V3.01 | **Time Investment** | Hours required | "Quick 10 minutes" | "Wasted my whole day" | J1 (timing) | +| V3.02 | **Mental Effort** | Cognitive load | "Effortless experience" | "Exhausting to figure out" | J2.01 (simplicity) | +| V3.03 | **Physical Effort** | Bodily exertion | "Brought to my door" | "Had to lug it upstairs" | A4 (convenience) | +| V3.04 | **Hassle Factor** | Cumulative frustration | "Smooth experience" | "Death by thousand cuts" | J2 (ease) | +| V3.05 | **Opportunity Cost** | What else could be done | "Worth the trip" | "Not worth the drive" | V4.01 (overall value) | + +#### V4: Worth +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| V4.01 | **Overall Value** | Total assessment | "Excellent value" | "Total rip-off" | V1.01 (absolute price) | +| V4.02 | **Quality-Price Ratio** | What you get for what you pay | "Great for the price" | "Pay more, get less" | O2 (quality) | +| V4.03 | **Satisfaction** | Contentment with exchange | "Very satisfied" | "Deeply regret it" | O1.05 (outcome achievement) | +| V4.04 | **Recommendation** | Would suggest to others | "Highly recommend" | "Would warn everyone" | R4.03 (relationship) | +| V4.05 | **Return Intent** | Would come back | "Definitely returning" | "Never again" | R4 (loyalty) | + +--- + +## R – RELATIONSHIP +*Trust, reliability, and ongoing connection* + +**Core Question**: Can I trust this business and do they value our relationship? + +### R Domain Disambiguation + +Use R when feedback is about: +- **Trust/commitment over time** ("They always/never...") +- **Organizational intent** ("They don't care about customers") +- **Pattern of behavior** ("This is the third time...") +- **Character judgment** ("Shady company," "Stand behind their product") +- **Moral assessment of the business** ("They're crooks," "Ethical company") + +Use P/J/V when feedback is about: +- **A specific interaction** ("The cashier was rude today") +- **A specific process** ("This refund took too long") +- **A specific price/term** ("This fee is unfair") + +### V vs R "Scam/Rip-off" Rule + +| Feedback | Primary Code | Rationale | +|----------|--------------|-----------| +| "This is a rip-off" | **V4.01** | Complaint is about the exchange (poor value) | +| "This company is a scam" | **R1.04** | Moral judgment about intent (they're dishonest) | +| "They're crooks who ripped me off" | **R1.04** | Primary is character; V4.01 secondary | +| "Overpriced garbage" | **V4.02** | About quality-price ratio, not character | +| "They deliberately mislead people" | **R1.01** | About organizational truthfulness | + +**Rule of thumb:** +- If the complaint is about **the exchange itself** (what I got vs. what I paid) → **V** +- If it's a **moral judgment about intent** (they meant to deceive/harm) → **R** + +**Metaphorical criminal language mapping:** +- "scam," "fraud," "crooks" → character judgment → **R1.04** +- "rip-off," "robbery," "highway robbery" → exchange complaint → **V4.01** + +### Categories + +| Code | Category | Definition | +|------|----------|------------| +| **R1** | Integrity | Honesty and ethical behavior | +| **R2** | Dependability | Consistency over time | +| **R3** | Recovery | Response to failures | +| **R4** | Loyalty | Investment in ongoing relationship | + +### Subcodes + +#### R1: Integrity +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| R1.01 | **Truthfulness** | Accurate representations | "Everything as stated" | "They flat out lied" | V2.03 (advertising accuracy) | +| R1.02 | **Promise Keeping** | Honoring commitments | "Always deliver on word" | "Never keep promises" | P3.04 (follow-through)* | +| R1.03 | **Transparency** | Openness about practices | "Full disclosure always" | "Hidden agendas" | V2.02 (fee disclosure) | +| R1.04 | **Ethics** | Moral business conduct | "Ethical company" | "Shady business practices" | V2.04 (terms fairness) | +| R1.05 | **Fair Dealing** | Equitable treatment | "Always treated fairly" | "Felt taken advantage of" | A3.05 (equal treatment) | + +*R1.02 vs P3.04: Use R1.02 when framed as trust/pattern ("They never keep their word"). Use P3.04 for specific interaction ("Said they'd call back, didn't").* + +#### R2: Dependability +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| R2.01 | **Track Record** | Historical performance | "Never let me down" | "History of problems" | P2.05 (experience) | +| R2.02 | **Consistency** | Same experience over time | "Always great" | "Varies wildly" | J3.01 (process consistency) | +| R2.03 | **Stability** | Organizational continuity | "Stable company" | "Constant changes" | J3.03 (uptime) | +| R2.04 | **Trustworthiness** | Warranting confidence | "Can count on them" | "Don't trust them" | R1 (integrity) | +| R2.05 | **Guarantee Honor** | Standing behind product | "Honored warranty" | "Worthless guarantee" | J4.04 (resolution quality) | + +#### R3: Recovery + +**R3 vs J4 Disambiguation**: If the span is about *what they did* to fix the problem, use J4. If it is about *how they took responsibility* (acknowledgment, apology, ownership), use R3. + +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| R3.01 | **Acknowledgment** | Admitting failures | "Owned their mistake" | "Denied any wrongdoing" | J4.01 (problem acknowledgment) | +| R3.02 | **Apology** | Expression of regret | "Sincere apology" | "Non-apology apology" | P1.03 (empathy) | +| R3.03 | **Compensation** | Making amends | "More than made up for it" | "Offered nothing" | J4.04 (resolution quality) | +| R3.04 | **Improvement** | Actions to prevent recurrence | "Changed their process" | "Same thing happens" | J4.05 (prevention) | +| R3.05 | **Ownership** | Taking responsibility | "Took full responsibility" | "Blamed me instead" | P2.03 (problem-solving) | + +#### R4: Loyalty +| Code | Name | Definition | + Example | − Example | Don't Confuse With | +|------|------|------------|-----------|-----------|-------------------| +| R4.01 | **Recognition** | Acknowledging repeat customers | "They remember me" | "Stranger every time" | O4.02 (personalization) | +| R4.02 | **Rewards** | Loyalty benefits | "Great perks" | "Points are worthless" | V1 (price) | +| R4.03 | **Relationship Building** | Investment in connection | "Personal relationship" | "Purely transactional" | P1.01 (friendliness) | +| R4.04 | **Communication** | Ongoing contact quality | "Helpful newsletters" | "Nothing but spam" | P4.03 (proactive updates) | +| R4.05 | **Community** | Belonging and connection | "Feel part of something" | "No sense of community" | E3.01 (atmosphere) | + +--- + +# Part 2: Metadata Dimensions + +Every span classification includes orthogonal metadata. There are **7 dimensions with 24 total values**. + +## 2.1 Valence (V) + +| Code | Label | Definition | Markers | +|------|-------|------------|---------| +| **V+** | Positive | Praise, satisfaction | "great," "loved," "excellent" | +| **V-** | Negative | Complaint, dissatisfaction | "terrible," "hated," "worst" | +| **V0** | Neutral | Observation without judgment | "they have," "it was," factual | +| **V±** | Mixed | Both positive and negative in same span | "good but," "despite," "however" | + +### V± Usage Rule +**Prefer splitting over V± unless truly inseparable.** + +| Feedback | Action | +|----------|--------| +| "Great product, terrible onboarding" | Split: two different targets | +| "Good but overpriced" | Keep as one span with V± in Value | +| "Nice staff despite the chaos" | Split if chaos is separate feedback, else V± | + +**Test**: If the positive and negative parts have different domain targets, split them. + +--- + +## 2.2 Intensity (I) + +| Code | Label | Definition | Linguistic Markers | +|------|-------|------------|-------------------| +| **I1** | Mild | Slight preference/concern | "a bit," "somewhat," "could be better," "slightly" | +| **I2** | Moderate | Clear but not extreme | Standard adjectives without intensifiers | +| **I3** | Strong | Emphatic or intense | "extremely," "absolutely," "worst ever," CAPS, !!!, profanity | + +--- + +## 2.3 Specificity (S) + +| Code | Label | Definition | Example | +|------|-------|------------|---------| +| **S1** | Vague | General impression only | "Service was bad" | +| **S2** | Moderate | Some details or context | "Service was slow at dinner" | +| **S3** | Specific | Concrete details, names, times, amounts | "Waiter John took 40 mins for appetizers at 7pm Saturday" | + +--- + +## 2.4 Actionability (A) + +| Code | Label | Definition | Example | +|------|-------|------------|---------| +| **A1** | Low | Feeling with no clear action path | "I just didn't like it" | +| **A2** | Medium | Suggests improvement area | "Food could be warmer" | +| **A3** | High | Specific implementable feedback | "West bathroom stall lock is broken" | + +### Specificity vs. Actionability: Key Distinctions + +These are correlated but not identical: + +| Example | Specificity | Actionability | Why Different | +|---------|-------------|---------------|---------------| +| "John was rude" | S3 (named person) | A2 (action unclear: coach? fire? investigate?) | Specific but action not obvious | +| "Website is confusing" | S1 (vague) | A3 (can trigger UX audit) | Vague but actionable category | +| "Bathroom stall lock broken" | S3 | A3 | High both—ideal feedback | +| "I didn't enjoy it" | S1 | A1 | Low both—least useful | +| "Food was cold" | S2 | A2 | Moderate both—typical | + +--- + +## 2.5 Temporal Reference (T) + +| Code | Label | Definition | +|------|-------|------------| +| **TC** | Current | This specific visit/experience | +| **TR** | Recent | Recent pattern of experiences | +| **TH** | Historical | Long-standing pattern | +| **TF** | Future | Expectations or predictions | + +--- + +## 2.6 Evidence Type (E) + +| Code | Label | Definition | Constraint | +|------|-------|------------|------------| +| **ES** | Stated | Explicitly said by customer | Text directly says it | +| **EI** | Inferred | Logically entailed by text | Must be directly deducible, not speculative | +| **EC** | Contextual | Requires surrounding text | Span uses "that," "they," "it" referencing earlier content | + +### Evidence Type Rules + +**EI Constraint**: Use only when text logically entails the inference. +- ✓ "Took 3 weeks to reply" → EI for J1.03 (response time) +- ✓ "Fifth time calling about this" → EI for J3.05 (error rate) +- ✗ "Seemed tired" → Cannot infer CD-S.01 (fatigue) without more evidence + +**EC Constraint**: Use when span depends on earlier referents. +- "The same issue happened again" (depends on knowing what issue) +- "They did the same thing" (requires prior context) +- "That was disappointing" (references unstated subject) + +--- + +## 2.7 Comparative Reference (CR) + +This dimension captures when customers explicitly compare their current experience to a previous state. It enables tracking whether issues are improving, worsening, or persisting over time. + +| Code | Label | Definition | Trigger Words | +|------|-------|------------|---------------| +| **CR-N** | None | No comparison to previous state | (default) | +| **CR-B** | Better | Explicit improvement vs. before | "better now," "improved," "finally fixed," "much faster than last time" | +| **CR-W** | Worse | Explicit decline vs. before | "worse now," "used to be good," "has really gone downhill," "not like it used to be" | +| **CR-S** | Same | Explicitly unchanged | "still," "as always," "same as before," "nothing has changed" | + +### CR Assignment Rules + +**Rule 1: Only assign CR-B/W/S when the customer explicitly compares to their own past experience.** +Do not infer comparison from context or assume temporal patterns. + +**Rule 2: CR-N is the default.** +~90% of spans will be CR-N. Only change when comparison is explicit. + +**Rule 3: Self-comparison only.** +CR tracks comparison to the customer's own prior experience, not to competitors (that's noted in the primary code or as a secondary dimension). + +**Rule 4: Implicit decline/improvement counts.** +Past-positive + present-negative implies CR-W. Past-negative + present-positive implies CR-B. Examples: +- "used to be good" → CR-W +- "was great before" → CR-W +- "no longer what it was" → CR-W +- "they've really turned things around" → CR-B + +### CR Examples + +| Span | CR Code | Rationale | +|------|---------|-----------| +| "Service is slow" | **CR-N** | No comparison made | +| "Service is still slow" | **CR-S** | "Still" = explicitly unchanged | +| "Service is much better now" | **CR-B** | Explicit improvement | +| "Service has really gone downhill" | **CR-W** | Explicit decline | +| "Service is better than [Competitor]" | **CR-N** | Competitor comparison, not self-comparison | +| "They finally fixed the app!" | **CR-B** | Explicit resolution of prior issue | +| "Same problems as my last visit" | **CR-S** | Explicitly unchanged | +| "This used to be my favorite restaurant" | **CR-W** | Implies decline | +| "Great as always" | **CR-S** | Explicitly consistent (positive) | + +### CR + Valence Combinations + +| CR | V+ | V- | Interpretation | +|----|----|----|----------------| +| CR-B | Improvement praise | Recovery acknowledgment | Issue resolved or improving | +| CR-W | — | Decline complaint | Quality deteriorating | +| CR-S | Consistent praise | Persistent complaint | Stable state (good or bad) | +| CR-N | General praise | General complaint | No temporal signal | + +### Why CR Matters + +CR enables downstream analytics to: +1. **Confirm issue resolution** without requiring explicit positive reviews +2. **Detect declining quality** before it becomes widespread +3. **Identify persistent issues** that haven't been fixed +4. **Track improvement velocity** over time + +--- + +## Metadata Summary Table + +| Dimension | Code | Values | Default | Required In | +|-----------|------|--------|---------|-------------| +| **Valence** | V | V+, V-, V0, V± | — | All profiles | +| **Intensity** | I | I1, I2, I3 | — | All profiles | +| **Specificity** | S | S1, S2, S3 | — | Standard+ | +| **Actionability** | A | A1, A2, A3 | — | Standard+ | +| **Temporal** | T | TC, TR, TH, TF | TC | Core+ | +| **Evidence** | E | ES, EI, EC | ES | Standard+ | +| **Comparative** | CR | CR-N, CR-B, CR-W, CR-S | CR-N | Standard+ | + +**Total: 7 dimensions, 24 values** + +--- + +# Part 3: Multi-Coding Rules + +## Primary and Secondary Codes + +Each span receives: +- **One primary code** (required) — the main classification +- **Up to two secondary codes** (optional) — additional relevant dimensions + +### Primary Code Selection + +The primary code captures *what the customer is primarily frustrated or happy about*. + +**Selection test**: "If I could only tell the business one thing about this feedback, what would it be?" + +### Secondary Code Rules + +1. **Max 2 secondary codes** — prevents over-tagging +2. **Must be genuinely distinct** — not just a related code in same category +3. **Different domain preferred** — if both codes would be in same category, reconsider if secondary is needed +4. **Higher intensity escalates** — if secondary code is I3 and primary is I1/I2, consider swapping + +### Multi-Code Examples + +| Span | Primary | Secondary | Rationale | +|------|---------|-----------|-----------| +| "Rude staff and unfair refund policy" | P1.02 (Respect) | V2.04 (Terms) | Two distinct complaints | +| "The broken machine made me wait an hour" | J1.01 (Wait Time) | E1.02 (Maintenance) | Wait is impact, machine is cause | +| "Great food but too expensive" | V4.02 (Quality-Price) | — | Single judgment, no secondary needed | +| "Support was slow and kept transferring me" | J1.03 (Response Time) | J2.04 (Handoffs) | Two distinct process issues | + +--- + +# Part 4: Span Extraction Rules + +## Span Boundary Rules + +1. **Split at contrasting conjunctions**: but, however, although, despite, yet +2. **Split when subject changes**: location → service → food +3. **Split when valence changes**: positive → negative +4. **Split when domain changes**: different aspect of experience +5. **Keep together for cause-effect**: "X happened because Y" stays together if about same issue + +### Max Spans Guidance + +- **Typical sentence**: 1-2 spans +- **Complex sentence**: 2-3 spans +- **If tempted to create 4+ spans from one sentence**: Re-read; you may be over-splitting + +### Cause-Effect Span Rule + +When a span describes both an impact and its cause, **keep it as one span**: +- Primary code = the **impact** (what the customer experienced) +- Secondary code = the **cause** (what created the impact) + +**Example:** +> "Support was slow because the system kept crashing" + +| Approach | Primary | Secondary | Rationale | +|----------|---------|-----------|-----------| +| ✓ Correct | J1.03 (Response Time) | J3.03 (System Availability) | Impact + cause, single span | +| ✗ Incorrect | Split into two spans | — | Over-splitting same issue | + +**When to split instead:** +- If cause and effect are in different sentences +- If the customer emphasizes both independently +- If they're about genuinely different issues + +**More examples:** +| Span | Treatment | Primary | Secondary | +|------|-----------|---------|-----------| +| "Long wait because understaffed" | Single span | J1.01 (Wait Time) | A1.04 (Staffing) | +| "Food cold, had to send it back" | Single span | O2.05 (Condition) | J4.02 (Resolution) | +| "App crashed so I lost my data" | Single span | E2.02 (Functionality) | E4.03 (Security) | +| "Rude waiter. Also the food was cold." | Two spans | P1.02 / O2.05 | Different issues | + +--- + +# Part 5: Causal Depth (Optional) + +For root cause analysis, any classification can be extended with causal layers. + +## Causal Layer Structure + +``` +LAYER 4: SYSTEMIC (Why does the organization create these conditions?) +┌─────────────────────────────────────────────────────────────────┐ +│ SY-R: Resource Decisions (budget, investment, staffing levels) │ +│ SY-P: Policy/Procedure (rules, requirements, bureaucracy) │ +│ SY-C: Culture (values, priorities, norms) │ +│ SY-S: Standards (quality thresholds, metrics, expectations) │ +│ SY-H: Human Capital (compensation, hiring, retention) │ +│ SY-X: External (market, regulatory, competitive pressure) │ +└─────────────────────────────────────────────────────────────────┘ + ↑ constrains +LAYER 3: MANAGEMENT (What decisions allowed enabling conditions?) +┌─────────────────────────────────────────────────────────────────┐ +│ MG-P: Planning (staffing plans, scheduling, forecasting) │ +│ MG-T: Training (preparation, development, competency) │ +│ MG-O: Oversight (supervision, monitoring, correction) │ +│ MG-R: Resources (maintenance, supplies, equipment) │ +│ MG-C: Communication (policy relay, expectations, culture) │ +└─────────────────────────────────────────────────────────────────┘ + ↑ creates +LAYER 2: CONDITIONS (What allowed the experience to happen?) +┌─────────────────────────────────────────────────────────────────┐ +│ CD-S: Staff State (fatigue, training, motivation, experience) │ +│ CD-T: Team Dynamics (handoffs, coordination, communication) │ +│ CD-E: Equipment (malfunction, unavailable, outdated) │ +│ CD-F: Facility (maintenance, capacity, hazards) │ +│ CD-O: Operational (understaffing, demand surge, time pressure) │ +└─────────────────────────────────────────────────────────────────┘ + ↑ enables +LAYER 1: EXPERIENCE (What the customer directly perceived) +┌─────────────────────────────────────────────────────────────────┐ +│ [Primary Domain/Category/Subcode Classification] │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## ⚠️ CAUSAL DEPTH PROHIBITION RULE + +**Causal layers (CD/MG/SY) may ONLY be assigned when the review explicitly states or logically entails the condition. Otherwise, leave `causal_chain` empty.** + +This rule prevents analysts from inventing plausible-but-unsubstantiated causes. + +### Valid Causal Inference + +| Review Text | Causal Code | Evidence | Valid? | +|-------------|-------------|----------|--------| +| "Long wait because they were short-staffed" | CD-O (Understaffing) | ES | ✓ Yes | +| "The machine was broken" | CD-E (Equipment) | ES | ✓ Yes | +| "Fifth time I've reported this issue" | MG-O (Oversight failure) | EI | ✓ Yes | +| "They seem understaffed" | — | — | ✗ No — "seem" is speculation | +| "Probably a training issue" | — | — | ✗ No — annotator speculation | +| "Management doesn't care" (stated) | SY-C (Culture) | ES | ✓ Yes | +| "Management doesn't care" (inferred) | — | — | ✗ No — if you're guessing | + +**Repeated Complaints Rule**: Multiple unresolved complaints (e.g., "third time," "keep reporting") may justify MG-O (Oversight) via EI, as the pattern logically entails failure to monitor/correct. + +**When in doubt, omit causal codes.** It's better to have no causal chain than an invented one. + +--- + +# Part 6: Implementation Profiles + +## Profile Overview + +| Profile | Use Case | Codes | Metadata Fields | Complexity | +|---------|----------|-------|-----------------|------------| +| **URT-Lite** | Micro-business, quick triage | 7 domains | 2 | Minimal | +| **URT-Core** | Small business, dashboards | 28 categories | 3 | Low | +| **URT-Standard** | Operations, routing, analytics | 140 subcodes | 7 | Medium | +| **URT-Full** | Enterprise, root cause, audit | 156 (+ causal) | 9+ | High | + +--- + +## URT-Lite Profile + +**For**: Micro-businesses, quick manual triage, getting started + +### Required Fields +| Field | Values | Notes | +|-------|--------|-------| +| **primary_code** | 7 domains (O, P, J, E, A, V, R) | Tier 1 only | +| **valence** | V+, V-, V0, V± | Basic sentiment | + +### Optional Fields +- intensity + +### Not Allowed +- secondary_codes (use Core profile or higher for multi-coding) + +### Example Record +```json +{ + "span_text": "The food was cold", + "primary_code": "O", + "valence": "V-" +} +``` + +--- + +## URT-Core Profile + +**For**: Small businesses, basic dashboards, trend tracking + +### Required Fields +| Field | Values | Notes | +|-------|--------|-------| +| **primary_code** | 28 categories (O1, P2, J3, etc.) | Tier 2 | +| **valence** | V+, V-, V0, V± | — | +| **intensity** | I1, I2, I3 | For prioritization | + +### Optional Fields +- secondary_codes (max 2, Tier 2 categories only) +- temporal +- comparative + +### Example Record +```json +{ + "span_text": "The food was cold", + "primary_code": "O2", + "valence": "V-", + "intensity": "I2" +} +``` + +--- + +## URT-Standard Profile + +**For**: Mid-size operations, team routing, full analytics + +### Required Fields +| Field | Values | Notes | +|-------|--------|-------| +| **primary_code** | 140 subcodes (O1.01, P2.03, etc.) | Tier 3 | +| **secondary_codes** | 0-2 subcodes | Multi-coding | +| **valence** | V+, V-, V0, V± | — | +| **intensity** | I1, I2, I3 | — | +| **specificity** | S1, S2, S3 | Feedback quality | +| **actionability** | A1, A2, A3 | Prioritization | +| **temporal** | TC, TR, TH, TF | Pattern detection | +| **evidence** | ES, EI, EC | Audit trail | +| **comparative** | CR-N, CR-B, CR-W, CR-S | Change tracking | + +### Optional Fields +- causal_chain +- linked_spans +- confidence + +### Example Record +```json +{ + "span_id": "span_001", + "review_id": "rev_12345", + "span_text": "The food was cold, just like last time", + "primary_code": "O2.05", + "secondary_codes": [], + "valence": "V-", + "intensity": "I2", + "specificity": "S2", + "actionability": "A2", + "temporal": "TR", + "evidence": "ES", + "comparative": "CR-S" +} +``` + +--- + +## URT-Full Profile + +**For**: Enterprise, root cause analysis, regulated contexts, audit + +### Required Fields +All URT-Standard fields, plus: + +| Field | Values | Notes | +|-------|--------|-------| +| **causal_chain** | CD/MG/SY codes | When evidence supports | +| **linked_spans** | Array of span_ids | Multi-span relationships | +| **confidence** | high, medium, low | QA tracking | +| **annotator_notes** | Free text | Audit trail | + +### Example Record +```json +{ + "span_id": "span_001", + "review_id": "rev_12345", + "span_text": "Long wait because they were clearly understaffed", + "span_start": 0, + "span_end": 47, + "primary_code": "J1.01", + "secondary_codes": ["A1.04"], + "valence": "V-", + "intensity": "I2", + "specificity": "S2", + "actionability": "A3", + "temporal": "TC", + "evidence": "ES", + "comparative": "CR-N", + "causal_chain": [ + { + "layer": "conditions", + "code": "CD-O", + "evidence": "ES" + } + ], + "linked_spans": [], + "confidence": "high", + "annotator_notes": "Customer explicitly stated understaffing as cause" +} +``` + +--- + +## Profile Comparison Matrix + +| Field | Lite | Core | Standard | Full | +|-------|:----:|:----:|:--------:|:----:| +| primary_code (Tier 1) | ✓ | — | — | — | +| primary_code (Tier 2) | — | ✓ | — | — | +| primary_code (Tier 3) | — | — | ✓ | ✓ | +| secondary_codes | ✗ | ○² | ✓³ | ✓³ | +| valence | ✓ | ✓ | ✓ | ✓ | +| intensity | ○ | ✓ | ✓ | ✓ | +| specificity | — | — | ✓ | ✓ | +| actionability | — | — | ✓ | ✓ | +| temporal | — | ○ | ✓ | ✓ | +| evidence | — | — | ✓ | ✓ | +| comparative | — | ○ | ✓ | ✓ | +| causal_chain | — | — | ○ | ✓ | +| linked_spans | — | — | ○ | ✓ | +| confidence | — | — | — | ✓ | +| annotator_notes | — | — | ○ | ✓ | + +✓ = Required | ○ = Optional | — = Not used | ✗ = Forbidden +² = Tier 2 categories only | ³ = Tier 3 subcodes only + +--- + +# Part 7: Annotation Schema + +## JSON Schema + +The schema supports all implementation profiles through flexible primary_code validation. + +**Key Constraint**: Secondary codes must always match the same tier as primary_code (Tier 2 for Core, Tier 3 for Standard/Full). Lite profile forbids secondary codes entirely. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://urt.schema/v5.1/span", + "title": "URT Span Classification v5.1", + "type": "object", + + "definitions": { + "domain": { + "type": "string", + "pattern": "^[OPJEAVR]$", + "description": "Tier 1: Domain code (URT-Lite)" + }, + "category": { + "type": "string", + "pattern": "^[OPJEAVR][1-4]$", + "description": "Tier 2: Category code (URT-Core)" + }, + "subcode": { + "type": "string", + "pattern": "^[OPJEAVR][1-4]\\.[0-9]{2}$", + "description": "Tier 3: Subcode (URT-Standard/Full)" + }, + "primary_code": { + "oneOf": [ + { "$ref": "#/definitions/domain" }, + { "$ref": "#/definitions/category" }, + { "$ref": "#/definitions/subcode" } + ], + "description": "Classification code at any tier level based on profile" + }, + "secondary_code": { + "oneOf": [ + { "$ref": "#/definitions/category" }, + { "$ref": "#/definitions/subcode" } + ], + "description": "Secondary codes (Tier 2 or 3 only)" + }, + "valence": { + "enum": ["V+", "V-", "V0", "V±"] + }, + "intensity": { + "enum": ["I1", "I2", "I3"] + }, + "specificity": { + "enum": ["S1", "S2", "S3"] + }, + "actionability": { + "enum": ["A1", "A2", "A3"] + }, + "temporal": { + "enum": ["TC", "TR", "TH", "TF"] + }, + "evidence": { + "enum": ["ES", "EI", "EC"] + }, + "comparative": { + "enum": ["CR-N", "CR-B", "CR-W", "CR-S"] + }, + "causal_code": { + "type": "string", + "pattern": "^(CD|MG|SY)-[A-Z]$" + }, + "confidence": { + "enum": ["high", "medium", "low"] + } + }, + + "properties": { + "span_id": { + "type": "string", + "description": "Unique identifier for this span" + }, + "review_id": { + "type": "string", + "description": "Parent review identifier" + }, + "span_text": { + "type": "string", + "description": "The extracted text of this span" + }, + "span_start": { + "type": "integer", + "minimum": 0, + "description": "Character offset start position" + }, + "span_end": { + "type": "integer", + "minimum": 0, + "description": "Character offset end position" + }, + "profile": { + "enum": ["lite", "core", "standard", "full"], + "description": "URT profile used for this classification" + }, + "primary_code": { + "$ref": "#/definitions/primary_code" + }, + "secondary_codes": { + "type": "array", + "items": { "$ref": "#/definitions/secondary_code" }, + "maxItems": 2, + "description": "Additional classification codes (not available in Lite)" + }, + "valence": { + "$ref": "#/definitions/valence" + }, + "intensity": { + "$ref": "#/definitions/intensity" + }, + "specificity": { + "$ref": "#/definitions/specificity" + }, + "actionability": { + "$ref": "#/definitions/actionability" + }, + "temporal": { + "$ref": "#/definitions/temporal" + }, + "evidence": { + "$ref": "#/definitions/evidence" + }, + "comparative": { + "$ref": "#/definitions/comparative" + }, + "causal_chain": { + "type": "array", + "items": { + "type": "object", + "properties": { + "layer": { + "enum": ["conditions", "management", "systemic"] + }, + "code": { + "$ref": "#/definitions/causal_code" + }, + "evidence": { + "$ref": "#/definitions/evidence" + } + }, + "required": ["layer", "code", "evidence"] + } + }, + "linked_spans": { + "type": "array", + "items": { "type": "string" }, + "description": "Related span IDs" + }, + "confidence": { + "$ref": "#/definitions/confidence" + }, + "annotator_notes": { + "type": "string" + } + }, + + "required": ["span_id", "review_id", "span_text", "primary_code", "valence", "intensity", "profile"], + + "allOf": [ + { + "if": { + "properties": { "profile": { "const": "lite" } } + }, + "then": { + "properties": { + "primary_code": { "$ref": "#/definitions/domain" }, + "secondary_codes": { "maxItems": 0 } + }, + "not": { + "anyOf": [ + { "properties": { "primary_code": { "$ref": "#/definitions/category" } } }, + { "properties": { "primary_code": { "$ref": "#/definitions/subcode" } } }, + { "required": ["specificity"] }, + { "required": ["actionability"] }, + { "required": ["evidence"] }, + { "required": ["comparative"] }, + { "required": ["causal_chain"] } + ] + } + } + }, + { + "if": { + "properties": { "profile": { "const": "core" } } + }, + "then": { + "properties": { + "primary_code": { "$ref": "#/definitions/category" }, + "secondary_codes": { + "items": { "$ref": "#/definitions/category" }, + "maxItems": 2 + } + }, + "not": { + "anyOf": [ + { "properties": { "primary_code": { "$ref": "#/definitions/domain" } } }, + { "properties": { "primary_code": { "$ref": "#/definitions/subcode" } } }, + { "required": ["specificity"] }, + { "required": ["actionability"] }, + { "required": ["evidence"] }, + { "required": ["causal_chain"] } + ] + } + } + }, + { + "if": { + "properties": { "profile": { "const": "standard" } } + }, + "then": { + "properties": { + "primary_code": { "$ref": "#/definitions/subcode" }, + "secondary_codes": { + "items": { "$ref": "#/definitions/subcode" }, + "maxItems": 2 + } + }, + "not": { + "anyOf": [ + { "properties": { "primary_code": { "$ref": "#/definitions/domain" } } }, + { "properties": { "primary_code": { "$ref": "#/definitions/category" } } }, + { "required": ["causal_chain"] } + ] + } + } + }, + { + "if": { + "properties": { "profile": { "const": "full" } } + }, + "then": { + "properties": { + "primary_code": { "$ref": "#/definitions/subcode" }, + "secondary_codes": { + "items": { "$ref": "#/definitions/subcode" }, + "maxItems": 2 + } + }, + "not": { + "anyOf": [ + { "properties": { "primary_code": { "$ref": "#/definitions/domain" } } }, + { "properties": { "primary_code": { "$ref": "#/definitions/category" } } } + ] + } + } + } + ] +} +``` + +### Profile-Specific Validation + +| Profile | primary_code | secondary_codes | Forbidden | +|---------|--------------|-----------------|-----------| +| **Lite** | Domain only (`^[OPJEAVR]$`) | ✗ Not allowed | Categories, subcodes, S/A/E/CR/causal | +| **Core** | Category only (`^[OPJEAVR][1-4]$`) | Tier 2 only (max 2) | Domains, subcodes, S/A/E/causal | +| **Standard** | Subcode only (`^[OPJEAVR][1-4]\.[0-9]{2}$`) | Tier 3 only (max 2) | Domains, categories, causal_chain | +| **Full** | Subcode only (`^[OPJEAVR][1-4]\.[0-9]{2}$`) | Tier 3 only (max 2) | Domains, categories | + +**Validation enforces**: +- Correct tier for profile (no Tier 3 in Core, no Tier 2 in Standard/Full) +- Profile-appropriate metadata fields +- Causal chain only in Full profile + +--- + +# Part 8: Quick Decision Tree + +``` +START: Read the span + │ + ▼ +┌─────────────────────────────────────────────┐ +│ Is it about the THING they bought/received? │ +│ (product, service, treatment, outcome) │ +└─────────────────────────────────────────────┘ + │ YES → O (Offering) + │ NO ↓ + ▼ +┌─────────────────────────────────────────────┐ +│ Is it about HOW PEOPLE behaved or treated │ +│ them? (staff attitude, skill, communication)│ +└─────────────────────────────────────────────┘ + │ YES → P (People) + │ NO ↓ + ▼ +┌─────────────────────────────────────────────┐ +│ Is it about TIME, STEPS, or FRICTION? │ +│ (waiting, process, ease, resolution) │ +└─────────────────────────────────────────────┘ + │ YES → J (Journey) + │ NO ↓ + ▼ +┌─────────────────────────────────────────────┐ +│ Is it about the SPACE or INTERFACE? │ +│ (physical place, app/website, ambiance) │ +└─────────────────────────────────────────────┘ + │ YES → E (Environment) + │ NO ↓ + ▼ +┌─────────────────────────────────────────────┐ +│ Is it about ABILITY TO ACCESS or INCLUSION? │ +│ (availability, disability, language, bias) │ +└─────────────────────────────────────────────┘ + │ YES → A (Access) + │ NO ↓ + ▼ +┌─────────────────────────────────────────────┐ +│ Is it about PRICE, COST, or WORTH? │ +│ (money, effort, value, transparency) │ +└─────────────────────────────────────────────┘ + │ YES → V (Value) + │ NO ↓ + ▼ +┌─────────────────────────────────────────────┐ +│ Is it about TRUST, PATTERNS, or LOYALTY? │ +│ (honesty over time, brand, recovery, bond) │ +└─────────────────────────────────────────────┘ + │ YES → R (Relationship) + │ NO ↓ + ▼ + RE-READ SPAN — may need splitting +``` + +--- + +# Part 9: Worked Examples + +## Example 1: Restaurant Review + +> "The pasta was perfectly al dente and beautifully plated, but our waiter disappeared for 20 minutes and we had to flag down someone else to get the check. Good value for a nice dinner out." + +| Span | Primary | Secondary | V | I | S | A | T | E | CR | +|------|---------|-----------|---|---|---|---|---|---|-----| +| "pasta was perfectly al dente" | O1.02 | — | V+ | I2 | S2 | A2 | TC | ES | CR-N | +| "beautifully plated" | O2.03 | — | V+ | I2 | S2 | A2 | TC | ES | CR-N | +| "waiter disappeared for 20 minutes" | P3.03 | — | V- | I2 | S3 | A3 | TC | ES | CR-N | +| "flag down someone else" | P3.01 | — | V- | I2 | S2 | A2 | TC | ES | CR-N | +| "Good value for nice dinner" | V4.01 | — | V+ | I1 | S1 | A1 | TC | ES | CR-N | + +--- + +## Example 2: B2B Software with Improvement Signal + +> "Implementation took twice as long as promised, but once we went live, the system has been rock solid. Much more stable than the last version we used." + +| Span | Primary | Secondary | V | I | CR | Note | +|------|---------|-----------|---|---|-----|------| +| "Implementation took twice as long" | J1.02 | R1.02 | V- | I3 | CR-N | No comparison to before | +| "system has been rock solid" | O1.04 | — | V+ | I3 | CR-N | Current state | +| "Much more stable than last version" | O1.04 | — | V+ | I2 | **CR-B** | Explicit improvement | + +--- + +## Example 3: Persistent Problem + +> "Still waiting forever for appointments. Third time I've complained about this and nothing has changed." + +| Span | Primary | Secondary | V | I | CR | Note | +|------|---------|-----------|---|---|-----|------| +| "Still waiting forever for appointments" | A1.02 | J1.01 | V- | I3 | **CR-S** | "Still" = unchanged | +| "Third time I've complained" | J4.05 | R3.04 | V- | I2 | **CR-S** | Pattern, nothing changed | + +**Causal Chain** (if using Full profile): +- MG-O (Management: Oversight failure) — Evidence: EI + +**Causal Justification**: Repeated unresolved complaints justify MG-O (Management Oversight) via EI because failure to monitor and correct a known issue is logically entailed by "third time" + "nothing has changed." + +--- + +## Example 4: Quality Decline + +> "This used to be my favorite restaurant but the quality has really gone downhill since they changed chefs." + +| Span | Primary | Secondary | V | I | CR | Note | +|------|---------|-----------|---|---|-----|------| +| "used to be my favorite" | R2.02 | — | V- | I2 | **CR-W** | Consistency lost over time | +| "quality has really gone downhill" | O2.02 | — | V- | I3 | **CR-W** | Explicit decline | +| "since they changed chefs" | — | — | — | — | — | Context, not separate span | + +--- + +## Example 5: Service Recovery with Resolution Confirmation + +> "My package arrived damaged, which was frustrating. But they immediately sent a replacement and it arrived perfect. Great recovery!" + +| Span | Primary | Secondary | V | I | CR | Role | +|------|---------|-----------|---|---|-----|------| +| "package arrived damaged" | O2.05 | — | V- | I2 | CR-N | Problem | +| "immediately sent replacement" | R3.03 | J4.03 | V+ | I2 | CR-N | Recovery | +| "arrived perfect" | O2.05 | — | V+ | I2 | **CR-B** | Resolution confirmed | +| "Great recovery" | R3 | — | V+ | I2 | CR-N | Summary | + +--- + +## Example 6: "Scam" vs "Rip-off" Classification + +> "Total scam company. They charged me twice and refused to refund. This is robbery." + +| Span | Primary | Secondary | V | I | CR | +|------|---------|-----------|---|---|-----| +| "Total scam company" | R1.04 (Ethics) | — | V- | I3 | CR-N | +| "charged me twice" | J3.02 (Accuracy) | — | V- | I2 | CR-N | +| "refused to refund" | R3.03 (Compensation) | V2.04 | V- | I2 | CR-N | +| "This is robbery" | V4.01 (Overall Value) | — | V- | I3 | CR-N | + +**Note**: "Scam" = R1.04 (moral judgment about intent). "Robbery" = V4.01 (about the exchange). + +--- + +# Part 10: Inter-Annotator Consistency Rules + +## Mandatory Conventions + +1. **One primary code per span** — no exceptions +2. **Max 2 secondary codes** — prevents over-tagging +3. **Max 3 spans per sentence** — if more, reconsider boundaries +4. **Prefer splitting over V±** — unless truly inseparable +5. **Check "Don't Confuse With"** — before finalizing subcode +6. **Evidence type required** — must justify EI inferences +7. **No invented causes** — causal_chain only when text supports +8. **CR-N is default** — only use CR-B/W/S when comparison is explicit + +## Tie-Break Rules + +When annotators disagree: + +1. **Different domains**: Use decision tree; first "yes" wins +2. **Different subcodes in same category**: Prefer more specific +3. **Different intensity**: Defer to linguistic markers +4. **Different actionability**: A3 requires concrete implementable action +5. **Different CR**: CR-N unless explicit temporal language present + +## Calibration Protocol + +Weekly team calibration: +- 5 straightforward spans (target: 95% agreement) +- 3 ambiguous spans (discuss reasoning) +- 2 edge cases (document resolution) +- 2 CR-specific spans (practice temporal detection) + +--- + +# Part 11: Code Statistics + +## Final Counts + +| Component | Count | +|-----------|-------| +| **Tier 1: Domains** | 7 | +| **Tier 2: Categories** | 28 | +| **Tier 3: Subcodes** | 140 | +| **Causal Codes** | 16 | +| **Metadata Dimensions** | 7 | +| **Metadata Values** | 24 | + +## Breakdown by Domain + +| Domain | Categories | Subcodes | +|--------|------------|----------| +| O (Offering) | 4 | 18 | +| P (People) | 4 | 20 | +| J (Journey) | 4 | 20 | +| E (Environment) | 4 | 20 | +| A (Access) | 4 | 20 | +| V (Value) | 4 | 20 | +| R (Relationship) | 4 | 20 | +| **Total** | **28** | **140** | + +## Causal Codes + +| Layer | Prefix | Codes | Count | +|-------|--------|-------|-------| +| Conditions | CD- | S, T, E, F, O | 5 | +| Management | MG- | P, T, O, R, C | 5 | +| Systemic | SY- | R, P, C, S, H, X | 6 | +| **Total** | | | **16** | + +## Metadata Values + +| Dimension | Values | Count | +|-----------|--------|-------| +| Valence | V+, V-, V0, V± | 4 | +| Intensity | I1, I2, I3 | 3 | +| Specificity | S1, S2, S3 | 3 | +| Actionability | A1, A2, A3 | 3 | +| Temporal | TC, TR, TH, TF | 4 | +| Evidence | ES, EI, EC | 3 | +| Comparative | CR-N, CR-B, CR-W, CR-S | 4 | +| **Total** | | **24** | + +--- + +# Part 12: Quick Reference Card + +## Domains (7) +| O | P | J | E | A | V | R | +|---|---|---|---|---|---|---| +| Offering | People | Journey | Environment | Access | Value | Relationship | + +## Categories (28) +``` +O: O1 Function O2 Quality O3 Completeness O4 Fit +P: P1 Attitude P2 Competence P3 Responsiveness P4 Communication +J: J1 Timing J2 Ease J3 Reliability J4 Resolution +E: E1 Physical E2 Digital E3 Ambiance E4 Safety +A: A1 Availability A2 Accessibility A3 Inclusivity A4 Convenience +V: V1 Price V2 Transparency V3 Effort V4 Worth +R: R1 Integrity R2 Dependability R3 Recovery R4 Loyalty +``` + +## Metadata (7 dimensions, 24 values) +| Dimension | Codes | +|-----------|-------| +| Valence | V+ V- V0 V± | +| Intensity | I1 I2 I3 | +| Specificity | S1 S2 S3 | +| Actionability | A1 A2 A3 | +| Temporal | TC TR TH TF | +| Evidence | ES EI EC | +| **Comparative** | **CR-N CR-B CR-W CR-S** | + +## Causal Layers (Optional) +| Layer | Prefix | Focus | +|-------|--------|-------| +| Conditions | CD- | What allowed it (S/T/E/F/O) | +| Management | MG- | What decisions created it (P/T/O/R/C) | +| Systemic | SY- | What org forces drove it (R/P/C/S/H/X) | + +## Implementation Profiles +| Profile | Codes | Metadata | Use Case | +|---------|-------|----------|----------| +| **Lite** | 7 domains | 2 | Micro, triage | +| **Core** | 28 categories | 3 | Small, dashboards | +| **Standard** | 140 subcodes | 7 | Operations, routing | +| **Full** | 156 total | 9+ | Enterprise, audit | + +--- + +# Appendix A: Comparative Reference (CR) Trigger Words + +Quick reference for detecting CR-B/W/S: + +## CR-B (Better) Triggers +- "better now" +- "improved" +- "finally fixed" +- "much faster/cleaner/friendlier than before" +- "they've turned it around" +- "glad they addressed it" +- "not like last time" (positive context) + +## CR-W (Worse) Triggers +- "worse now" +- "used to be good" +- "has gone downhill" +- "not what it used to be" +- "declining" +- "deteriorating" +- "they've really fallen off" + +## CR-S (Same) Triggers +- "still" +- "as always" +- "same as before" +- "nothing has changed" +- "yet again" +- "once again" +- "as usual" (positive or negative) + +## CR-N (None) — Default +- No temporal comparison language +- First-time customer +- Competitor comparison (not self-comparison) +- General statement without "before/after" framing + +--- + +# Appendix B: Related Documents + +This specification is part of the URT document set: + +| Document | Purpose | Status | +|----------|---------|--------| +| **URT Specification v5.1** | This document — canonical codes and rules | Frozen | +| **URT String Notation (USN)** | Compact serialization format (Appendix C) | Included | +| **URT Issue Lifecycle Framework** | Analytics layer for resolution tracking | Separate document | +| **URT Annotation Manual** | Training materials (to be extracted) | Planned | +| **URT QA Protocol** | Calibration and audit procedures | Planned | + +--- + +# Appendix C: URT String Notation (USN) + +A compact single-line format for URT classifications, analogous to CVE identifiers for vulnerabilities. + +## Purpose + +USN enables: +- Quick manual tagging in tickets/notes +- Log entries and audit trails +- API responses and webhooks +- Spreadsheet-friendly format +- Cross-system communication +- Human-readable shorthand + +## Format Specification + +``` +USN := URT:{profile}:{codes}:{valence}{intensity}[:{metadata}][:{causal}] +``` + +| Component | Format | Required | Examples | +|-----------|--------|----------|----------| +| **Prefix** | `URT:` | Always | `URT:` | +| **Profile** | `L` / `C` / `S` / `F` | Always | `S` | +| **Codes** | `{primary}[+{sec1}][+{sec2}]` | Always | `P1.02+V2.04` | +| **Valence** | `+` / `-` / `0` / `±` | Always | `-` | +| **Intensity** | `1` / `2` / `3` | Always | `3` | +| **Metadata** | `{S}{A}{T}.{E}.{CR}` | Standard+ | `22TC.ES.N` | +| **Causal** | `{layer}.{code}[,...]` | Full only | `CD.O,MG.O` | + +## Profile Formats + +### URT-Lite +``` +URT:L:{domain}:{valence}{intensity} +``` +**Examples:** +``` +URT:L:O:-2 → Offering, negative, moderate +URT:L:P:+3 → People, positive, strong +URT:L:V:-1 → Value, negative, mild +``` + +### URT-Core +``` +URT:C:{category}:{valence}{intensity} +``` +**Examples:** +``` +URT:C:O2:-2 → Quality issue, negative, moderate +URT:C:P1:+3 → Attitude praise, positive, strong +URT:C:J1:-3 → Timing complaint, negative, strong +``` + +### URT-Standard +``` +URT:S:{subcode}[+{sec}]:{valence}{intensity}:{S}{A}{T}.{E}.{CR} +``` +**Examples:** +``` +URT:S:P1.02:-3:22TC.ES.N → Respect issue, negative, strong +URT:S:O2.05+J4.02:-2:33TC.ES.B → Damaged + resolution, improving +URT:S:J1.01+A1.04:-2:23TC.ES.S → Wait time (understaffed), persistent +``` + +### URT-Full +``` +URT:F:{subcode}[+{sec}]:{valence}{intensity}:{S}{A}{T}.{E}.{CR}:{causal} +``` +**Examples:** +``` +URT:F:J1.01+A1.04:-2:23TC.ES.S:CD.O,MG.O → Wait + understaffing + oversight +URT:F:P1.02:-3:32TC.ES.N:CD.S → Rude staff, staff state cause +``` + +## Metadata Encoding + +| Dimension | Position | Values | Meaning | +|-----------|----------|--------|---------| +| **Specificity** | 1 | `1` / `2` / `3` | S1, S2, S3 | +| **Actionability** | 2 | `1` / `2` / `3` | A1, A2, A3 | +| **Temporal** | 3-4 | `TC` / `TR` / `TH` / `TF` | Current/Recent/Historical/Future | +| **Evidence** | 5-6 | `ES` / `EI` / `EC` | Stated/Inferred/Contextual | +| **Comparative** | 7 | `N` / `B` / `W` / `S` | None/Better/Worse/Same | + +**Format**: `{S}{A}{T}.{E}.{CR}` + +**Examples:** +| Metadata String | Meaning | +|-----------------|---------| +| `22TC.ES.N` | S2, A2, current visit, stated, no comparison | +| `33TR.EI.S` | S3, A3, recent pattern, inferred, same as before | +| `11TH.ES.W` | S1, A1, historical, stated, worse than before | + +## Causal Chain Encoding + +| Layer | Prefix | Codes | +|-------|--------|-------| +| Conditions | `CD` | `S` / `T` / `E` / `F` / `O` | +| Management | `MG` | `P` / `T` / `O` / `R` / `C` | +| Systemic | `SY` | `R` / `P` / `C` / `S` / `H` / `X` | + +**Format**: `{layer}.{code}[,{layer}.{code}]` + +**Examples:** +| Causal String | Meaning | +|---------------|---------| +| `CD.O` | Conditions: Operational (understaffing) | +| `CD.E,MG.R` | Conditions: Equipment → Management: Resources | +| `SY.C` | Systemic: Culture | +| `CD.S,MG.T,SY.H` | Staff state → Training gap → Human capital | + +## Complete Examples + +| Review Span | USN | Interpretation | +|-------------|-----|----------------| +| "Food was cold" | `URT:L:O:-2` | Offering issue, negative, moderate | +| "Food was cold" | `URT:C:O2:-2` | Quality issue, negative, moderate | +| "Food was cold, like last time" | `URT:S:O2.05:-2:22TR.ES.S` | Condition at delivery, persistent | +| "Rude staff and unfair policy" | `URT:S:P1.02+V2.04:-3:22TC.ES.N` | Respect + terms, strong negative | +| "Still waiting, third complaint" | `URT:F:A1.02+J1.01:-3:23TR.EI.S:MG.O` | Booking + wait, oversight failure | +| "Much better service now!" | `URT:S:P3.05:+2:11TC.ES.B` | Urgency improved | +| "Total scam company" | `URT:S:R1.04:-3:12TC.ES.N` | Ethics, strong negative | +| "Great as always" | `URT:S:V4.01:+2:11TR.ES.S` | Value, consistent praise | + +## Validation Patterns + +### Regex by Profile + +```regex +# Lite +^URT:L:[OPJEAVR]:[+\-0±][123]$ + +# Core +^URT:C:[OPJEAVR][1-4]:[+\-0±][123]$ + +# Standard +^URT:S:[OPJEAVR][1-4]\.[0-9]{2}(\+[OPJEAVR][1-4]\.[0-9]{2}){0,2}:[+\-0±][123]:[1-3][1-3]T[CRHF]\.E[SIC]\.[NBWS]$ + +# Full (with optional causal) +^URT:F:[OPJEAVR][1-4]\.[0-9]{2}(\+[OPJEAVR][1-4]\.[0-9]{2}){0,2}:[+\-0±][123]:[1-3][1-3]T[CRHF]\.E[SIC]\.[NBWS](:(CD|MG|SY)\.[STEOFRPCSHX](,(CD|MG|SY)\.[STEOFRPCSHX])*)?$ +``` + +### Validation Rules + +1. **Profile must match code tier**: `L` → domain, `C` → category, `S`/`F` → subcode +2. **Secondary codes forbidden in Lite**: No `+` allowed +3. **Secondary codes match profile tier**: Core uses categories, Standard/Full use subcodes +4. **Metadata required for Standard/Full**: Cannot omit `:{S}{A}{T}.{E}.{CR}` +5. **Causal only in Full**: `:{causal}` segment only valid with `F` profile + +## Use Cases + +| Context | Example | +|---------|---------| +| **Ticket tag** | `[URT:S:P1.02:-3:22TC.ES.N]` | +| **Log entry** | `2026-01-23 14:32:01 FEEDBACK span_042 URT:S:J1.01:-2:33TC.ES.S` | +| **Spreadsheet cell** | `URT:C:O2:-2` | +| **API response** | `{"usn": "URT:S:O2.05+J4.02:-2:23TC.ES.B"}` | +| **Slack message** | "New I3 alert: `URT:S:P1.02:-3:22TC.ES.N` — HR review needed" | +| **Dashboard filter** | Show all `URT:*:J1.*:-3:*` (strong timing complaints) | +| **Audit trail** | `CLASSIFIED rev_12345 span_003 URT:F:J1.01:-2:23TC.ES.S:CD.O` | + +## Parser Reference + +```python +import re + +def parse_usn(usn: str) -> dict: + """Parse URT String Notation into structured dict.""" + + parts = usn.split(':') + if parts[0] != 'URT': + raise ValueError("Invalid USN: must start with 'URT:'") + + profile = parts[1] + codes = parts[2].split('+') + valence = parts[3][0] + intensity = int(parts[3][1]) + + result = { + 'profile': profile, + 'primary_code': codes[0], + 'secondary_codes': codes[1:] if len(codes) > 1 else [], + 'valence': {'+':"V+", '-':"V-", '0':"V0", '±':"V±"}[valence], + 'intensity': f"I{intensity}" + } + + # Standard and Full have metadata + if profile in ['S', 'F'] and len(parts) > 4: + meta = parts[4] + result['specificity'] = f"S{meta[0]}" + result['actionability'] = f"A{meta[1]}" + result['temporal'] = meta[2:4] + result['evidence'] = meta.split('.')[1] + result['comparative'] = f"CR-{meta.split('.')[2]}" + + # Full may have causal chain + if profile == 'F' and len(parts) > 5: + causal_parts = parts[5].split(',') + result['causal_chain'] = [ + {'layer': c.split('.')[0], 'code': c.split('.')[1]} + for c in causal_parts + ] + + return result + + +def to_usn(record: dict) -> str: + """Convert URT record to String Notation.""" + + profile_map = {'lite': 'L', 'core': 'C', 'standard': 'S', 'full': 'F'} + profile = profile_map[record['profile']] + + # Codes + codes = record['primary_code'] + if record.get('secondary_codes'): + codes += '+' + '+'.join(record['secondary_codes']) + + # Valence + Intensity + valence = {'+': '+', '-': '-', '0': '0', '±': '±'}[record['valence'][-1]] + intensity = record['intensity'][-1] + vi = f"{valence}{intensity}" + + usn = f"URT:{profile}:{codes}:{vi}" + + # Metadata for Standard/Full + if profile in ['S', 'F']: + s = record['specificity'][-1] + a = record['actionability'][-1] + t = record['temporal'] + e = record['evidence'] + cr = record['comparative'].split('-')[1] + usn += f":{s}{a}{t}.{e}.{cr}" + + # Causal for Full + if profile == 'F' and record.get('causal_chain'): + causal = ','.join( + f"{c['layer']}.{c['code']}" + for c in record['causal_chain'] + ) + usn += f":{causal}" + + return usn +``` + +## USN Quick Reference + +``` +FORMAT: URT:{P}:{codes}:{V}{I}[:{meta}][:{causal}] + +PROFILE: L=Lite C=Core S=Standard F=Full + +CODES: O/P/J/E/A/V/R (Lite) + O1-O4, P1-P4, etc. (Core) + O1.01-R4.05 (Standard/Full) + + for secondary: P1.02+V2.04 + +VALENCE: + positive - negative 0 neutral ± mixed +INTENSITY: 1 mild 2 moderate 3 strong + +METADATA (Standard+): + {S}{A}{T}.{E}.{CR} + S/A = 1/2/3 + T = TC/TR/TH/TF + E = ES/EI/EC + CR = N/B/W/S + +CAUSAL (Full only): + CD.S/T/E/F/O (Conditions) + MG.P/T/O/R/C (Management) + SY.R/P/C/S/H/X (Systemic) +``` + +--- + +# Document Control + +| Field | Value | +|-------|-------| +| **Status** | Frozen — Production Ready | +| **Version** | 5.1 | +| **Release Date** | 2026-01-23 | +| **Total Classification Codes** | 156 (140 subcodes + 16 causal) | +| **Metadata Dimensions** | 7 | +| **Metadata Values** | 24 | +| **Implementation Profiles** | 4 (Lite, Core, Standard, Full) | +| **String Notation** | USN (Appendix C) | +| **Designed For** | Universal applicability across industries, scales, cultures | +| **Key Innovations** | CR dimension, multi-profile schema, cause-effect span rules, USN format | + +--- + +*End of URT Specification v5.1* \ No newline at end of file diff --git a/urt-taxonomy/track-a-training/A1-Annotator-Quickstart.md b/urt-taxonomy/track-a-training/A1-Annotator-Quickstart.md new file mode 100644 index 0000000..e275b76 --- /dev/null +++ b/urt-taxonomy/track-a-training/A1-Annotator-Quickstart.md @@ -0,0 +1,925 @@ +# A1: Annotator Quickstart Guide +## Universal Review Taxonomy (URT) v5.1 + +**Purpose**: Quick reference for human annotators to classify review spans +**Version**: 5.1 | **Status**: Production Ready | **Date**: 2026-01-23 + +--- + +## Table of Contents + +1. [Quick Decision Tree](#1-quick-decision-tree) +2. [Domain Summary Table](#2-domain-summary-table) +3. [Category Quick Reference (28 Categories)](#3-category-quick-reference) + - [3.5 High-Frequency Subcodes](#35-high-frequency-subcodes-quick-reference) +4. [Metadata Cheat Sheet](#4-metadata-cheat-sheet) +5. [Common Mistakes to Avoid](#5-common-mistakes-to-avoid) +6. [V vs R Rule: Scam vs Rip-off](#6-v-vs-r-rule-scam-vs-rip-off) +7. [J4 vs R3 Rule: Process vs Ownership](#7-j4-vs-r3-rule-process-vs-ownership) +8. [Span Boundary Rules](#8-span-boundary-rules) +9. [Worked Examples](#9-worked-examples) +10. [USN Quick Reference](#10-usn-quick-reference) +11. [Billing/Returns/Refunds Decision Table](#11-billingreturnsrefunds-decision-table) +12. [Data Privacy/Security Decision Table](#12-data-privacysecurity-decision-table) +13. [CR Trigger Word Reference](#13-cr-trigger-word-reference) +14. [Causal Chain Quick Guide](#14-causal-chain-quick-guide-full-profile-only) +15. [Inter-Annotator Agreement Rules](#15-inter-annotator-agreement-rules) + +--- + +## 1. Quick Decision Tree + +Use this flowchart for every span. Go top-to-bottom; first "YES" wins. + +``` +START: Read the span + | + v ++-----------------------------------------------+ +| Is it about the THING they bought/received? | +| (product, service, treatment, outcome) | ++-----------------------------------------------+ + | YES --> O (Offering) + | NO | + v ++-----------------------------------------------+ +| Is it about HOW PEOPLE behaved? | +| (staff attitude, skill, communication) | ++-----------------------------------------------+ + | YES --> P (People) + | NO | + v ++-----------------------------------------------+ +| Is it about TIME, STEPS, or FRICTION? | +| (waiting, process, ease, resolution steps) | ++-----------------------------------------------+ + | YES --> J (Journey) + | NO | + v ++-----------------------------------------------+ +| Is it about the SPACE or INTERFACE? | +| (physical place, app/website, ambiance) | ++-----------------------------------------------+ + | YES --> E (Environment) + | NO | + v ++-----------------------------------------------+ +| Is it about ABILITY TO ACCESS or INCLUSION? | +| (availability, disability, language, bias) | ++-----------------------------------------------+ + | YES --> A (Access) + | NO | + v ++-----------------------------------------------+ +| Is it about PRICE, COST, or WORTH? | +| (money, effort, value, transparency) | ++-----------------------------------------------+ + | YES --> V (Value) + | NO | + v ++-----------------------------------------------+ +| Is it about TRUST, PATTERNS, or LOYALTY? | +| (honesty over time, brand, recovery, bond) | ++-----------------------------------------------+ + | YES --> R (Relationship) + | NO | + v + RE-READ SPAN -- may need splitting +``` + +**Memory Aid**: O-P-J-E-A-V-R = "**O**ffer **P**eople a **J**ourney in an **E**nvironment with **A**ccess to **V**alue and **R**elationship" + +--- + +## 2. Domain Summary Table + +| Code | Domain | Core Question | One-Line Definition | Example (+) | Example (-) | +|------|--------|---------------|---------------------|-------------|-------------| +| **O** | Offering | Does it work? | The core product/service delivered | "Perfectly cooked steak" | "Phone won't charge" | +| **P** | People | How did they treat me? | Human interactions and behavior | "So helpful and patient" | "Rude and dismissive" | +| **J** | Journey | Was it smooth? | Process, timing, friction | "Seated immediately" | "Waited 45 minutes" | +| **E** | Environment | Is the space okay? | Physical, digital, ambient context | "Beautiful clean space" | "App keeps crashing" | +| **A** | Access | Can I get it? | Availability, accessibility, inclusion | "Open 24/7" | "No wheelchair ramp" | +| **V** | Value | Is it worth it? | Cost, pricing, and worth | "Great bang for buck" | "Total rip-off" | +| **R** | Relationship | Can I trust them? | Trust, reliability, loyalty | "Always reliable" | "Shady company" | + +### Default Owner Routing + +| Domain | Default Owner | +|--------|---------------| +| O | Product / Operations | +| P | HR / Training | +| J | Operations / Process | +| E | Facilities / IT | +| A | Compliance / Design | +| V | Finance / Pricing | +| R | Leadership / CX | + +--- + +## 3. Category Quick Reference + +**28 Categories** - 4 per domain. Use this for URT-Core or to narrow down to subcodes. + +### O - Offering (4 categories, 18 subcodes) + +| Code | Category | Definition | +|------|----------|------------| +| **O1** | Function | Does it do what it's supposed to do? | +| **O2** | Quality | How well is it made or executed? | +| **O3** | Completeness | Is everything included that should be? | +| **O4** | Fit | Does it match customer's specific needs? | + +### P - People (4 categories, 20 subcodes) + +| Code | Category | Definition | +|------|----------|------------| +| **P1** | Attitude | Disposition, manner, emotional tone of staff | +| **P2** | Competence | Knowledge, skill, professional capability | +| **P3** | Responsiveness | Attentiveness, initiative, follow-through | +| **P4** | Communication | Quality of information exchange | + +### J - Journey (4 categories, 20 subcodes) + +| Code | Category | Definition | +|------|----------|------------| +| **J1** | Timing | Speed, punctuality, time management | +| **J2** | Ease | Effort required and friction encountered | +| **J3** | Reliability | Consistency and predictability of process | +| **J4** | Resolution | How problems are handled when they arise | + +### E - Environment (4 categories, 20 subcodes) + +| Code | Category | Definition | +|------|----------|------------| +| **E1** | Physical Space | Tangible environment attributes | +| **E2** | Digital Space | Online and application interface | +| **E3** | Ambiance | Intangible environmental qualities (mood, noise) | +| **E4** | Safety | Security and wellbeing factors | + +### A - Access (4 categories, 20 subcodes) + +| Code | Category | Definition | +|------|----------|------------| +| **A1** | Availability | Can you get it when you need it? | +| **A2** | Accessibility | Can everyone use it regardless of ability? | +| **A3** | Inclusivity | Does it work for diverse backgrounds? | +| **A4** | Convenience | Is it easy to reach and engage with? | + +### V - Value (4 categories, 20 subcodes) + +| Code | Category | Definition | +|------|----------|------------| +| **V1** | Price | The monetary cost itself | +| **V2** | Transparency | Clarity and honesty about costs | +| **V3** | Effort | Non-monetary costs (time, hassle, mental load) | +| **V4** | Worth | Overall value assessment | + +### R - Relationship (4 categories, 20 subcodes) + +| Code | Category | Definition | +|------|----------|------------| +| **R1** | Integrity | Honesty and ethical behavior | +| **R2** | Dependability | Consistency over time | +| **R3** | Recovery | Response to failures (ownership, apology, compensation) | +| **R4** | Loyalty | Investment in ongoing relationship | + +--- + +## 3.5 High-Frequency Subcodes Quick Reference + +These are the most commonly used subcodes across all domains. Memorize these first. + +### Offering (O) - Top Subcodes + +| Code | Name | Definition | + Example | - Example | +|------|------|------------|-----------|-----------| +| O1.01 | Works/Doesn't Work | Basic functionality | "Software runs perfectly" | "Car won't start" | +| O1.02 | Performance Level | How well it operates | "Incredibly fast" | "Sluggish and laggy" | +| O1.05 | Outcome Achievement | Did customer accomplish goal? | "Passed my exam!" | "Treatment didn't work" | +| O2.01 | Materials/Inputs | Quality of components | "Real leather" | "Cheap plastic parts" | +| O2.03 | Presentation | Visual/aesthetic quality | "Gorgeous plating" | "Looked thrown together" | +| O2.05 | Condition at Delivery | State when received | "Still warm" | "Arrived damaged" | +| O4.01 | Specification Match | Matches what was ordered | "Exactly right" | "Wrong size delivered" | + +### People (P) - Top Subcodes + +| Code | Name | Definition | + Example | - Example | +|------|------|------------|-----------|-----------| +| P1.01 | Warmth/Friendliness | Approachability | "So welcoming" | "Cold and unfriendly" | +| P1.02 | Respect | Treating with dignity | "Made me feel valued" | "Talked down to me" | +| P1.03 | Empathy | Understanding situation | "Really got my frustration" | "Couldn't care less" | +| P2.01 | Knowledge | Understanding of products | "Knew every detail" | "Couldn't answer basics" | +| P2.03 | Problem-Solving | Ability to address issues | "Found creative solution" | "Just said 'can't'" | +| P3.01 | Attentiveness | Awareness of needs | "Always checking in" | "Had to flag them down" | +| P3.03 | Availability | Present when needed | "Easy to find someone" | "Impossible to reach" | +| P4.01 | Clarity | Understandable info | "Explained clearly" | "Confusing jargon" | + +### Journey (J) - Top Subcodes + +| Code | Name | Definition | + Example | - Example | +|------|------|------------|-----------|-----------| +| J1.01 | Wait Time | Time spent waiting | "Seated immediately" | "45 min past appointment" | +| J1.02 | Service Speed | Time for delivery | "Next day delivery" | "Took three weeks" | +| J1.03 | Response Time | Time to address inquiries | "Replied in minutes" | "Days for a response" | +| J2.01 | Simplicity | Straightforward processes | "So easy to do" | "Needlessly complicated" | +| J3.02 | Accuracy | Correct execution | "Order exactly right" | "Wrong items delivered" | +| J4.02 | Resolution Process | How problems handled | "Clear escalation path" | "Transferred in circles" | +| J4.03 | Resolution Speed | Time to fix | "Fixed same day" | "Took weeks to resolve" | + +### Environment (E) - Top Subcodes + +| Code | Name | Definition | + Example | - Example | +|------|------|------------|-----------|-----------| +| E1.01 | Cleanliness | Hygiene and tidiness | "Spotless facilities" | "Filthy bathrooms" | +| E1.02 | Maintenance | Condition and upkeep | "Everything works" | "Broken equipment" | +| E2.01 | Interface Design | Visual/interaction quality | "Beautiful app" | "Cluttered mess" | +| E2.02 | Functionality | Features working | "Everything works" | "Buttons broken" | +| E3.01 | Atmosphere/Vibe | Overall mood | "Calm and relaxing" | "Stressful chaos" | +| E4.01 | Physical Safety | Protection from harm | "Felt completely safe" | "Dangerous conditions" | + +### Access (A) - Top Subcodes + +| Code | Name | Definition | + Example | - Example | +|------|------|------------|-----------|-----------| +| A1.01 | Operating Hours | When accessible | "Open 24/7" | "Banker's hours only" | +| A1.02 | Booking Access | Ability to schedule | "Easy online booking" | "3 weeks for appointment" | +| A1.03 | Inventory/Capacity | Available | "Always in stock" | "Perpetually sold out" | +| A2.01 | Physical Accessibility | Mobility accommodations | "Wheelchair accessible" | "No ramps or elevators" | +| A3.01 | Language Support | Multiple languages | "Staff spoke my language" | "English only, no help" | +| A4.01 | Location | Physical accessibility | "Convenient location" | "Middle of nowhere" | +| A4.02 | Parking | Vehicle accommodation | "Easy free parking" | "Parking nightmare" | + +### Value (V) - Top Subcodes + +| Code | Name | Definition | + Example | - Example | +|------|------|------------|-----------|-----------| +| V1.01 | Absolute Price | The actual cost | "Very affordable" | "Outrageously expensive" | +| V1.04 | Hidden Costs | Unexpected charges | "No hidden fees" | "Surprise $50 charge" | +| V2.01 | Pricing Clarity | Understanding costs | "Clear price list" | "Impossible to understand" | +| V2.03 | Advertising Accuracy | Marketing matches reality | "As advertised" | "Bait and switch" | +| V2.04 | Terms Fairness | Policy reasonableness | "Fair cancellation" | "Predatory contract" | +| V4.01 | Overall Value | Total assessment | "Excellent value" | "Total rip-off" | +| V4.02 | Quality-Price Ratio | What you get for payment | "Great for the price" | "Pay more, get less" | + +### Relationship (R) - Top Subcodes + +| Code | Name | Definition | + Example | - Example | +|------|------|------------|-----------|-----------| +| R1.01 | Truthfulness | Accurate representations | "Everything as stated" | "They flat out lied" | +| R1.02 | Promise Keeping | Honoring commitments | "Always deliver on word" | "Never keep promises" | +| R1.04 | Ethics | Moral business conduct | "Ethical company" | "Shady business practices" | +| R2.02 | Consistency | Same experience over time | "Always great" | "Varies wildly" | +| R3.01 | Acknowledgment | Admitting failures | "Owned their mistake" | "Denied any wrongdoing" | +| R3.03 | Compensation | Making amends | "More than made up for it" | "Offered nothing" | +| R4.01 | Recognition | Acknowledging repeat customers | "They remember me" | "Stranger every time" | + +--- + +## 4. Metadata Cheat Sheet + +**7 dimensions, 24 total values**. Profile determines which are required. + +### 4.1 Valence (V) - ALWAYS REQUIRED + +| Code | Label | When to Use | Markers | +|------|-------|-------------|---------| +| **V+** | Positive | Praise, satisfaction | "great," "loved," "excellent" | +| **V-** | Negative | Complaint, dissatisfaction | "terrible," "hated," "worst" | +| **V0** | Neutral | Factual observation | "they have," "it was" | +| **V+-** | Mixed | Both positive and negative in same span | "good but," "despite," "however" | + +**Rule**: Prefer splitting over V+- unless the positive and negative target the *same thing*. + +### 4.2 Intensity (I) - ALWAYS REQUIRED + +| Code | Label | When to Use | Markers | +|------|-------|-------------|---------| +| **I1** | Mild | Slight preference/concern | "a bit," "somewhat," "could be better" | +| **I2** | Moderate | Clear but not extreme | Standard adjectives, no intensifiers | +| **I3** | Strong | Emphatic, intense | "extremely," "worst ever," CAPS, !!!, profanity | + +### 4.3 Specificity (S) - Standard+ + +| Code | Label | When to Use | Example | +|------|-------|-------------|---------| +| **S1** | Vague | General impression only | "Service was bad" | +| **S2** | Moderate | Some details or context | "Service was slow at dinner" | +| **S3** | Specific | Names, times, amounts | "Waiter John took 40 mins at 7pm Saturday" | + +### 4.4 Actionability (A) - Standard+ + +| Code | Label | When to Use | Example | +|------|-------|-------------|---------| +| **A1** | Low | Feeling, no clear action path | "I just didn't like it" | +| **A2** | Medium | Suggests improvement area | "Food could be warmer" | +| **A3** | High | Specific implementable fix | "West bathroom stall lock is broken" | + +**Note**: S and A are correlated but not identical. "John was rude" = S3 (named person) but A2 (action unclear). + +### 4.5 Temporal Reference (T) - Standard+ + +| Code | Label | When to Use | +|------|-------|-------------| +| **TC** | Current | This specific visit/experience (default) | +| **TR** | Recent | Recent pattern of experiences | +| **TH** | Historical | Long-standing pattern | +| **TF** | Future | Expectations or predictions | + +### 4.6 Evidence Type (E) - Standard+ + +| Code | Label | When to Use | Constraint | +|------|-------|-------------|------------| +| **ES** | Stated | Explicitly said by customer | Text directly says it (default) | +| **EI** | Inferred | Logically entailed by text | Must be directly deducible, not speculative | +| **EC** | Contextual | Requires surrounding text | Span uses "that," "they," "it" referencing earlier | + +**EI Rule**: Only use when text *logically entails* the inference. +- OK: "Took 3 weeks to reply" = EI for slow response time +- NOT OK: "Seemed tired" = Cannot infer fatigue without more evidence + +### 4.7 Comparative Reference (CR) - Standard+ + +| Code | Label | When to Use | Trigger Words | +|------|-------|-------------|---------------| +| **CR-N** | None | No comparison to past (DEFAULT - 90% of spans) | (no temporal language) | +| **CR-B** | Better | Explicit improvement | "better now," "improved," "finally fixed" | +| **CR-W** | Worse | Explicit decline | "worse now," "used to be good," "gone downhill" | +| **CR-S** | Same | Explicitly unchanged | "still," "as always," "same as before" | + +**CR Rules**: +1. Only assign CR-B/W/S when customer *explicitly compares* to their own past +2. CR-N is default -- only change when comparison is explicit +3. Self-comparison only (not competitor comparison) +4. Implicit decline counts: "used to be good" = CR-W + +### Metadata by Profile + +| Dimension | Lite | Core | Standard | Full | +|-----------|:----:|:----:|:--------:|:----:| +| Valence | Required | Required | Required | Required | +| Intensity | Optional | Required | Required | Required | +| Specificity | -- | -- | Required | Required | +| Actionability | -- | -- | Required | Required | +| Temporal | -- | Optional | Required | Required | +| Evidence | -- | -- | Required | Required | +| Comparative | -- | Optional | Required | Required | + +--- + +## 5. Common Mistakes to Avoid + +### Top 10 Disambiguation Pitfalls + +| # | Mistake | Correct Approach | +|---|---------|------------------| +| 1 | **Confusing O1.01 (Works/Doesn't Work) with J3.03 (System Uptime)** | O1.01 = product function. J3.03 = system/service availability. "Car won't start" = O1.01. "Website was down" = J3.03. | +| 2 | **Confusing P3.04 (Follow-Through) with R1.02 (Promise Keeping)** | P3.04 = specific interaction ("said they'd call back, didn't"). R1.02 = trust/pattern ("they never keep their word"). | +| 3 | **Confusing J2.01 (Simplicity) with E2.04 (Navigation)** | J2 = effort/friction in *process* ("too many steps"). E2 = qualities of *interface* ("buttons don't work"). | +| 4 | **Confusing J3.01 (Consistency) with O1.04 (Reliability)** | J3.01 = process delivers same result each time. O1.04 = product itself works consistently. "Pizza is always good" = J3.01. "Phone always connects" = O1.04. | +| 5 | **Confusing E2.03 (Interface Performance) with O1.02 (Product Performance)** | E2.03 = the app/interface is slow. O1.02 = the core product performs poorly ("car accelerates slowly"). | +| 6 | **Confusing A3.05 (Equal Treatment) with P1.02 (Respect)** | A3.05 = identity-based discrimination ("treated differently because of X"). P1.02 = general disrespect without identity framing. | +| 7 | **Confusing V2.xx with R1.xx** | V2 = pricing/terms/advertising specifically. R1 = trust/integrity/organizational character framing. | +| 8 | **Over-splitting cause-effect spans** | "Long wait because understaffed" = single span. Primary = J1.01, Secondary = A1.04. Only split if different sentences or genuinely different issues. | +| 9 | **Assigning CR-B/W/S without explicit comparison** | CR-N is default. "Service is slow" = CR-N. "Service is *still* slow" = CR-S. Must have explicit temporal language. | +| 10 | **Inventing causal codes** | Causal chain only when text explicitly states or logically entails. "Probably a training issue" = annotator speculation = NO causal code. | + +### Quick Disambiguation Tests + +| Question | If YES | If NO | +|----------|--------|-------| +| Does it mention the product/service itself? | Likely O | Check P-R | +| Does it name or describe a person? | Likely P | Check J-R | +| Does it mention time, steps, or waiting? | Likely J | Check E-R | +| Does it describe a place or interface? | Likely E | Check A-R | +| Does it mention accessibility or availability? | Likely A | Check V-R | +| Does it mention price, cost, or worth? | Likely V | Check R | +| Does it mention trust, patterns, or "always/never"? | Likely R | Re-read span | + +--- + +## 6. V vs R Rule: Scam vs Rip-off + +This is the most common confusion. Use this anchor: + +### The Rule + +| Feedback Type | Domain | Rationale | +|---------------|--------|-----------| +| **"This is a rip-off"** | **V4.01** | Complaint about the *exchange* (poor value) | +| **"This company is a scam"** | **R1.04** | Moral judgment about *intent* (they're dishonest) | + +### Criminal Metaphor Mapping + +| Word/Phrase | Domain | Reasoning | +|-------------|--------|-----------| +| "scam" | R1.04 | Character judgment | +| "fraud" | R1.04 | Character judgment | +| "crooks" | R1.04 | Character judgment | +| "rip-off" | V4.01 | Exchange complaint | +| "robbery" | V4.01 | Exchange complaint | +| "highway robbery" | V4.01 | Exchange complaint | +| "overpriced" | V1.01 or V4.02 | Price/value complaint | + +### Decision Heuristic + +**Ask**: Is the complaint about... +- **What I got vs. what I paid?** --> **V** (Value) +- **Their intent to deceive/harm me?** --> **R** (Relationship) + +### Examples + +| Span | Primary | Rationale | +|------|---------|-----------| +| "Total scam company" | R1.04 | Moral judgment about intent | +| "They charged me twice" | J3.02 | Process accuracy issue | +| "refused to refund" | R3.03 | Recovery/compensation failure | +| "This is robbery" | V4.01 | Exchange complaint | +| "They deliberately mislead people" | R1.01 | Organizational truthfulness | +| "Overpriced garbage" | V4.02 | Quality-price ratio | + +--- + +## 7. J4 vs R3 Rule: Process vs Ownership + +Both J4 and R3 deal with problems, but from different angles. + +### The Distinction + +| Domain | Focus | Key Question | +|--------|-------|--------------| +| **J4 (Resolution)** | *What they did* to fix it | How was the problem handled operationally? | +| **R3 (Recovery)** | *How they took responsibility* | Did they own it, apologize, make amends? | + +### Category-Level Comparison + +| J4 Category | R3 Category | Distinction | +|-------------|-------------|-------------| +| J4.01 Problem Acknowledgment | R3.01 Admitting Failures | J4.01 = recognized the issue exists. R3.01 = admitted wrongdoing/fault. | +| J4.02 Resolution Process | -- | J4.02 = the operational steps taken | +| J4.03 Resolution Speed | -- | J4.03 = how fast they fixed it | +| J4.04 Resolution Quality | R3.03 Compensation | J4.04 = was fix adequate? R3.03 = did they make amends beyond fixing? | +| J4.05 Prevention | R3.04 Improvement | J4.05 = process change. R3.04 = organizational commitment to change. | + +### Decision Heuristic + +**Ask**: Is the feedback about... +- **The mechanics of the fix?** --> **J4** (Journey: Resolution) +- **Their accountability and making things right?** --> **R3** (Relationship: Recovery) + +### Examples + +| Span | Primary | Rationale | +|------|---------|-----------| +| "They immediately sent a replacement" | J4.02 or R3.03 | If emphasizing speed/process = J4. If emphasizing making amends = R3. | +| "Took weeks to resolve" | J4.03 | Resolution speed | +| "They owned their mistake" | R3.01 | Admitting fault | +| "Sincere apology" | R3.02 | Expression of regret | +| "Offered nothing" | R3.03 | Compensation failure | +| "Changed their process" | J4.05 | Prevention action | +| "Blamed me instead" | R3.05 | Ownership failure | + +--- + +## 8. Span Boundary Rules + +### When to SPLIT + +1. **At contrasting conjunctions**: but, however, although, despite, yet +2. **When subject changes**: location -> service -> food +3. **When valence changes**: positive -> negative +4. **When domain changes**: different aspect of experience +5. **When in different sentences** (unless tightly linked cause-effect) + +### When to KEEP TOGETHER + +1. **Cause-effect in same clause**: "Long wait because understaffed" + - Primary = impact (J1.01 Wait Time) + - Secondary = cause (A1.04 Staffing) +2. **Same target, mixed assessment**: "Good but overpriced" (same product) +3. **Elaboration of same point**: "Service was slow. Had to wait 40 minutes." + +### Max Spans Guidance + +| Sentence Type | Typical Spans | +|---------------|---------------| +| Simple sentence | 1-2 spans | +| Complex sentence | 2-3 spans | +| If tempted to create 4+ | Re-read; probably over-splitting | + +### Cause-Effect Examples + +| Span | Treatment | Primary | Secondary | +|------|-----------|---------|-----------| +| "Long wait because understaffed" | Single | J1.01 | A1.04 | +| "Food cold, had to send it back" | Single | O2.05 | J4.02 | +| "App crashed so I lost my data" | Single | E2.02 | E4.03 | +| "Rude waiter. Also the food was cold." | TWO spans | P1.02 / O2.05 | -- | +| "Support was slow because the system kept crashing" | Single | J1.03 | J3.03 | + +### V+- vs Split Decision + +| Feedback | Action | +|----------|--------| +| "Great product, terrible onboarding" | SPLIT: two different targets | +| "Good but overpriced" | KEEP: same target, use V+- | +| "Nice staff despite the chaos" | SPLIT if chaos is separate feedback | + +**Test**: If the positive and negative parts have *different domain targets*, split them. + +--- + +## 9. Worked Examples + +### Example 1: Restaurant Review (Multiple Spans) + +> "The pasta was perfectly al dente and beautifully plated, but our waiter disappeared for 20 minutes and we had to flag down someone else to get the check. Good value for a nice dinner out." + +| Span | Primary | Secondary | V | I | S | A | T | E | CR | +|------|---------|-----------|---|---|---|---|---|---|-----| +| "pasta was perfectly al dente" | O1.02 | -- | V+ | I2 | S2 | A2 | TC | ES | CR-N | +| "beautifully plated" | O2.03 | -- | V+ | I2 | S2 | A2 | TC | ES | CR-N | +| "waiter disappeared for 20 minutes" | P3.03 | -- | V- | I2 | S3 | A3 | TC | ES | CR-N | +| "flag down someone else" | P3.01 | -- | V- | I2 | S2 | A2 | TC | ES | CR-N | +| "Good value for nice dinner" | V4.01 | -- | V+ | I1 | S1 | A1 | TC | ES | CR-N | + +### Example 2: Software with Improvement Signal (CR-B) + +> "Implementation took twice as long as promised, but once we went live, the system has been rock solid. Much more stable than the last version." + +| Span | Primary | Secondary | V | I | CR | Note | +|------|---------|-----------|---|---|-----|------| +| "Implementation took twice as long" | J1.02 | R1.02 | V- | I3 | CR-N | No self-comparison | +| "system has been rock solid" | O1.04 | -- | V+ | I3 | CR-N | Current state | +| "Much more stable than last version" | O1.04 | -- | V+ | I2 | **CR-B** | Explicit improvement | + +### Example 3: Persistent Problem (CR-S) + +> "Still waiting forever for appointments. Third time I've complained about this and nothing has changed." + +| Span | Primary | Secondary | V | I | CR | Note | +|------|---------|-----------|---|---|-----|------| +| "Still waiting forever" | A1.02 | J1.01 | V- | I3 | **CR-S** | "Still" = unchanged | +| "Third time I've complained" | J4.05 | R3.04 | V- | I2 | **CR-S** | Pattern, unchanged | + +**Causal Chain** (Full profile only): +- MG-O (Oversight failure) -- Evidence: EI +- Justification: "Third time" + "nothing changed" logically entails oversight failure + +### Example 4: Quality Decline (CR-W) + +> "This used to be my favorite restaurant but the quality has really gone downhill since they changed chefs." + +| Span | Primary | Secondary | V | I | CR | Note | +|------|---------|-----------|---|---|-----|------| +| "used to be my favorite" | R2.02 | -- | V- | I2 | **CR-W** | Past-positive implies decline | +| "quality has really gone downhill" | O2.02 | -- | V- | I3 | **CR-W** | Explicit decline | + +### Example 5: Service Recovery (CR-B) + +> "My package arrived damaged, which was frustrating. But they immediately sent a replacement and it arrived perfect. Great recovery!" + +| Span | Primary | Secondary | V | I | CR | +|------|---------|-----------|---|---|-----| +| "package arrived damaged" | O2.05 | -- | V- | I2 | CR-N | +| "immediately sent replacement" | R3.03 | J4.03 | V+ | I2 | CR-N | +| "arrived perfect" | O2.05 | -- | V+ | I2 | **CR-B** | +| "Great recovery" | R3 | -- | V+ | I2 | CR-N | + +### Example 6: Scam vs Rip-off (V vs R) + +> "Total scam company. They charged me twice and refused to refund. This is robbery." + +| Span | Primary | Secondary | V | I | CR | +|------|---------|-----------|---|---|-----| +| "Total scam company" | R1.04 | -- | V- | I3 | CR-N | +| "charged me twice" | J3.02 | -- | V- | I2 | CR-N | +| "refused to refund" | R3.03 | V2.04 | V- | I2 | CR-N | +| "This is robbery" | V4.01 | -- | V- | I3 | CR-N | + +### Example 7: Accessibility Issue + +> "No wheelchair ramp and the staff didn't seem to care." + +| Span | Primary | Secondary | V | I | S | A | T | E | CR | +|------|---------|-----------|---|---|---|---|---|---|-----| +| "No wheelchair ramp" | A2.01 | -- | V- | I2 | S3 | A3 | TC | ES | CR-N | +| "staff didn't seem to care" | P1.03 | -- | V- | I2 | S1 | A2 | TC | EI | CR-N | + +### Example 8: Digital Environment + +> "App is beautiful but crashes constantly. Finally works on mobile though!" + +| Span | Primary | Secondary | V | I | CR | +|------|---------|-----------|---|---|-----| +| "App is beautiful" | E2.01 | -- | V+ | I2 | CR-N | +| "crashes constantly" | E2.02 | -- | V- | I3 | CR-N | +| "Finally works on mobile" | E2.05 | -- | V+ | I2 | **CR-B** | + +### Example 9: Cause-Effect (Single Span) + +> "Support was painfully slow because their system kept going down." + +| Span | Primary | Secondary | V | I | Note | +|------|---------|-----------|---|---|------| +| Full span | J1.03 | J3.03 | V- | I3 | Impact (slow) + cause (system down) | + +### Example 10: Multi-Domain Complex Review + +> "Great location and the room was clean, but checkout took forever and they tried to charge me for a minibar I never touched. Classic hotel scam." + +| Span | Primary | Secondary | V | I | CR | Note | +|------|---------|-----------|---|---|-----|------| +| "Great location" | A4.01 | -- | V+ | I2 | CR-N | Convenience | +| "room was clean" | E1.01 | -- | V+ | I2 | CR-N | Physical space | +| "checkout took forever" | J1.01 | -- | V- | I3 | CR-N | Wait time | +| "tried to charge me for minibar I never touched" | V1.04 | J3.02 | V- | I2 | CR-N | Hidden cost + accuracy | +| "Classic hotel scam" | R1.04 | -- | V- | I3 | CR-N | Character judgment | + +--- + +## 10. USN Quick Reference + +URT String Notation for compact tagging. + +### Format + +``` +URT:{Profile}:{codes}:{Valence}{Intensity}[:{metadata}][:{causal}] +``` + +### Profiles + +| Code | Profile | Code Tier | +|------|---------|-----------| +| L | Lite | Domain (O, P, J...) | +| C | Core | Category (O1, P2...) | +| S | Standard | Subcode (O1.01, P2.03...) | +| F | Full | Subcode + Causal | + +### Quick Examples + +| Review | USN | +|--------|-----| +| "Food was cold" (Lite) | `URT:L:O:-2` | +| "Food was cold" (Core) | `URT:C:O2:-2` | +| "Food was cold, like last time" (Standard) | `URT:S:O2.05:-2:22TR.ES.S` | +| "Rude staff and unfair policy" (Standard) | `URT:S:P1.02+V2.04:-3:22TC.ES.N` | +| "Much better now!" (Standard) | `URT:S:V4.01:+2:11TC.ES.B` | + +### Metadata Encoding (Standard+) + +``` +{Specificity}{Actionability}{Temporal}.{Evidence}.{Comparative} + +Example: 22TC.ES.N + ^^ = S2, A2 + ^^ = TC (current) + ^^ = ES (stated) + ^ = CR-N (no comparison) +``` + +### Valence Symbols + +| Symbol | Meaning | +|--------|---------| +| + | Positive | +| - | Negative | +| 0 | Neutral | +| +- | Mixed | + +--- + +## Quick Checklist Before Submitting + +1. [ ] **One primary code per span** (no exceptions) +2. [ ] **Max 2 secondary codes** (prevents over-tagging) +3. [ ] **Checked "Don't Confuse With"** in spec for ambiguous codes +4. [ ] **Used decision tree** for domain selection +5. [ ] **Split at domain changes** (different aspects = different spans) +6. [ ] **CR-N unless explicit comparison** (default is no comparison) +7. [ ] **No invented causes** (causal chain only when text supports) +8. [ ] **Verified intensity markers** (I3 requires emphatic language) +9. [ ] **Cause-effect kept together** (impact = primary, cause = secondary) +10. [ ] **V vs R correctly applied** (exchange = V, character = R) + +--- + +## 11. Billing/Returns/Refunds Decision Table + +Special guidance for common billing and refund scenarios. + +| Feedback Type | Primary Code | Secondary | Rationale | +|---------------|--------------|-----------|-----------| +| "Returns process was easy" | J4.02 | -- | Resolution process ease | +| "Returns process was a nightmare" | J4.02 | -- | Resolution process friction | +| "Refund took too long" | J4.03 | -- | Resolution speed | +| "Refund policy is unfair" | V2.04 | -- | Terms fairness | +| "They refused to refund me" (trust framing) | R3.03 | V2.04 | Compensation failure + policy | +| "Wrong amount refunded" | J3.02 | V1.04 | Accuracy + hidden costs | +| "They honored the warranty" | R2.05 | -- | Guarantee honor | +| "Worthless guarantee" | R2.05 | -- | Guarantee failure | +| "Charged me twice" | J3.02 | -- | Process accuracy | +| "Hidden fees at checkout" | V1.04 | V2.02 | Hidden costs + fee disclosure | + +--- + +## 12. Data Privacy/Security Decision Table + +| Feedback Type | Primary Code | Secondary | Rationale | +|---------------|--------------|-----------|-----------| +| "Security incident occurred" | E4.03 | -- | Security breach | +| "I don't trust them with my data" | R1.03 or R1.04 | E4.03 | Trust + security | +| "Data breach notification" | E4.03 | R1.03 | Security + transparency | +| "Privacy policy concerns" | V2.04 | R1.04 | Terms + ethics | +| "Account was hacked" | E4.03 | -- | Security failure | +| "They sell my data" | R1.04 | V2.04 | Ethics + terms | + +--- + +## 13. CR Trigger Word Reference + +Quick lookup for Comparative Reference assignment. + +### CR-B (Better) - Improvement Signals + +| Trigger Phrase | Example | +|----------------|---------| +| "better now" | "Service is much better now" | +| "improved" | "Quality has improved" | +| "finally fixed" | "They finally fixed the app!" | +| "much faster/cleaner/friendlier than before" | "Much faster than my last visit" | +| "they've turned it around" | "They've really turned things around" | +| "glad they addressed it" | "Glad they addressed the issue" | +| "not like last time" (positive context) | "Not like last time - actually worked!" | + +### CR-W (Worse) - Decline Signals + +| Trigger Phrase | Example | +|----------------|---------| +| "worse now" | "Quality is worse now" | +| "used to be good" | "This used to be my favorite restaurant" | +| "has gone downhill" | "Really gone downhill lately" | +| "not what it used to be" | "Just not what it used to be" | +| "declining" | "Quality is declining" | +| "deteriorating" | "Service has been deteriorating" | +| "they've really fallen off" | "They've really fallen off" | +| "was great before" | "Was great before the renovation" | +| "no longer what it was" | "No longer the place I loved" | + +### CR-S (Same) - Persistence Signals + +| Trigger Phrase | Example | +|----------------|---------| +| "still" | "Service is still slow" | +| "as always" | "Great as always" | +| "same as before" | "Same problems as before" | +| "nothing has changed" | "Complained twice, nothing has changed" | +| "yet again" | "Wrong order yet again" | +| "once again" | "Once again disappointed" | +| "as usual" | "Late as usual" | +| "same old" | "Same old problems" | + +### CR-N (None) - No Comparison + +- Default for ~90% of spans +- First-time customer reviews +- Competitor comparisons ("better than Brand X") +- No temporal language present + +--- + +## 14. Causal Chain Quick Guide (Full Profile Only) + +Only assign causal codes when text **explicitly states** or **logically entails** the cause. When in doubt, omit. + +### Conditions Layer (CD-) + +| Code | Name | When to Use | Example Text | +|------|------|-------------|--------------| +| CD-S | Staff State | Fatigue, training, motivation stated | "Server seemed exhausted" | +| CD-T | Team Dynamics | Handoffs, coordination issues stated | "They kept passing me around" | +| CD-E | Equipment | Malfunction stated | "The machine was broken" | +| CD-F | Facility | Maintenance, capacity stated | "Place was falling apart" | +| CD-O | Operational | Understaffing, demand surge stated | "Clearly understaffed" | + +### Management Layer (MG-) + +| Code | Name | When to Use | Example Text | +|------|------|-------------|--------------| +| MG-P | Planning | Scheduling, forecasting failure stated | "No one scheduled for weekend" | +| MG-T | Training | Training gap stated | "Clearly not trained properly" | +| MG-O | Oversight | Supervision failure inferable | "Third time reporting this" (EI) | +| MG-R | Resources | Resource allocation stated | "No supplies available" | +| MG-C | Communication | Policy relay failure stated | "Staff didn't know the policy" | + +### Systemic Layer (SY-) + +| Code | Name | When to Use | Example Text | +|------|------|-------------|--------------| +| SY-R | Resource Decisions | Budget, investment stated | "Cheap owners" | +| SY-P | Policy/Procedure | Bureaucracy, rules stated | "Company policy is the problem" | +| SY-C | Culture | Values, priorities stated | "Management doesn't care" | +| SY-S | Standards | Quality thresholds stated | "They've lowered their standards" | +| SY-H | Human Capital | Compensation, hiring stated | "Can't keep good employees" | +| SY-X | External | Market, regulatory stated | "Ever since COVID" | + +### Causal Chain Validity Test + +| Review Text | Causal Code? | Valid? | Why | +|-------------|--------------|--------|-----| +| "Long wait because they were short-staffed" | CD-O | Yes | Explicitly stated | +| "The machine was broken" | CD-E | Yes | Explicitly stated | +| "Fifth time I've reported this" | MG-O | Yes | Logically entailed (EI) | +| "They seem understaffed" | -- | No | "Seem" = speculation | +| "Probably a training issue" | -- | No | Annotator speculation | +| "Management doesn't care" (stated by customer) | SY-C | Yes | Customer explicitly states | + +--- + +## 15. Inter-Annotator Agreement Rules + +### Mandatory Conventions + +1. **One primary code per span** - no exceptions +2. **Max 2 secondary codes** - prevents over-tagging +3. **Max 3 spans per sentence** - if more, reconsider boundaries +4. **Prefer splitting over V+-** - unless truly inseparable +5. **Check "Don't Confuse With"** - before finalizing subcode +6. **Evidence type required** - must justify EI inferences +7. **No invented causes** - causal_chain only when text supports +8. **CR-N is default** - only use CR-B/W/S when comparison is explicit + +### Tie-Break Rules + +When unsure between two codes: + +| Disagreement Type | Resolution | +|-------------------|------------| +| Different domains | Use decision tree; first "YES" wins | +| Same category, different subcodes | Prefer more specific subcode | +| Different intensity | Defer to linguistic markers (see I3 markers) | +| Different actionability | A3 requires specific implementable action | +| Different CR | CR-N unless explicit temporal language present | + +### Calibration Check Questions + +Before submitting, ask yourself: + +1. Would another annotator choose the same primary domain? +2. Is the secondary code genuinely distinct (different category)? +3. Is intensity justified by linguistic markers? +4. Is CR assignment supported by explicit comparison language? +5. Would I assign causal codes if I didn't know the industry? + +--- + +## Where to Find More + +| Document | Purpose | +|----------|---------| +| **URT-Specification-v5.1.md** | Full specification with all 140 subcodes | +| **URT Issue Lifecycle Framework** | Analytics layer for resolution tracking | +| **URT QA Protocol** | Calibration and audit procedures | + +--- + +## Appendix: Profile Requirements Summary + +### URT-Lite (Micro-business, quick triage) + +``` +Required: primary_code (domain), valence +Optional: intensity +Forbidden: secondary_codes, subcodes, S/A/E/CR/causal +``` + +### URT-Core (Small business, dashboards) + +``` +Required: primary_code (category), valence, intensity +Optional: secondary_codes (max 2, categories only), temporal, comparative +Forbidden: subcodes, S/A/E, causal +``` + +### URT-Standard (Operations, routing, analytics) + +``` +Required: primary_code (subcode), valence, intensity, specificity, + actionability, temporal, evidence, comparative +Optional: secondary_codes (max 2, subcodes only), causal_chain, confidence +Forbidden: domains, categories as primary +``` + +### URT-Full (Enterprise, root cause, audit) + +``` +Required: All Standard fields + causal_chain (when evidence supports), + linked_spans, confidence, annotator_notes +Optional: None - all fields should be completed +Forbidden: domains, categories as primary +``` + +--- + +*URT v5.1 Annotator Quickstart Guide | Track A: Training Materials* diff --git a/urt-taxonomy/track-a-training/A2-QA-Protocol.md b/urt-taxonomy/track-a-training/A2-QA-Protocol.md new file mode 100644 index 0000000..7d84a44 --- /dev/null +++ b/urt-taxonomy/track-a-training/A2-QA-Protocol.md @@ -0,0 +1,476 @@ +# A2: QA Protocol +## Universal Review Taxonomy (URT) v5.1 + +**Purpose**: Define quality assurance processes for URT annotation +**Version**: 5.1 | **Status**: Production Ready | **Date**: 2026-01-23 + +--- + +## Table of Contents + +1. [Inter-Annotator Agreement (IAA) Metrics](#1-inter-annotator-agreement-iaa-metrics) +2. [Calibration Sessions](#2-calibration-sessions) +3. [Error Categories and Severity](#3-error-categories-and-severity) +4. [Audit Procedures](#4-audit-procedures) +5. [Gold Standard Management](#5-gold-standard-management) +6. [Quality Gates](#6-quality-gates) +7. [Feedback Loop](#7-feedback-loop) +8. [Metrics Dashboard](#8-metrics-dashboard) + +--- + +## 1. Inter-Annotator Agreement (IAA) Metrics + +### 1.1 Cohen's Kappa Thresholds by Code Tier + +| Code Tier | Minimum Kappa | Target Kappa | +|-----------|---------------|--------------| +| **Domain (Tier 1)** | 0.80 | 0.90+ | +| **Category (Tier 2)** | 0.75 | 0.85+ | +| **Subcode (Tier 3)** | 0.70 | 0.80+ | +| **Valence** | 0.85 | 0.92+ | +| **Intensity** | 0.70 | 0.80+ | +| **Comparative Reference** | 0.75 | 0.85+ | + +### 1.2 Krippendorff's Alpha (3+ Annotators) + +| Scenario | Minimum Alpha | Target Alpha | +|----------|---------------|--------------| +| Initial Training | 0.67 | 0.75+ | +| Production Quality | 0.75 | 0.85+ | +| Gold Standard Creation | 0.85 | 0.90+ | + +### 1.3 Agreement Interpretation Scale + +| Range | Interpretation | Action | +|-------|----------------|--------| +| **0.90 - 1.00** | Almost Perfect | Maintain standards | +| **0.80 - 0.89** | Excellent | Minor calibration | +| **0.70 - 0.79** | Good | Schedule calibration | +| **0.60 - 0.69** | Moderate | Mandatory retraining | +| **< 0.60** | Poor | Suspend, reassess | + +### 1.4 Profile-Specific Requirements + +| Profile | Domain | Category | Subcode | Overall Target | +|---------|--------|----------|---------|----------------| +| URT-Lite | >= 0.85 | N/A | N/A | >= 0.85 | +| URT-Core | >= 0.85 | >= 0.80 | N/A | >= 0.80 | +| URT-Standard/Full | >= 0.85 | >= 0.80 | >= 0.75 | >= 0.78 | + +--- + +## 2. Calibration Sessions + +### 2.1 Session Frequency + +| Team Size | Daily | Weekly | Monthly | +|-----------|-------|--------|---------| +| 1-3 annotators | -- | 30min | 2hr | +| 4-10 annotators | 15min | 1hr | 3hr | +| 11+ annotators | 15min | 2x 1hr | 4hr | + +### 2.2 Weekly Session Structure (60 min) + +| Time | Activity | +|------|----------| +| 0-5 min | Review IAA metrics from past week | +| 5-15 min | Discuss 3 highest-disagreement spans | +| 15-35 min | Group annotation exercise (5 spans) | +| 35-50 min | Compare results, discuss differences | +| 50-60 min | Document decisions, update guidance | + +### 2.3 Materials Checklist + +- [ ] 5-10 pre-selected review spans +- [ ] IAA metrics report +- [ ] Top disagreement patterns list +- [ ] Gold standard examples +- [ ] A1 Quickstart Guide +- [ ] Session notes template + +### 2.4 Outcome Documentation + +``` +## Calibration Session: [DATE] + +### Disagreement Patterns +1. Pattern: [Description] + Resolution: [Decision] + +### Exercise Results +| Span | Consensus | Votes | Notes | +|------|-----------|-------|-------| + +### Action Items +- [ ] Update A1 Section X +- [ ] Add gold standard example +``` + +--- + +## 3. Error Categories and Severity + +### 3.1 Error Severity Matrix + +| Severity | Weight | Description | +|----------|--------|-------------| +| **Critical** | 1.0 | Fundamentally wrong | +| **Major** | 0.5 | Significant deviation | +| **Minor** | 0.25 | Suboptimal but defensible | +| **Slip** | 0.1 | Typo/formatting | + +### 3.2 Critical Errors (Weight: 1.0) + +| Error Type | Example | +|------------|---------| +| Wrong Domain | "Rude waiter" coded as O instead of P | +| Wrong Valence | Complaint coded as V+ | +| Valence Omission | No valence assigned | +| Profile Violation | Subcode in URT-Lite | + +### 3.3 Major Errors (Weight: 0.5) + +| Error Type | Example | +|------------|---------| +| Wrong Category | J1 (Timing) vs J4 (Resolution) | +| Intensity Off by 2 | "TERRIBLE!!!" coded as I1 | +| Wrong CR Direction | "Gone downhill" coded as CR-B | +| Missed/Over Split | Two issues merged OR single split | +| J4/R3 Confusion | Process vs Ownership | +| V/R Confusion | "Total scam" coded as V4.01 | + +### 3.4 Minor Errors (Weight: 0.25) + +| Error Type | Example | +|------------|---------| +| Wrong Subcode (Same Category) | P1.01 vs P1.02 within P1 | +| Intensity Off by 1 | "pretty good" as I1 vs I2 | +| Borderline Secondary | Questionable secondary code | + +### 3.5 Slips (Weight: 0.1) + +Typos, formatting errors, boundary off by <5 chars + +### 3.6 Error Severity Decision Tree + +``` +Is DOMAIN wrong? --> YES: CRITICAL +Is VALENCE wrong/missing? --> YES: CRITICAL +Is CATEGORY wrong? --> YES: MAJOR +Is INTENSITY off by 2? --> YES: MAJOR +Is SUBCODE wrong? --> YES: MINOR +Is it formatting/typo? --> YES: SLIP +``` + +### 3.7 Accuracy Calculation + +``` +Error Score = Sum(error_weight * count) / total_spans +Accuracy = 100% - Error Score + +Thresholds: + > 95% = Excellent 85-90% = Acceptable + 90-95% = Good < 85% = Below Standard +``` + +--- + +## 4. Audit Procedures + +### 4.1 Sampling Methodology + +**Random**: Equal probability selection for general monitoring +**Stratified**: Ensure representation across domains, annotators, edge cases + +| Stratum | Minimum Sample | +|---------|----------------| +| Each Domain (O-R) | 5% of total | +| Each Annotator | 10% of output | +| High-Intensity (I3) | 15% of I3 spans | +| Non-default CR | 25% of CR-B/W/S | + +### 4.2 Sample Size by Volume + +| Daily Volume | Audit Rate | +|--------------|------------| +| < 100 spans | 30% | +| 100-500 | 20% | +| 500-2000 | 15% | +| 2000-10000 | 10% | +| > 10000 | 7% | + +### 4.3 Audit Frequency + +| Type | Frequency | Owner | +|------|-----------|-------| +| Spot Check | Daily | QA Lead | +| Sample Audit | Weekly | QA Team | +| Full Audit | Monthly | Senior QA | +| External | Quarterly | External | + +### 4.4 Audit Workflow + +``` +[Daily Output] --> [Sample] --> [Blind Re-code] + | + v +[Compare] --> Match: [Log] + | + +--> Mismatch: [Classify Error] --> [Route] --> [Aggregate] +``` + +### 4.5 Escalation Paths + +| Error Score | Level | Action | +|-------------|-------|--------| +| < 10% | 1 | Self-correction | +| 10-15% | 2 | QA Lead review | +| 15-20% | 3 | Team calibration | +| > 20% | 4 | Management escalation | + +--- + +## 5. Gold Standard Management + +### 5.1 Corpus Requirements + +| Metric | Minimum | Target | +|--------|---------|--------| +| Total Spans | 500 | 1000+ | +| Per Domain | 50 | 100+ | +| Per Category | 10 | 25+ | +| Edge Cases | 100 | 200+ | + +### 5.2 Creation Process + +``` +[Candidate] --> [3+ Annotators Classify] --> [Calculate Alpha] + | + Alpha >= 0.85: [Add to Gold] + Alpha < 0.85: [Discuss/Reject] +``` + +### 5.3 Gold Standard Documentation + +```json +{ + "gold_id": "GS-2026-001", + "span_text": "The waiter was incredibly rude", + "classification": { + "primary_code": "P1.02", + "valence": "V-", + "intensity": "I3" + }, + "rationale": "Clear disrespect. 'Incredibly' indicates I3.", + "common_mistakes": ["P1.01 (Warmth)"], + "agreement_score": 0.92, + "version": "5.1", + "status": "active" +} +``` + +### 5.4 Version Control + +| Change Type | Version Bump | +|-------------|--------------| +| Add example | Patch (5.1.1) | +| Fix error | Patch | +| Spec alignment | Minor (5.2) | +| Taxonomy change | Major (6.0) | + +### 5.5 Retirement Criteria + +- Spec change invalidates example +- Systematic confusion traced to example +- Industry shifts make obsolete + +--- + +## 6. Quality Gates + +### 6.1 New Annotator Qualification + +``` +Week 1: Training (A1 Guide, Spec, Videos) +Week 2: Supervised Practice (100 spans, daily feedback) +Week 3: Qualification Exam (50 gold spans, blind) + | + Pass (>= 85%): Production + 30-day probation + Fail: Remediation + retake +``` + +**Passing Criteria**: +- Overall Accuracy >= 85% +- Domain Accuracy >= 90% +- Critical Errors = 0 +- Major Errors <= 3 + +### 6.2 Production Annotator Requirements + +| Requirement | Frequency | Threshold | +|-------------|-----------|-----------| +| Accuracy Check | Weekly | >= 90% | +| Calibration | Weekly | 90% attendance | +| Gold Quiz | Monthly | >= 85% | +| IAA with Peers | Bi-weekly | Kappa >= 0.75 | + +### 6.3 Annotator Tiers + +| Tier | Accuracy | Audit Rate | +|------|----------|------------| +| Expert | >= 95% | 5% | +| Senior | 92-95% | 10% | +| Standard | 88-92% | 15% | +| Developing | 85-88% | 25% | +| Probation | < 85% | 50% | + +### 6.4 Automated System Thresholds + +| Metric | Minimum | Production | Best | +|--------|---------|------------|------| +| Domain Accuracy | 85% | 90% | 95% | +| Category Accuracy | 80% | 85% | 90% | +| Subcode Accuracy | 75% | 80% | 85% | +| Valence F1 | 0.88 | 0.92 | 0.96 | + +### 6.5 Release Criteria + +- [ ] All accuracy metrics meet thresholds +- [ ] Gold standard test documented +- [ ] Error analysis completed +- [ ] Rollback plan in place +- [ ] Stakeholder sign-off + +--- + +## 7. Feedback Loop + +### 7.1 Error Reporting + +``` +ERROR REPORT FIELDS: +- Reporter, Date, Span ID +- Type: [Spec Unclear | Gold Issue | Edge Case | Tool Bug] +- Description +- Suggested Resolution +- Urgency: [Critical | High | Medium | Low] +``` + +### 7.2 Triage Process + +``` +[Error Submitted] --> [QA Lead (24hr)] + | + +--> Spec Issue --> PM + +--> Gold Issue --> QA Team + +--> Tool Bug --> Engineering + +--> Training Gap --> QA Lead +``` + +### 7.3 Spec Clarification Process + +``` +[Ambiguity] --> Check A1 Guide --> Found: Apply + | + Not Found: Submit Request + | + PM + QA Review + | + Accept: Update A1/Spec + Reject: Document Rationale +``` + +### 7.4 Training Update Triggers + +| Trigger | Action | Timeline | +|---------|--------|----------| +| IAA < 0.75 | Mandatory calibration | 48 hours | +| New error pattern (3+) | Targeted training | 1 week | +| Spec release | Full training | 2 weeks | +| Annotator < 85% | Individual coaching | Immediate | + +### 7.5 Response SLAs + +| Urgency | Response | Resolution | +|---------|----------|------------| +| Critical | 2 hours | 24 hours | +| High | 24 hours | 1 week | +| Medium | 48 hours | 2 weeks | +| Low | 1 week | Next sprint | + +--- + +## 8. Metrics Dashboard + +### 8.1 Key QA KPIs + +| KPI | Target | Alert | +|-----|--------|-------| +| Overall Accuracy | >= 92% | < 88% | +| IAA (Kappa) | >= 0.80 | < 0.75 | +| Critical Error Rate | < 2/1K | >= 5/1K | +| Audit Coverage | >= 10% | < 7% | +| Calibration Attendance | >= 90% | < 80% | +| Error Resolution Time | < 5 days | > 10 days | + +### 8.2 Reporting Frequency + +| Report | Frequency | Audience | +|--------|-----------|----------| +| Daily Snapshot | Daily | QA Lead | +| Weekly Summary | Weekly | Team + Management | +| Monthly Deep Dive | Monthly | Leadership | +| Quarterly Review | Quarterly | Executives | + +### 8.3 Alert Configuration + +``` + Green Yellow Red +Accuracy >= 92% 88-92% < 88% +IAA >= 0.80 0.75-0.80 < 0.75 +Critical Err < 2/1K 2-5/1K > 5/1K +Coverage >= 12% 10-12% < 10% + +Yellow: Notify QA Lead +Red: Escalate + Immediate Action +``` + +### 8.4 Dashboard Panels + +1. **Accuracy Trend**: Line chart, 30-day rolling +2. **IAA Heatmap**: Annotator pairwise Kappa +3. **Error Distribution**: Stacked bar by severity +4. **Domain Performance**: Radar chart (O-P-J-E-A-V-R) +5. **Annotator Leaderboard**: Table with tiers +6. **Alert Status**: Traffic light indicators + +### 8.5 Metric Formulas + +``` +Accuracy = 1 - (Sum(error_weight * count) / total_spans) + +Cohen's Kappa = (Po - Pe) / (1 - Pe) + Po = Observed agreement + Pe = Expected agreement by chance + +Krippendorff's Alpha = 1 - (Do / De) + Do = Observed disagreement + De = Expected disagreement + +F1 = 2 * (Precision * Recall) / (Precision + Recall) +``` + +--- + +## Document References + +| Document | Location | +|----------|----------| +| URT-Specification-v5.1.md | `/urt-taxonomy/spec/` | +| A1-Annotator-Quickstart.md | `/urt-taxonomy/track-a-training/` | +| Gold Standard Corpus | `/urt-taxonomy/gold-standard/` | + +--- + +*URT v5.1 QA Protocol | Track A: Training Materials* diff --git a/urt-taxonomy/track-a-training/A3-Calibration-Test-Set.md b/urt-taxonomy/track-a-training/A3-Calibration-Test-Set.md new file mode 100644 index 0000000..94bcbe8 --- /dev/null +++ b/urt-taxonomy/track-a-training/A3-Calibration-Test-Set.md @@ -0,0 +1,1925 @@ +# A3: Calibration Test Set +## Universal Review Taxonomy (URT) v5.1 - Gold Standard Annotation Corpus + +**Purpose**: Gold standard examples for annotator training, certification, and ongoing calibration +**Version**: 5.1 | **Status**: Production Ready | **Date**: 2026-01-23 + +--- + +## Table of Contents + +1. [Overview](#1-overview) +2. [Test Set Structure](#2-test-set-structure) +3. [Calibration Examples by Domain](#3-calibration-examples-by-domain) + - [3.1 Offering (O) Domain](#31-offering-o-domain) + - [3.2 People (P) Domain](#32-people-p-domain) + - [3.3 Journey (J) Domain](#33-journey-j-domain) + - [3.4 Environment (E) Domain](#34-environment-e-domain) + - [3.5 Access (A) Domain](#35-access-a-domain) + - [3.6 Value (V) Domain](#36-value-v-domain) + - [3.7 Relationship (R) Domain](#37-relationship-r-domain) +4. [Confusion Pair Examples](#4-confusion-pair-examples) +5. [Multi-Code Span Examples](#5-multi-code-span-examples) +6. [Edge Cases and Boundary Conditions](#6-edge-cases-and-boundary-conditions) +7. [Certification Test Structure](#7-certification-test-structure) +8. [Scoring Rubric](#8-scoring-rubric) +9. [Pass/Fail Criteria](#9-passfail-criteria) + +--- + +## 1. Overview + +### 1.1 Purpose + +This document serves as the **gold standard annotation corpus** for URT v5.1. It provides: + +- **Training material** for new annotators to learn correct classification +- **Certification tests** to verify annotator competency at each profile level +- **Calibration benchmarks** for ongoing quality assurance +- **Reference examples** for resolving disagreements + +### 1.2 Gold Standard Creation Process + +All examples in this corpus have been validated through: + +1. **Triple-blind annotation** by 3+ certified expert annotators +2. **Krippendorff's Alpha >= 0.90** agreement threshold +3. **Expert panel review** for disputed cases +4. **Documentation of rationale** for all decisions + +### 1.3 Usage Guidelines + +| Use Case | Process | +|----------|---------| +| New annotator training | Work through examples in order, domain by domain | +| Certification testing | Select items by profile level (see Section 7) | +| Calibration sessions | Use confusion pairs and edge cases | +| Dispute resolution | Reference rationale for analogous cases | + +### 1.4 Corpus Statistics + +| Metric | Count | +|--------|-------| +| Total Examples | 62 | +| Examples per Domain | 8-10 | +| Confusion Pair Examples | 12 | +| Multi-Code Examples | 8 | +| Edge Cases | 10 | +| Difficulty: Easy | 20 | +| Difficulty: Medium | 22 | +| Difficulty: Hard | 14 | +| Difficulty: Expert | 6 | + +--- + +## 2. Test Set Structure + +### 2.1 Difficulty Levels + +| Level | Description | Target Annotators | Typical Agreement | +|-------|-------------|-------------------|-------------------| +| **Easy** | Clear single-domain, obvious valence/intensity | Entry-level | >= 0.95 Kappa | +| **Medium** | Standard cases requiring decision tree application | Standard | >= 0.85 Kappa | +| **Hard** | Confusion pairs, multi-code, subtle distinctions | Advanced | >= 0.75 Kappa | +| **Expert** | Edge cases, causal chains, complex metadata | Expert | >= 0.70 Kappa | + +### 2.2 Example Format + +Each example includes: + +``` +ID: [Domain]-[Difficulty]-[Number] +Difficulty: Easy | Medium | Hard | Expert +Review Text: "[Realistic Google review style text]" + +GOLD STANDARD CLASSIFICATION: +- Span: [Exact text boundaries] +- Primary Code: [Domain] > [Category] > [Subcode] ([Code]) +- Secondary Codes: [If applicable] +- Valence: [V+/V-/V0/V+-] +- Intensity: [I1/I2/I3] +- Specificity: [S1/S2/S3] (Standard+) +- Actionability: [A1/A2/A3] (Standard+) +- Temporal: [TC/TR/TH/TF] (Standard+) +- Evidence: [ES/EI/EC] (Standard+) +- Comparative: [CR-N/CR-B/CR-W/CR-S] (Standard+) +- Causal Chain: [If applicable, Full profile only] + +RATIONALE: +[Detailed explanation of why this code and not alternatives] + +COMMON MISTAKES: +- [Mistake 1]: [Why it's wrong] +- [Mistake 2]: [Why it's wrong] +``` + +### 2.3 Profile Requirements by Example + +| Profile | Required Fields | Example Sections to Complete | +|---------|-----------------|------------------------------| +| Lite | Primary (domain), Valence | Domain, V only | +| Core | Primary (category), Valence, Intensity | Category, V, I | +| Standard | All metadata except causal | Full minus causal | +| Full | All fields including causal when supported | Complete | + +--- + +## 3. Calibration Examples by Domain + +### 3.1 Offering (O) Domain + +#### O-EASY-01: Basic Product Function +**Difficulty**: Easy + +**Review Text**: "My new phone arrived and it won't even turn on. Completely dead out of the box." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "it won't even turn on. Completely dead out of the box" +- **Primary Code**: Offering > Function > Works/Doesn't Work (O1.01) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S2 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: This is a clear product functionality failure. The product does not perform its basic function (turning on). "Completely dead" and "won't even" indicate strong intensity (I3). Actionable because it requires replacement/repair (A3). + +**COMMON MISTAKES**: +- Coding as E2.02 (Digital Functionality): Wrong because this is about the physical product, not an app/interface +- Coding as O2.05 (Condition at Delivery): While delivery-related, the core complaint is function, not cosmetic condition + +--- + +#### O-EASY-02: Product Quality Praise +**Difficulty**: Easy + +**Review Text**: "The steak was perfectly cooked, medium-rare exactly as I ordered. The meat was so tender it practically melted." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The steak was perfectly cooked, medium-rare exactly as I ordered" +- **Primary Code**: Offering > Quality > Craftsmanship (O2.02) +- **Secondary Codes**: O4.01 (Specification Match) +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: "Perfectly cooked" addresses how well the dish was executed (craftsmanship). Secondary code O4.01 captures "exactly as I ordered" (specification match). Specific (S3) due to exact doneness mentioned. + +**COMMON MISTAKES**: +- Coding as O2.01 (Materials/Inputs): "Tender meat" might suggest quality ingredients, but "perfectly cooked" emphasizes execution/skill +- Missing secondary code O4.01: "Exactly as I ordered" is a distinct point about specification match + +--- + +#### O-MEDIUM-01: Product Durability Issue +**Difficulty**: Medium + +**Review Text**: "I loved this jacket for the first month, but after just two washes the zipper broke and seams started coming apart." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "after just two washes the zipper broke and seams started coming apart" +- **Primary Code**: Offering > Function > Durability (O1.03) +- **Secondary Codes**: O2.02 (Craftsmanship) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TR +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Primary complaint is durability ("after just two washes"). The zipper and seams failing are symptoms of poor durability. Secondary O2.02 captures the craftsmanship defect. Temporal is TR (recent pattern) because it tracks degradation over time. + +**COMMON MISTAKES**: +- Coding as O2.01 (Materials): Materials may be the root cause, but the customer's complaint is about how long it lasted (durability) +- Coding Temporal as TC: This spans multiple wash cycles, indicating a recent pattern (TR) + +--- + +#### O-MEDIUM-02: Outcome Achievement +**Difficulty**: Medium + +**Review Text**: "I hired them to fix my back pain and after 6 sessions I'm still in agony. Complete waste of time and money." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I hired them to fix my back pain and after 6 sessions I'm still in agony" +- **Primary Code**: Offering > Function > Outcome Achievement (O1.05) +- **Secondary Codes**: V4.01 (Overall Value) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TR +- **Evidence**: ES +- **Comparative**: CR-S + +**RATIONALE**: Customer's goal (pain relief) was not achieved. "Still in agony" after 6 sessions indicates the treatment didn't work. CR-S because "still" indicates the condition is unchanged. Secondary V4.01 captures "waste of time and money." + +**COMMON MISTAKES**: +- Coding as P2.02 (Technical Skill): While practitioner skill may be the cause, the customer is complaining about the outcome, not observing the technique +- Missing CR-S: "Still in agony" is an explicit persistence signal + +--- + +#### O-HARD-01: Specification Match vs Accuracy +**Difficulty**: Hard + +**Review Text**: "I ordered the blue model size medium and received a red one in large. Not even close to what I wanted." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I ordered the blue model size medium and received a red one in large" +- **Primary Code**: Offering > Fit > Specification Match (O4.01) +- **Secondary Codes**: J3.02 (Accuracy) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Primary is O4.01 because the customer is emphasizing the product doesn't match their specification/needs. Secondary J3.02 captures the process error that caused this. The distinction: O4.01 = "wrong product for me"; J3.02 = "they made a mistake in fulfillment." + +**COMMON MISTAKES**: +- Coding only as J3.02 (Accuracy): J3.02 alone misses that the customer's need wasn't met. Primary should be O4.01 (the product impact) +- Confusing with O3.01 (All Components Present): Nothing is missing; it's the wrong item entirely + +--- + +#### O-HARD-02: Quality vs Environment Aesthetics +**Difficulty**: Hard + +**Review Text**: "The sushi presentation was amateur hour. Fish slapped on rice with no artistry whatsoever." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The sushi presentation was amateur hour. Fish slapped on rice with no artistry" +- **Primary Code**: Offering > Quality > Presentation (O2.03) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: This is about the product's (sushi) visual/aesthetic quality, not the restaurant's ambiance. O2.03 covers how the product itself looks. "Amateur hour" and the vivid description indicate I3 intensity. + +**COMMON MISTAKES**: +- Coding as E3.05 (Aesthetics): E3.05 is for space/environment aesthetics, not product presentation +- Coding as O2.02 (Craftsmanship): While related, "presentation" is the specific subcode for visual/aesthetic quality of the product + +--- + +#### O-EXPERT-01: Feature Availability vs Inventory +**Difficulty**: Expert + +**Review Text**: "The app advertises real-time translation but that feature has been 'coming soon' for 8 months now." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The app advertises real-time translation but that feature has been 'coming soon' for 8 months now" +- **Primary Code**: Offering > Completeness > Feature Availability (O3.02) +- **Secondary Codes**: V2.03 (Advertising Accuracy) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TH +- **Evidence**: ES +- **Comparative**: CR-S + +**RATIONALE**: O3.02 captures that a promised feature isn't available. This differs from A1.03 (inventory) which is about physical stock. Secondary V2.03 addresses the misleading advertising. TH (historical) because 8 months is a long-standing pattern. CR-S because it's persistently unavailable. + +**COMMON MISTAKES**: +- Coding as A1.03 (Inventory/Capacity): A1.03 is for physical availability ("sold out"), not software features +- Coding as E2.02 (Digital Functionality): The feature doesn't exist yet; it's not broken +- Coding as R1.01 (Truthfulness): While deceptive, the primary focus is on the missing feature; advertising is secondary + +--- + +### 3.2 People (P) Domain + +#### P-EASY-01: Staff Warmth +**Difficulty**: Easy + +**Review Text**: "Sarah at the front desk was so friendly and welcoming. She made us feel right at home from the moment we walked in." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Sarah at the front desk was so friendly and welcoming. She made us feel right at home" +- **Primary Code**: People > Attitude > Warmth/Friendliness (P1.01) +- **Secondary Codes**: None +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Classic example of staff warmth/friendliness. Named employee (S3). "So friendly and welcoming" is clear praise without extreme intensifiers (I2). + +**COMMON MISTAKES**: +- Coding as R4.03 (Relationship Building): R4.03 is about ongoing relationship investment, not single-visit warmth +- Over-rating intensity to I3: "So friendly" is moderate; I3 would require "absolutely amazing" or similar + +--- + +#### P-EASY-02: Staff Rudeness +**Difficulty**: Easy + +**Review Text**: "The cashier rolled her eyes when I asked a question and said 'I already told you' in the most condescending tone." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The cashier rolled her eyes when I asked a question and said 'I already told you' in the most condescending tone" +- **Primary Code**: People > Attitude > Respect (P1.02) +- **Secondary Codes**: P4.05 (Tone) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Eye-rolling and condescension are disrespect indicators (P1.02). Secondary P4.05 captures the communication tone specifically. Not I3 because language is descriptive but not extreme. + +**COMMON MISTAKES**: +- Coding as P4.01 (Clarity): The issue isn't unclear communication; it's disrespectful delivery +- Coding as P1.03 (Empathy): While related, the specific behavior (eye-rolling, condescension) indicates disrespect + +--- + +#### P-MEDIUM-01: Staff Competence vs Problem-Solving +**Difficulty**: Medium + +**Review Text**: "I asked the tech about compatibility issues and he had no idea what I was talking about. Had to Google it myself." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I asked the tech about compatibility issues and he had no idea what I was talking about" +- **Primary Code**: People > Competence > Knowledge (P2.01) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: This is about knowledge gap (P2.01), not problem-solving ability (P2.03). The tech didn't lack the ability to solve a problem; they lacked the knowledge to even understand the question. + +**COMMON MISTAKES**: +- Coding as P2.03 (Problem-Solving): P2.03 is for ability to find solutions; this is about not knowing basic information +- Coding as O3.04 (Documentation): The customer needed staff knowledge, not documentation + +--- + +#### P-MEDIUM-02: Responsiveness - Follow-Through +**Difficulty**: Medium + +**Review Text**: "The manager promised to call me back within 24 hours to resolve the issue. It's been a week and nothing." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The manager promised to call me back within 24 hours to resolve the issue. It's been a week and nothing" +- **Primary Code**: People > Responsiveness > Follow-Through (P3.04) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TR +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: P3.04 (Follow-Through) is correct because this is a specific instance of failing to complete a promised action. Specific timeline mentioned (S3). Temporal is TR because it spans a week. + +**COMMON MISTAKES**: +- Coding as R1.02 (Promise Keeping): Use R1.02 for trust/pattern framing ("they never keep promises"). P3.04 is for specific interaction follow-through +- Coding as J1.03 (Response Time): While timing is mentioned, the core issue is the broken promise, not response speed + +--- + +#### P-HARD-01: Empathy vs Listening +**Difficulty**: Hard + +**Review Text**: "I explained my situation three times but the rep just kept reading from the script. It's like she didn't hear a word I said." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I explained my situation three times but the rep just kept reading from the script" +- **Primary Code**: People > Communication > Listening (P4.02) +- **Secondary Codes**: P1.03 (Empathy) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Primary is P4.02 (Listening) because "didn't hear a word" and "kept reading from script" indicate failure to process what was said. Secondary P1.03 captures the implied lack of empathy. The distinction: P4.02 = cognitive processing of input; P1.03 = emotional understanding. + +**COMMON MISTAKES**: +- Coding as P1.03 primary: The explicit complaint is about not listening (P4.02); empathy is implied but secondary +- Adding P2.03 (Problem-Solving): The complaint isn't that they couldn't solve it; it's that they didn't listen + +--- + +#### P-HARD-02: Professionalism vs Respect +**Difficulty**: Hard + +**Review Text**: "The technician showed up in dirty clothes, was on his personal phone the whole time, and tracked mud through my house." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The technician showed up in dirty clothes, was on his personal phone the whole time, and tracked mud through my house" +- **Primary Code**: People > Competence > Professionalism (P2.04) +- **Secondary Codes**: P1.02 (Respect) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: P2.04 (Professionalism) covers conduct/standards violations (dirty clothes, personal phone). Secondary P1.02 captures the disrespect shown to the customer's home (tracked mud). Multiple specific failures = I3. + +**COMMON MISTAKES**: +- Coding as E1.01 (Cleanliness): E1.01 is about the business's space, not a technician's appearance or behavior +- Coding P1.02 as primary: The behaviors described are professional conduct violations; disrespect is a consequence + +--- + +### 3.3 Journey (J) Domain + +#### J-EASY-01: Wait Time +**Difficulty**: Easy + +**Review Text**: "Had an appointment at 2pm and wasn't seen until 3:15. Over an hour wait with no explanation or apology." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Had an appointment at 2pm and wasn't seen until 3:15. Over an hour wait" +- **Primary Code**: Journey > Timing > Wait Time (J1.01) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Clear wait time complaint with specific times (2pm, 3:15). Over an hour indicates I3 severity. Note: "no explanation or apology" could be a separate span (P4.03 or R3.02). + +**COMMON MISTAKES**: +- Coding as A1.02 (Booking Access): A1.02 is about ability to schedule; J1.01 is about wait time once there +- Combining "no apology" in same span: This should be split as it's a separate complaint about recovery + +--- + +#### J-EASY-02: Process Simplicity +**Difficulty**: Easy + +**Review Text**: "Returning the item was surprisingly easy. Just scanned the QR code, dropped it off, and got my refund in 2 days." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Returning the item was surprisingly easy. Just scanned the QR code, dropped it off, and got my refund in 2 days" +- **Primary Code**: Journey > Ease > Simplicity (J2.01) +- **Secondary Codes**: J4.03 (Resolution Speed) +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: "Surprisingly easy" and the simple process description indicate J2.01. Secondary J4.03 captures the fast resolution (2 days). S3 because specific steps and timeline mentioned. + +**COMMON MISTAKES**: +- Coding as J4.02 (Resolution Process): J4.02 is for problem handling; this is a standard return, not a problem resolution +- Missing secondary code: The 2-day refund speed is a distinct positive point + +--- + +#### J-MEDIUM-01: Process Accuracy +**Difficulty**: Medium + +**Review Text**: "They delivered the wrong prescription to the wrong address. Could have been dangerous." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "They delivered the wrong prescription to the wrong address" +- **Primary Code**: Journey > Reliability > Accuracy (J3.02) +- **Secondary Codes**: E4.01 (Physical Safety) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S2 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: J3.02 (Accuracy) covers incorrect execution of requests. Two errors (wrong prescription + wrong address) compound to I3. Secondary E4.01 captures the safety concern ("could have been dangerous"). + +**COMMON MISTAKES**: +- Coding as O4.01 (Specification Match): O4.01 is about product-customer fit; J3.02 is about execution error +- Coding as E4.03 (Security): This is safety (E4.01), not security/property protection + +--- + +#### J-MEDIUM-02: Resolution Process +**Difficulty**: Medium + +**Review Text**: "When I reported the problem, I was transferred to 4 different departments and had to explain everything from scratch each time." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I was transferred to 4 different departments and had to explain everything from scratch each time" +- **Primary Code**: Journey > Resolution > Resolution Process (J4.02) +- **Secondary Codes**: J2.04 (Handoffs) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: J4.02 covers how problems are handled - this describes a dysfunctional resolution process. Secondary J2.04 captures the handoff failures specifically. "4 different departments" = S3 and I3. + +**COMMON MISTAKES**: +- Coding as P4.03 (Proactive Updates): P4.03 is about keeping customer informed, not transfer issues +- Coding as J2.04 alone: The primary complaint is the overall resolution process, not just handoffs + +--- + +#### J-HARD-01: Resolution Speed vs Service Speed +**Difficulty**: Hard + +**Review Text**: "After my complaint, it took them 3 weeks to finally send a replacement. The original delivery only took 2 days!" + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "After my complaint, it took them 3 weeks to finally send a replacement" +- **Primary Code**: Journey > Resolution > Resolution Speed (J4.03) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-W + +**RATIONALE**: J4.03 (Resolution Speed) not J1.02 (Service Speed) because this is fixing a problem, not initial delivery. CR-W because the implicit comparison shows decline (original was fast, resolution was slow). + +**COMMON MISTAKES**: +- Coding as J1.02 (Service Speed): J1.02 is for normal service delivery; J4.03 is specifically for problem resolution timing +- Missing CR-W: The comparison to "original delivery only took 2 days" is an implicit decline signal + +--- + +#### J-HARD-02: System Availability vs Product Function +**Difficulty**: Hard + +**Review Text**: "The banking app was down for maintenance during tax weekend when I desperately needed to transfer funds." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The banking app was down for maintenance during tax weekend when I desperately needed to transfer funds" +- **Primary Code**: Journey > Reliability > Availability (J3.03) +- **Secondary Codes**: A1.01 (Operating Hours) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: J3.03 (System Availability/Uptime) not O1.01 because the app works; it was just unavailable. Secondary A1.01 captures the timing issue (inaccessible when needed). "Desperately needed" = I3. + +**COMMON MISTAKES**: +- Coding as O1.01 (Works/Doesn't Work): The app functions; it was just down for maintenance +- Coding as E2.02 (Digital Functionality): E2.02 is for broken features, not scheduled downtime + +--- + +### 3.4 Environment (E) Domain + +#### E-EASY-01: Physical Cleanliness +**Difficulty**: Easy + +**Review Text**: "The bathroom was disgusting. Toilet unflushed, paper towels on the floor, and the mirror was covered in water spots." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The bathroom was disgusting. Toilet unflushed, paper towels on the floor, and the mirror was covered in water spots" +- **Primary Code**: Environment > Physical Space > Cleanliness (E1.01) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Clear cleanliness issue with specific examples. "Disgusting" indicates I3. Multiple specific problems (S3) that are directly actionable (A3). + +**COMMON MISTAKES**: +- Coding as E4.02 (Health/Hygiene): E4.02 is for sanitation protocols; E1.01 is for general cleanliness +- Splitting into multiple spans: These are all part of one cleanliness complaint + +--- + +#### E-EASY-02: Digital Interface Design +**Difficulty**: Easy + +**Review Text**: "The new website design is beautiful. Clean layout, modern fonts, and the color scheme is perfect." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The new website design is beautiful. Clean layout, modern fonts, and the color scheme is perfect" +- **Primary Code**: Environment > Digital Space > Interface Design (E2.01) +- **Secondary Codes**: None +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A1 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-B + +**RATIONALE**: E2.01 covers visual/interaction quality of digital interfaces. "New website design" signals CR-B (improvement from before). A1 because praise doesn't suggest specific action. + +**COMMON MISTAKES**: +- Coding as O2.03 (Product Presentation): O2.03 is for product aesthetics; E2.01 is for interface design +- Missing CR-B: "New website design" implies improvement from previous version + +--- + +#### E-MEDIUM-01: Interface Navigation +**Difficulty**: Medium + +**Review Text**: "I spent 20 minutes trying to find the cancellation option. It was buried 5 menus deep with no search function." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I spent 20 minutes trying to find the cancellation option. It was buried 5 menus deep" +- **Primary Code**: Environment > Digital Space > Navigation (E2.04) +- **Secondary Codes**: J2.01 (Simplicity) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: E2.04 (Interface Navigation) because it's about finding things in the digital interface specifically. Secondary J2.01 captures the process friction this caused. "20 minutes" and "5 menus deep" = S3, I3. + +**COMMON MISTAKES**: +- Coding as J2.01 primary: J2.01 is process simplicity; E2.04 is specifically about interface navigation +- Coding as V2.04 (Terms Fairness): Hiding cancellation could be policy issue, but the complaint is about navigation + +--- + +#### E-MEDIUM-02: Atmosphere/Vibe +**Difficulty**: Medium + +**Review Text**: "The restaurant had such a cozy atmosphere. Soft lighting, gentle music, perfect for a date night." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The restaurant had such a cozy atmosphere. Soft lighting, gentle music, perfect for a date night" +- **Primary Code**: Environment > Ambiance > Atmosphere/Vibe (E3.01) +- **Secondary Codes**: None +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A1 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: E3.01 captures overall mood/atmosphere. Lighting and music are components of atmosphere. This differs from E3.02 (noise specifically) or E3.05 (aesthetics/beauty). + +**COMMON MISTAKES**: +- Coding as E3.05 (Aesthetics): E3.05 is visual beauty; E3.01 is overall vibe/mood +- Splitting lighting and music: These work together to create the atmosphere + +--- + +#### E-HARD-01: Safety vs Cleanliness +**Difficulty**: Hard + +**Review Text**: "The kitchen staff weren't wearing gloves and I saw the cook sneeze directly over the food prep area." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The kitchen staff weren't wearing gloves and I saw the cook sneeze directly over the food prep area" +- **Primary Code**: Environment > Safety > Health/Hygiene (E4.02) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: E4.02 (Health/Hygiene) covers sanitation protocols and food safety, not just surface cleanliness. Specific witnessed violations (S3), highly actionable (A3), severe concern (I3). + +**COMMON MISTAKES**: +- Coding as E1.01 (Cleanliness): E1.01 is general tidiness; E4.02 is health/sanitation protocols +- Coding as P2.04 (Professionalism): While unprofessional, the primary concern is health/safety + +--- + +#### E-HARD-02: Mobile Experience vs Digital Accessibility +**Difficulty**: Hard + +**Review Text**: "The mobile site is completely unusable. Buttons are tiny, text overlaps, and I can't even see the checkout button on my screen." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The mobile site is completely unusable. Buttons are tiny, text overlaps, and I can't even see the checkout button" +- **Primary Code**: Environment > Digital Space > Mobile Experience (E2.05) +- **Secondary Codes**: E2.01 (Interface Design) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: E2.05 (Mobile Experience) is for smartphone optimization issues. This is not A2.05 (Digital Accessibility) which is about assistive technology support. Secondary E2.01 captures the design failures. + +**COMMON MISTAKES**: +- Coding as A2.05 (Digital Accessibility): A2.05 is for screen readers, assistive tech; E2.05 is for mobile optimization +- Coding as E2.02 (Functionality): The features work; they're just poorly optimized for mobile + +--- + +### 3.5 Access (A) Domain + +#### A-EASY-01: Operating Hours +**Difficulty**: Easy + +**Review Text**: "Love that they're open until midnight. Perfect for late-night cravings!" + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Love that they're open until midnight. Perfect for late-night cravings" +- **Primary Code**: Access > Availability > Operating Hours (A1.01) +- **Secondary Codes**: None +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A1 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Clear operating hours praise. A1.01, not P3.03 (staff availability) which is about whether staff are present when you need them. + +**COMMON MISTAKES**: +- Coding as P3.03 (Staff Availability): P3.03 is about staff being present; A1.01 is about business hours +- Coding as A4.01 (Location): Location is where; hours are when + +--- + +#### A-EASY-02: Physical Accessibility +**Difficulty**: Easy + +**Review Text**: "As a wheelchair user, I was so happy to see they have a ramp, automatic doors, and an accessible bathroom." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "they have a ramp, automatic doors, and an accessible bathroom" +- **Primary Code**: Access > Accessibility > Physical Accessibility (A2.01) +- **Secondary Codes**: None +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: A2.01 covers mobility accommodations. Multiple specific features mentioned (S3). Distinct from E4.01 (physical safety) which is about protection from harm. + +**COMMON MISTAKES**: +- Coding as E4.01 (Physical Safety): E4.01 is about danger/harm; A2.01 is about disability accommodation +- Coding as E1.03 (Layout/Design): While related to design, accessibility is a distinct concern + +--- + +#### A-MEDIUM-01: Language Support +**Difficulty**: Medium + +**Review Text**: "Nobody spoke Spanish and there were no signs or menus in Spanish. Felt completely lost." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Nobody spoke Spanish and there were no signs or menus in Spanish" +- **Primary Code**: Access > Inclusivity > Language Support (A3.01) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: A3.01 covers language accessibility. This is not P2.01 (staff knowledge) because the issue isn't staff competence but language support as an inclusion matter. + +**COMMON MISTAKES**: +- Coding as P2.01 (Knowledge): P2.01 is about product knowledge; A3.01 is about language inclusion +- Coding as E1.05 (Signage): While signs are mentioned, the core issue is language access + +--- + +#### A-MEDIUM-02: Equal Treatment / Discrimination +**Difficulty**: Medium + +**Review Text**: "The staff was super helpful to other customers but completely ignored me. I'm pretty sure it's because of how I was dressed." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The staff was super helpful to other customers but completely ignored me. I'm pretty sure it's because of how I was dressed" +- **Primary Code**: Access > Inclusivity > Equal Treatment (A3.05) +- **Secondary Codes**: P3.01 (Attentiveness) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: EI +- **Comparative**: CR-N + +**RATIONALE**: A3.05 (Equal Treatment) because customer perceives identity-based discrimination ("because of how I was dressed"). Secondary P3.01 captures the service failure. Evidence is EI because discrimination is inferred. + +**COMMON MISTAKES**: +- Coding as P1.02 (Respect): Use P1.02 for general disrespect; A3.05 when identity-based discrimination is perceived +- Coding as P3.03 (Availability): Staff were available, just selectively helpful + +--- + +#### A-HARD-01: Booking Access vs Wait Time +**Difficulty**: Hard + +**Review Text**: "I tried to book an appointment for two months and the earliest they had was in December. That's a 4-month wait just to get an appointment!" + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I tried to book an appointment for two months and the earliest they had was in December. That's a 4-month wait just to get an appointment" +- **Primary Code**: Access > Availability > Booking Access (A1.02) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TR +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: A1.02 (Booking Access) is about ability to schedule, distinct from J1.01 (Wait Time) which is waiting once you arrive. "4-month wait just to get an appointment" = scheduling access, not day-of wait. + +**COMMON MISTAKES**: +- Coding as J1.01 (Wait Time): J1.01 is waiting at the appointment; A1.02 is getting the appointment in the first place +- Coding as A1.03 (Inventory/Capacity): While capacity may be the cause, the complaint is about booking access + +--- + +#### A-HARD-02: Digital Accessibility vs Mobile Experience +**Difficulty**: Hard + +**Review Text**: "My screen reader can't interpret any of the buttons on their website. It's completely inaccessible for blind users like me." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "My screen reader can't interpret any of the buttons on their website. It's completely inaccessible for blind users like me" +- **Primary Code**: Access > Accessibility > Digital Accessibility (A2.05) +- **Secondary Codes**: A2.02 (Visual Accessibility) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S2 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: A2.05 (Digital Accessibility) covers assistive technology support like screen readers. Secondary A2.02 captures the visual accessibility dimension. This is NOT E2.05 (Mobile Experience) which is about smartphone optimization. + +**COMMON MISTAKES**: +- Coding as E2.05 (Mobile Experience): E2.05 is for mobile optimization; A2.05 is for assistive technology +- Coding as E2.02 (Digital Functionality): The site may function; it's just not accessible + +--- + +### 3.6 Value (V) Domain + +#### V-EASY-01: Absolute Price +**Difficulty**: Easy + +**Review Text**: "Prices are insanely high. $25 for a basic salad is just ridiculous." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "$25 for a basic salad is just ridiculous" +- **Primary Code**: Value > Price > Absolute Price (V1.01) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: V1.01 is the absolute cost itself. "Insanely high" and "ridiculous" indicate I3. Specific price mentioned (S3). This is not V4.02 (quality-price ratio) because quality isn't mentioned. + +**COMMON MISTAKES**: +- Coding as V4.02 (Quality-Price Ratio): V4.02 requires quality discussion; this is pure price complaint +- Coding as V1.03 (Price vs Market): No competitor comparison made + +--- + +#### V-EASY-02: Hidden Costs +**Difficulty**: Easy + +**Review Text**: "At checkout they added a $15 'service fee' that wasn't mentioned anywhere. Total bait and switch." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "At checkout they added a $15 'service fee' that wasn't mentioned anywhere" +- **Primary Code**: Value > Price > Hidden Costs (V1.04) +- **Secondary Codes**: V2.02 (Fee Disclosure) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S3 +- **Actionability**: A3 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: V1.04 (Hidden Costs) is the unexpected charge itself. Secondary V2.02 captures the disclosure failure. Note: "bait and switch" could be separate span coded V2.03. + +**COMMON MISTAKES**: +- Coding as V2.02 primary: V1.04 is the charge itself; V2.02 is the disclosure failure +- Coding as R1.04 (Ethics): While unethical, the explicit complaint is about the hidden fee + +--- + +#### V-MEDIUM-01: Quality-Price Ratio +**Difficulty**: Medium + +**Review Text**: "For what we paid, the food was disappointing. You can get much better quality at half the price elsewhere." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "For what we paid, the food was disappointing" +- **Primary Code**: Value > Worth > Quality-Price Ratio (V4.02) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S1 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: V4.02 specifically addresses what you get for what you pay. "For what we paid" directly frames quality relative to cost. Vague (S1) because no specifics on what was disappointing. + +**COMMON MISTAKES**: +- Coding as O2 (Quality): The quality alone isn't the complaint; it's quality relative to price +- Coding as V1.03 (Price vs Market): While competitors mentioned, primary framing is quality-price ratio + +--- + +#### V-MEDIUM-02: Terms Fairness +**Difficulty**: Medium + +**Review Text**: "Their cancellation policy is criminal. Cancel more than 24 hours out and you still lose 50% of your payment." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Their cancellation policy is criminal. Cancel more than 24 hours out and you still lose 50% of your payment" +- **Primary Code**: Value > Transparency > Terms Fairness (V2.04) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: V2.04 covers policy/contract reasonableness. "Criminal" indicates I3. Specific terms described (S3). This is NOT R1.05 (Fair Dealing) which is about equitable treatment patterns. + +**COMMON MISTAKES**: +- Coding as R1.05 (Fair Dealing): R1.05 is relationship/trust framing; V2.04 is specifically about policy terms +- Coding as R1.04 (Ethics): While "criminal" is strong, the complaint is about policy, not organizational ethics + +--- + +#### V-HARD-01: Overall Value (Rip-off) +**Difficulty**: Hard + +**Review Text**: "Absolute rip-off. Paid $500 for what turned out to be a 30-minute consultation with zero actionable advice." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Absolute rip-off. Paid $500 for what turned out to be a 30-minute consultation with zero actionable advice" +- **Primary Code**: Value > Worth > Overall Value (V4.01) +- **Secondary Codes**: O1.05 (Outcome Achievement) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: V4.01 (Overall Value) for "rip-off" - this is an exchange complaint (poor value), not a character judgment (scam). Secondary O1.05 captures "zero actionable advice" (outcome failure). + +**COMMON MISTAKES**: +- Coding as R1.04 (Ethics/Scam): "Rip-off" = exchange complaint (V4.01); "scam" would be R1.04 +- Missing O1.05 secondary: "Zero actionable advice" is a distinct outcome achievement failure + +--- + +#### V-HARD-02: Advertising Accuracy vs Truthfulness +**Difficulty**: Hard + +**Review Text**: "The photos show a huge suite but the actual room was barely bigger than a closet. False advertising!" + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "The photos show a huge suite but the actual room was barely bigger than a closet. False advertising" +- **Primary Code**: Value > Transparency > Advertising Accuracy (V2.03) +- **Secondary Codes**: O4.01 (Specification Match) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: V2.03 (Advertising Accuracy) is about marketing matching reality. This is NOT R1.01 (Truthfulness) which is about trust/integrity/character. Secondary O4.01 captures product mismatch. + +**COMMON MISTAKES**: +- Coding as R1.01 (Truthfulness): R1.01 is for trust/integrity framing; V2.03 is specifically about advertising +- Coding as V2.05 (Honest Representation): V2.03 is more specific to advertising; V2.05 is broader claims + +--- + +### 3.7 Relationship (R) Domain + +#### R-EASY-01: Truthfulness +**Difficulty**: Easy + +**Review Text**: "They flat out lied to me about the warranty coverage. When I tried to claim, suddenly all these exclusions appeared." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "They flat out lied to me about the warranty coverage" +- **Primary Code**: Relationship > Integrity > Truthfulness (R1.01) +- **Secondary Codes**: R2.05 (Guarantee Honor) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: R1.01 for explicit lying accusation. Secondary R2.05 captures the warranty failure. "Flat out lied" indicates I3 and clear R domain (trust/integrity framing). + +**COMMON MISTAKES**: +- Coding as V2.04 (Terms Fairness): While terms are involved, the explicit complaint is about lying +- Coding as V2.02 (Fee Disclosure): The warranty exclusions aren't fees; it's about truthfulness + +--- + +#### R-EASY-02: Track Record +**Difficulty**: Easy + +**Review Text**: "I've been a customer for 10 years and they have never once let me down. Truly dependable." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "I've been a customer for 10 years and they have never once let me down. Truly dependable" +- **Primary Code**: Relationship > Dependability > Track Record (R2.01) +- **Secondary Codes**: None +- **Valence**: V+ +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A1 +- **Temporal**: TH +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: R2.01 covers historical performance. "10 years" and "never once" establish a track record. TH (historical) because of the long timeframe. + +**COMMON MISTAKES**: +- Coding as R2.02 (Consistency): R2.02 is "same experience each time"; R2.01 is overall track record +- Coding Temporal as TC: "10 years" clearly indicates historical (TH), not current visit + +--- + +#### R-MEDIUM-01: Recovery - Acknowledgment +**Difficulty**: Medium + +**Review Text**: "When I pointed out the error, the manager immediately admitted their mistake and took full responsibility. Refreshing honesty." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "the manager immediately admitted their mistake and took full responsibility" +- **Primary Code**: Relationship > Recovery > Acknowledgment (R3.01) +- **Secondary Codes**: R3.05 (Ownership) +- **Valence**: V+ +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: R3.01 (Acknowledgment) for admitting failures. Secondary R3.05 (Ownership) for "took full responsibility." This is NOT J4.01 (Problem Acknowledgment) which is recognizing the issue exists, not admitting fault. + +**COMMON MISTAKES**: +- Coding as J4.01 (Problem Acknowledgment): J4.01 = "yes, there's a problem"; R3.01 = "yes, we were wrong" +- Missing R3.05: "Took full responsibility" is a distinct ownership signal + +--- + +#### R-MEDIUM-02: Compensation +**Difficulty**: Medium + +**Review Text**: "After the terrible experience, they refunded my money AND gave me a $100 credit. They really went above and beyond." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "they refunded my money AND gave me a $100 credit" +- **Primary Code**: Relationship > Recovery > Compensation (R3.03) +- **Secondary Codes**: None +- **Valence**: V+ +- **Intensity**: I3 +- **Specificity**: S3 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: R3.03 (Compensation) covers making amends beyond fixing the issue. "Above and beyond" with specific dollar amount = I3, S3. This is NOT J4.04 (Resolution Quality) which is whether the fix worked. + +**COMMON MISTAKES**: +- Coding as J4.04 (Resolution Quality): J4.04 = was it fixed? R3.03 = did they make amends? +- Coding as V4.01 (Overall Value): This is about recovery relationship, not value assessment + +--- + +#### R-HARD-01: Ethics (Scam) +**Difficulty**: Hard + +**Review Text**: "This company is a complete scam. They're con artists who prey on elderly people with fake urgency tactics." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "This company is a complete scam. They're con artists who prey on elderly people with fake urgency tactics" +- **Primary Code**: Relationship > Integrity > Ethics (R1.04) +- **Secondary Codes**: A3.05 (Equal Treatment) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TH +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: R1.04 (Ethics) for "scam," "con artists" - these are moral judgments about organizational character/intent. Secondary A3.05 captures targeting vulnerable group. TH because implies ongoing pattern. + +**COMMON MISTAKES**: +- Coding as V4.01 (Overall Value): "Scam" is character judgment (R1.04), not exchange complaint +- Coding as V2.03 (Advertising Accuracy): While deceptive, "scam" goes beyond advertising to ethics + +--- + +#### R-HARD-02: Recovery vs Resolution (J4 vs R3) +**Difficulty**: Hard + +**Review Text**: "Yes, they eventually fixed the problem, but they never apologized or acknowledged they caused it in the first place." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "they never apologized or acknowledged they caused it in the first place" +- **Primary Code**: Relationship > Recovery > Apology (R3.02) +- **Secondary Codes**: R3.01 (Acknowledgment) +- **Valence**: V- +- **Intensity**: I2 +- **Specificity**: S2 +- **Actionability**: A2 +- **Temporal**: TC +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: Primary R3.02 (Apology) for missing expression of regret. Secondary R3.01 (Acknowledgment) for not admitting fault. Note: "they eventually fixed the problem" could be separate span (J4.04, V+). + +**COMMON MISTAKES**: +- Coding as J4.01 (Problem Acknowledgment): J4.01 is recognizing the problem; R3.01 is admitting they caused it +- Including the fix in same span: The fix and the apology failure are distinct feedback points + +--- + +#### R-EXPERT-01: Promise Keeping vs Follow-Through +**Difficulty**: Expert + +**Review Text**: "They promise the world to get your business but never deliver. Every single commitment they make turns out to be empty words." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "They promise the world to get your business but never deliver. Every single commitment they make turns out to be empty words" +- **Primary Code**: Relationship > Integrity > Promise Keeping (R1.02) +- **Secondary Codes**: R2.04 (Trustworthiness) +- **Valence**: V- +- **Intensity**: I3 +- **Specificity**: S1 +- **Actionability**: A1 +- **Temporal**: TH +- **Evidence**: ES +- **Comparative**: CR-N + +**RATIONALE**: R1.02 (Promise Keeping) not P3.04 (Follow-Through) because this is framed as trust/pattern ("Every single commitment," "never deliver") not a specific interaction. TH for ongoing pattern. + +**COMMON MISTAKES**: +- Coding as P3.04 (Follow-Through): P3.04 is specific interaction ("said they'd call, didn't"). R1.02 is pattern of broken promises +- Coding Temporal as TC: "Every single commitment" indicates historical pattern (TH) + +--- + +## 4. Confusion Pair Examples + +These examples target the most common disambiguation challenges identified in the A1 Quickstart Guide. + +### 4.1 V vs R: Scam vs Rip-off + +#### CP-VR-01: Exchange Complaint (V) +**Difficulty**: Hard + +**Review Text**: "Total rip-off! I paid premium prices for bargain basement quality. Won't get fooled again." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: V4.01 (Overall Value) +- **Valence**: V- | **Intensity**: I3 | **CR**: CR-N + +**RATIONALE**: "Rip-off" is an exchange complaint - the focus is on poor value for money paid. This is V4.01, NOT R1.04. The test: Is the complaint about what I got vs. what I paid? (V) Or is it about their intent to deceive? (R) + +--- + +#### CP-VR-02: Character Judgment (R) +**Difficulty**: Hard + +**Review Text**: "This business is nothing but a scam operation. They deliberately mislead customers and have no intention of delivering what they promise." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: R1.04 (Ethics) +- **Secondary Codes**: R1.01 (Truthfulness) +- **Valence**: V- | **Intensity**: I3 | **CR**: CR-N + +**RATIONALE**: "Scam," "deliberately mislead," "no intention" - these are moral judgments about organizational character and intent. This is R1.04, NOT V4.01. The test: Is this about their intent to deceive/harm? (R) + +--- + +### 4.2 J4 vs R3: Process vs Ownership + +#### CP-JR-01: Resolution Process (J4) +**Difficulty**: Hard + +**Review Text**: "When my order arrived wrong, they processed the return quickly and sent a replacement within 2 days." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: J4.02 (Resolution Process) +- **Secondary Codes**: J4.03 (Resolution Speed) +- **Valence**: V+ | **Intensity**: I2 | **CR**: CR-N + +**RATIONALE**: Focus is on *what they did* to fix it (process, speed). No mention of apology, ownership, or making amends beyond the fix. This is J4, NOT R3. + +--- + +#### CP-JR-02: Recovery Ownership (R3) +**Difficulty**: Hard + +**Review Text**: "When my order arrived wrong, they sincerely apologized, admitted it was their fault, and gave me a credit for my next order as a gesture of goodwill." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: R3.02 (Apology) +- **Secondary Codes**: R3.01 (Acknowledgment), R3.03 (Compensation) +- **Valence**: V+ | **Intensity**: I2 | **CR**: CR-N + +**RATIONALE**: Focus is on *how they took responsibility* - apology, admission, and goodwill gesture. This is R3, NOT J4. The test: Is this about the mechanics of fixing it (J4) or about accountability and making amends (R3)? + +--- + +### 4.3 P2 vs P3: Competence vs Responsiveness + +#### CP-PP-01: Competence - Problem-Solving (P2.03) +**Difficulty**: Medium + +**Review Text**: "The tech couldn't figure out what was wrong with my computer. Tried three different things but had no idea what they were doing." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: P2.03 (Problem-Solving) +- **Valence**: V- | **Intensity**: I2 | **CR**: CR-N + +**RATIONALE**: "Couldn't figure out," "had no idea" - this is about *ability* to solve, not willingness or attentiveness. This is P2.03 (skill to address issues). + +--- + +#### CP-PP-02: Responsiveness - Follow-Through (P3.04) +**Difficulty**: Medium + +**Review Text**: "The tech promised to get back to me with a solution within 24 hours but never called. Had to follow up myself three times." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: P3.04 (Follow-Through) +- **Valence**: V- | **Intensity**: I2 | **CR**: CR-N + +**RATIONALE**: "Promised to get back," "never called," "follow up myself" - this is about completing promised actions, not technical ability. This is P3.04 (follow-through on commitments). + +--- + +### 4.4 O1.01 vs J3.03: Product Function vs System Uptime + +#### CP-OJ-01: Product Function (O1.01) +**Difficulty**: Medium + +**Review Text**: "My new smartwatch won't sync with my phone no matter what I try. The Bluetooth connection just doesn't work." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: O1.01 (Works/Doesn't Work) +- **Valence**: V- | **Intensity**: I2 | **CR**: CR-N + +**RATIONALE**: The product itself doesn't function. The watch's Bluetooth is broken. This is O1.01 (basic functionality), NOT J3.03. + +--- + +#### CP-OJ-02: System Uptime (J3.03) +**Difficulty**: Medium + +**Review Text**: "The app kept timing out all weekend. Their servers must have been down because nothing would load." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: J3.03 (Availability) +- **Valence**: V- | **Intensity**: I2 | **CR**: CR-N + +**RATIONALE**: The service/system was unavailable, not the app itself broken. "Servers must have been down" = system uptime issue. This is J3.03, NOT O1.01 or E2.02. + +--- + +### 4.5 P3.04 vs R1.02: Specific vs Pattern + +#### CP-PR-01: Specific Follow-Through (P3.04) +**Difficulty**: Expert + +**Review Text**: "The salesperson said she'd email me the quote by EOD but I never received it." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: P3.04 (Follow-Through) +- **Valence**: V- | **Intensity**: I1 | **CR**: CR-N + +**RATIONALE**: Single specific incident of not completing a promised action. This is P3.04, a People domain code about individual behavior. + +--- + +#### CP-PR-02: Pattern of Broken Promises (R1.02) +**Difficulty**: Expert + +**Review Text**: "This company never keeps their promises. Every deadline they commit to gets pushed back, every commitment is an empty word." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: R1.02 (Promise Keeping) +- **Valence**: V- | **Intensity**: I3 | **Temporal**: TH | **CR**: CR-N + +**RATIONALE**: Pattern-level complaint about organizational trustworthiness ("never keeps," "every deadline," "every commitment"). This is R1.02, a Relationship domain code about trust patterns. + +--- + +## 5. Multi-Code Span Examples + +### MC-01: Cause-Effect Single Span +**Difficulty**: Medium + +**Review Text**: "The wait was ridiculous because they only had one cashier working during the lunch rush." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: Full sentence (keep together) +- **Primary Code**: J1.01 (Wait Time) - the impact +- **Secondary Codes**: A1.04 (Staffing Levels) - the cause +- **Valence**: V- +- **Intensity**: I3 +- **CR**: CR-N + +**RATIONALE**: Cause-effect in same clause stays together. Primary = customer-experienced impact (wait). Secondary = underlying cause (understaffing). Do NOT split. + +--- + +### MC-02: Two Distinct Complaints +**Difficulty**: Medium + +**Review Text**: "The pizza was cold AND the delivery driver was rude about it." + +**GOLD STANDARD CLASSIFICATION**: +- **Span 1**: "The pizza was cold" + - Primary: O2.05 (Condition at Delivery) + - V-/I2 +- **Span 2**: "the delivery driver was rude about it" + - Primary: P1.02 (Respect) + - V-/I2 + +**RATIONALE**: Two genuinely different issues (product condition + staff behavior). SPLIT into separate spans because they're different domains with independent fixes. + +--- + +### MC-03: Multi-Domain Complex +**Difficulty**: Hard + +**Review Text**: "Beautiful restaurant with friendly staff, but the food took forever and when it arrived it was barely warm." + +**GOLD STANDARD CLASSIFICATION**: +- **Span 1**: "Beautiful restaurant" + - Primary: E3.05 (Aesthetics) + - V+/I2 +- **Span 2**: "friendly staff" + - Primary: P1.01 (Warmth/Friendliness) + - V+/I2 +- **Span 3**: "the food took forever" + - Primary: J1.02 (Service Speed) + - V-/I2 +- **Span 4**: "when it arrived it was barely warm" + - Primary: O2.05 (Condition at Delivery) + - V-/I1 + +**RATIONALE**: Four distinct feedback points across four domains. Split at "but" (valence change) and at subject changes. + +--- + +### MC-04: Same Target, Mixed Assessment +**Difficulty**: Medium + +**Review Text**: "The steak was good but overpriced for what you get." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: Keep as one (same target) +- **Primary Code**: V4.02 (Quality-Price Ratio) +- **Valence**: V+- +- **Intensity**: I2 + +**RATIONALE**: Same target (the steak) with mixed assessment. Use V+- because positive and negative target the same thing. Do NOT split. + +--- + +### MC-05: Staff State Causal Chain +**Difficulty**: Expert + +**Review Text**: "Our server seemed exhausted and kept forgetting our orders. When I asked about it, she said they'd been working 12-hour shifts all week." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: "Our server seemed exhausted and kept forgetting our orders" +- **Primary Code**: J3.02 (Accuracy) +- **Secondary Codes**: P3.01 (Attentiveness) +- **Valence**: V- +- **Intensity**: I2 +- **Evidence**: ES +- **Causal Chain**: CD-S (Staff State: fatigue) - Evidence: ES (explicitly stated) + +**RATIONALE**: Primary is the customer impact (wrong orders). Causal code CD-S is valid because the fatigue and 12-hour shifts are explicitly stated, not inferred. + +--- + +### MC-06: Management Oversight Causal +**Difficulty**: Expert + +**Review Text**: "This is the fourth time I've reported this broken equipment and nothing has been done about it." + +**GOLD STANDARD CLASSIFICATION**: +- **Span**: Full sentence +- **Primary Code**: E1.02 (Maintenance) +- **Secondary Codes**: None +- **Valence**: V- +- **Intensity**: I3 +- **Temporal**: TH +- **CR**: CR-S +- **Causal Chain**: MG-O (Oversight failure) - Evidence: EI + +**RATIONALE**: CR-S because "still" broken after multiple reports. Causal MG-O is valid via EI because "fourth time" + "nothing done" logically entails oversight/supervision failure. + +--- + +### MC-07: Improvement Signal with Context +**Difficulty**: Hard + +**Review Text**: "The customer service used to be terrible but they've really turned things around. Fast, helpful, and actually solve problems now." + +**GOLD STANDARD CLASSIFICATION**: +- **Span 1**: "The customer service used to be terrible" + - Primary: P (domain level for context) + - V-/I2/CR-W (implicit past-negative) +- **Span 2**: "they've really turned things around. Fast, helpful, and actually solve problems now" + - Primary: P3.05 (Urgency) or P2.03 (Problem-Solving) + - Secondary: P1.01 (Warmth/Friendliness) + - V+/I2/CR-B + +**RATIONALE**: CR-B on the second span captures the improvement signal. "Turned things around" is explicit improvement. + +--- + +### MC-08: Compound Issue with Different Owners +**Difficulty**: Hard + +**Review Text**: "The app crashes constantly AND when I call support they put me on hold for 45 minutes." + +**GOLD STANDARD CLASSIFICATION**: +- **Span 1**: "The app crashes constantly" + - Primary: E2.02 (Digital Functionality) + - V-/I3 + - Owner: IT +- **Span 2**: "when I call support they put me on hold for 45 minutes" + - Primary: J1.01 (Wait Time) + - V-/I3 + - Owner: Operations + +**RATIONALE**: Two distinct issues requiring different owners. Split to enable proper routing. + +--- + +## 6. Edge Cases and Boundary Conditions + +### EC-01: Neutral Observation +**Difficulty**: Medium + +**Review Text**: "The restaurant has about 50 seats and they serve Italian food. Parking lot fits maybe 20 cars." + +**GOLD STANDARD CLASSIFICATION**: +- **Valence**: V0 (Neutral) +- **Primary Code**: E3.04 (Crowding/Capacity) or A4.02 (Parking) +- **Intensity**: I1 + +**RATIONALE**: Pure factual observation without judgment. Assign V0 (Neutral). Code based on what information could be useful (capacity, parking). + +--- + +### EC-02: Sarcasm Detection +**Difficulty**: Hard + +**Review Text**: "Oh sure, I LOVE waiting 2 hours for a table with a reservation. Really makes me feel valued." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: J1.01 (Wait Time) +- **Valence**: V- (negative despite positive words) +- **Intensity**: I3 (CAPS, sarcasm = strong) +- **CR**: CR-N + +**RATIONALE**: Sarcasm inverts literal meaning. "LOVE" + extreme wait = clear complaint. Code the actual sentiment (V-), not the literal words. + +--- + +### EC-03: Future Intent Statement +**Difficulty**: Medium + +**Review Text**: "If they don't fix the parking situation, I won't be coming back." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: A4.02 (Parking) +- **Valence**: V- +- **Intensity**: I2 +- **Temporal**: TF (Future) + +**RATIONALE**: Conditional future statement. Code the issue being complained about (parking). Temporal TF because it's about future intent/expectation. + +--- + +### EC-04: Competitor Comparison (NOT CR) +**Difficulty**: Hard + +**Review Text**: "Their customer service is way better than Amazon's." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: P (People domain) +- **Valence**: V+ +- **CR**: CR-N (NOT CR-B) + +**RATIONALE**: Competitor comparison is NOT CR. CR is only for self-comparison to customer's own past experience. This is CR-N despite "better than." + +--- + +### EC-05: Implicit Decline +**Difficulty**: Expert + +**Review Text**: "This used to be my favorite restaurant." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: R2.02 (Consistency) +- **Valence**: V- +- **Intensity**: I2 +- **Temporal**: TH +- **CR**: CR-W + +**RATIONALE**: "Used to be" implies past-positive, present-negative = CR-W (decline). The statement is negative despite no explicit current complaint. Past tense + "favorite" = implicit decline. + +--- + +### EC-06: Mixed Temporal Reference +**Difficulty**: Expert + +**Review Text**: "The breakfast has always been good but lately the portions have gotten smaller." + +**GOLD STANDARD CLASSIFICATION**: +- **Span 1**: "The breakfast has always been good" + - Primary: O2.02 (Craftsmanship) + - V+/TH/CR-S +- **Span 2**: "lately the portions have gotten smaller" + - Primary: O3.03 (Scope Delivery) + - V-/TR/CR-W + +**RATIONALE**: Two different temporal references and valences. Split and assign appropriate T and CR values to each. + +--- + +### EC-07: Identity-Framed Complaint +**Difficulty**: Hard + +**Review Text**: "As a vegetarian, there was literally nothing I could eat on the menu." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: A3.03 (Dietary/Medical) +- **Valence**: V- +- **Intensity**: I3 ("literally nothing") + +**RATIONALE**: A3.03 (dietary accommodation) not O4.03 (flexibility) because it's framed as identity-based inclusion ("as a vegetarian"). + +--- + +### EC-08: Praise with Caveat +**Difficulty**: Medium + +**Review Text**: "Everything was perfect... except for the price. But still worth it overall." + +**GOLD STANDARD CLASSIFICATION**: +- **Span 1**: "Everything was perfect" + - V+/I3 +- **Span 2**: "except for the price" + - Primary: V1.01 (Absolute Price) + - V-/I2 +- **Span 3**: "But still worth it overall" + - Primary: V4.01 (Overall Value) + - V+/I2 + +**RATIONALE**: Three distinct assessments. Final assessment is positive despite price complaint. Split at each valence shift. + +--- + +### EC-09: Ambiguous Referent +**Difficulty**: Expert + +**Review Text**: "They really need to fix that." + +**GOLD STANDARD CLASSIFICATION**: +- **Evidence**: EC (Contextual) +- **Primary Code**: [Cannot determine without context] + +**RATIONALE**: Ambiguous referent ("that") requires surrounding context to classify. Mark Evidence as EC. If no context available, flag for review. + +--- + +### EC-10: Causal Without Evidence +**Difficulty**: Expert + +**Review Text**: "The food took forever. They're probably understaffed or something." + +**GOLD STANDARD CLASSIFICATION**: +- **Primary Code**: J1.02 (Service Speed) +- **Valence**: V- +- **Intensity**: I2 +- **Causal Chain**: NONE + +**RATIONALE**: "Probably" indicates speculation. Do NOT assign CD-O (Understaffing) as causal code. Causal codes require explicit statement or logical entailment, not customer guessing. + +--- + +## 7. Certification Test Structure + +### 7.1 Entry-Level Test (Lite Profile) + +**Target**: New annotators beginning URT training +**Items**: 20 +**Time Limit**: 30 minutes +**Required Accuracy**: >= 85% + +| Component | Items | Focus | +|-----------|-------|-------| +| Domain classification | 14 | Correctly identify O-P-J-E-A-V-R | +| Valence assignment | 6 | V+, V-, V0, V+- | + +**Test Pool**: Easy difficulty items only +- O-EASY-01, O-EASY-02 +- P-EASY-01, P-EASY-02 +- J-EASY-01, J-EASY-02 +- E-EASY-01, E-EASY-02 +- A-EASY-01, A-EASY-02 +- V-EASY-01, V-EASY-02 +- R-EASY-01, R-EASY-02 +- Plus 6 additional Easy items for valence focus + +--- + +### 7.2 Standard Certification (Core Profile) + +**Target**: Annotators for dashboard/trend work +**Items**: 40 +**Time Limit**: 60 minutes +**Required Accuracy**: >= 85% + +| Component | Items | Focus | +|-----------|-------|-------| +| Domain classification | 10 | All 7 domains | +| Category classification | 20 | Correctly identify O1-O4, P1-P4, etc. | +| Valence + Intensity | 10 | Correct V and I assignment | + +**Test Pool**: Easy + Medium difficulty +- All Easy items +- All Medium items (O-MEDIUM-01, O-MEDIUM-02, etc.) +- Selected confusion pairs (CP-VR-01, CP-VR-02) + +--- + +### 7.3 Advanced Certification (Standard Profile) + +**Target**: Annotators for full analytics pipeline +**Items**: 60 +**Time Limit**: 90 minutes +**Required Accuracy**: >= 80% + +| Component | Items | Focus | +|-----------|-------|-------| +| Subcode classification | 30 | Correct X.XX subcode | +| Multi-code assignment | 10 | Primary + Secondary | +| Full metadata | 15 | All 7 dimensions | +| Confusion pairs | 5 | V vs R, J4 vs R3, etc. | + +**Test Pool**: Easy + Medium + Hard difficulty +- All Easy and Medium items +- All Hard items +- All confusion pair examples +- Multi-code examples MC-01 through MC-04 + +--- + +### 7.4 Expert Certification (Full Profile) + +**Target**: Lead annotators, QA reviewers, gold standard creators +**Items**: 80 +**Time Limit**: 120 minutes +**Required Accuracy**: >= 80% + +| Component | Items | Focus | +|-----------|-------|-------| +| Subcode classification | 30 | All difficulty levels | +| Multi-code + Causal | 15 | Including causal chain | +| Full metadata | 20 | All dimensions including CR | +| Edge cases | 10 | Boundary conditions | +| Complex scenarios | 5 | Expert difficulty items | + +**Test Pool**: All difficulty levels +- All items from all difficulty levels +- All multi-code examples (MC-01 through MC-08) +- All edge cases (EC-01 through EC-10) +- Expert items (O-EXPERT-01, R-EXPERT-01, etc.) + +--- + +## 8. Scoring Rubric + +### 8.1 Point Values by Component + +| Component | Correct | Partial | Incorrect | +|-----------|---------|---------|-----------| +| **Domain (Tier 1)** | 4 pts | 0 pts | 0 pts | +| **Category (Tier 2)** | 3 pts | 1 pt (correct domain) | 0 pts | +| **Subcode (Tier 3)** | 2 pts | 1 pt (correct category) | 0 pts | +| **Valence** | 2 pts | 0 pts | 0 pts | +| **Intensity** | 1 pt | 0 pts | 0 pts | +| **Secondary Code (each)** | 1 pt | 0.5 pt (correct domain) | 0 pts | +| **Specificity** | 1 pt | 0 pts | 0 pts | +| **Actionability** | 1 pt | 0 pts | 0 pts | +| **Temporal** | 1 pt | 0 pts | 0 pts | +| **Evidence** | 1 pt | 0 pts | 0 pts | +| **Comparative Reference** | 1 pt | 0 pts | 0 pts | +| **Causal Code (each)** | 2 pts | 0 pts | -1 pt (false positive) | + +### 8.2 Error Severity Weights + +| Severity | Weight | Examples | +|----------|--------|----------| +| **Critical** | 1.0 | Wrong domain, wrong valence | +| **Major** | 0.5 | Wrong category, intensity off by 2, wrong CR direction | +| **Minor** | 0.25 | Wrong subcode (same category), intensity off by 1 | +| **Slip** | 0.1 | Typo, boundary off by <5 chars | + +### 8.3 Profile-Specific Max Scores + +| Profile | Max Points per Item | Components Scored | +|---------|---------------------|-------------------| +| Lite | 6 pts | Domain (4) + Valence (2) | +| Core | 10 pts | Domain (4) + Category (3) + V (2) + I (1) | +| Standard | 17 pts | Subcode (2) + V (2) + I (1) + S (1) + A (1) + T (1) + E (1) + CR (1) + Secondary (2x1) + Domain context (4) | +| Full | 23 pts | Standard + Causal (up to 3x2) | + +--- + +## 9. Pass/Fail Criteria + +### 9.1 Certification Thresholds + +| Level | Overall Accuracy | Critical Errors | Domain Accuracy | +|-------|------------------|-----------------|-----------------| +| **Entry (Lite)** | >= 85% | 0 allowed | >= 90% | +| **Standard (Core)** | >= 85% | 0 allowed | >= 90% | +| **Advanced (Standard)** | >= 80% | 0 allowed | >= 85% | +| **Expert (Full)** | >= 80% | 0 allowed | >= 85% | + +### 9.2 Automatic Failure Conditions + +The following result in automatic test failure regardless of overall score: + +1. **Wrong Domain on 3+ items** - indicates fundamental misunderstanding +2. **Wrong Valence on 2+ items** - basic sentiment recognition failure +3. **V vs R confusion on both test items** - critical disambiguation failure +4. **J4 vs R3 confusion on both test items** - critical disambiguation failure +5. **Invented causal codes** - assigning causal without evidence support + +### 9.3 Retake Policy + +| Failure Type | Required Action | Wait Period | +|--------------|-----------------|-------------| +| Score < threshold | Review A1 materials | 3 days | +| Critical error(s) | Targeted training session | 5 days | +| Domain accuracy failure | Domain-specific training | 5 days | +| Second failure | Supervisor review required | 7 days | +| Third failure | Consider alternative assignment | N/A | + +### 9.4 Ongoing Maintenance + +Certified annotators must maintain: + +| Requirement | Frequency | Threshold | +|-------------|-----------|-----------| +| Accuracy spot check | Weekly | >= 90% | +| Calibration attendance | Weekly | 90% sessions | +| Recertification quiz | Quarterly | >= 85% | +| IAA with peers | Bi-weekly | Kappa >= 0.75 | + +### 9.5 Certification Levels Summary + +| Level | Profile | Test Items | Pass Score | Privileges | +|-------|---------|------------|------------|------------| +| Entry | Lite | 20 | 85% | Can annotate Lite profile | +| Standard | Core | 40 | 85% | Can annotate Core profile | +| Advanced | Standard | 60 | 80% | Can annotate Standard profile | +| Expert | Full | 80 | 80% | Full profile + QA reviewer + Gold standard creation | + +--- + +## Document References + +| Document | Location | Purpose | +|----------|----------|---------| +| URT-Specification-v5.1.md | `/urt-taxonomy/spec/` | Full taxonomy reference | +| A1-Annotator-Quickstart.md | `/urt-taxonomy/track-a-training/` | Quick reference guide | +| A2-QA-Protocol.md | `/urt-taxonomy/track-a-training/` | Quality assurance procedures | +| B1-urt-codes.yaml | `/urt-taxonomy/track-b-engineering/` | Machine-readable code registry | + +--- + +## Appendix: Quick Reference Tables + +### All 7 Domains + +| Code | Domain | Core Question | +|------|--------|---------------| +| O | Offering | Does it work? | +| P | People | How did they treat me? | +| J | Journey | Was it smooth? | +| E | Environment | Is the space okay? | +| A | Access | Can I get it? | +| V | Value | Is it worth it? | +| R | Relationship | Can I trust them? | + +### All 28 Categories + +| O | P | J | E | A | V | R | +|---|---|---|---|---|---|---| +| O1 Function | P1 Attitude | J1 Timing | E1 Physical | A1 Availability | V1 Price | R1 Integrity | +| O2 Quality | P2 Competence | J2 Ease | E2 Digital | A2 Accessibility | V2 Transparency | R2 Dependability | +| O3 Completeness | P3 Responsiveness | J3 Reliability | E3 Ambiance | A3 Inclusivity | V3 Effort | R3 Recovery | +| O4 Fit | P4 Communication | J4 Resolution | E4 Safety | A4 Convenience | V4 Worth | R4 Loyalty | + +### Metadata Quick Reference + +| Dimension | Values | Default | +|-----------|--------|---------| +| Valence | V+, V-, V0, V+- | None | +| Intensity | I1, I2, I3 | None | +| Specificity | S1, S2, S3 | None | +| Actionability | A1, A2, A3 | None | +| Temporal | TC, TR, TH, TF | TC | +| Evidence | ES, EI, EC | ES | +| Comparative | CR-N, CR-B, CR-W, CR-S | CR-N | + +--- + +*URT v5.1 Calibration Test Set | Track A: Training Materials* +*Gold Standard Corpus for Annotator Certification* diff --git a/urt-taxonomy/track-a-training/A4-Full-Annotation-Manual.md b/urt-taxonomy/track-a-training/A4-Full-Annotation-Manual.md new file mode 100644 index 0000000..9347d85 --- /dev/null +++ b/urt-taxonomy/track-a-training/A4-Full-Annotation-Manual.md @@ -0,0 +1,4578 @@ +# A4: Full Annotation Manual +## Universal Review Taxonomy (URT) v5.1 + +**Purpose**: Comprehensive reference for human annotators with complete domain, subcode, and metadata documentation +**Version**: 5.1 | **Status**: Production Ready | **Date**: 2026-01-24 + +--- + +## Table of Contents + +1. [Introduction](#1-introduction) +2. [URT Framework Overview](#2-urt-framework-overview) +3. [Complete Domain Reference](#3-complete-domain-reference) + - [3.1 Domain O: Offering](#31-domain-o-offering) + - [3.2 Domain P: People](#32-domain-p-people) + - [3.3 Domain J: Journey](#33-domain-j-journey) + - [3.4 Domain E: Environment](#34-domain-e-environment) + - [3.5 Domain A: Access](#35-domain-a-access) + - [3.6 Domain V: Value](#36-domain-v-value) + - [3.7 Domain R: Relationship](#37-domain-r-relationship) +4. [Metadata Dimensions](#4-metadata-dimensions) +5. [Causal Codes](#5-causal-codes) +6. [Span Boundary Rules](#6-span-boundary-rules) +7. [Disambiguation Guide](#7-disambiguation-guide) +8. [USN Notation](#8-usn-notation) +9. [Appendices](#9-appendices) + +--- + +## 1. Introduction + +### 1.1 Purpose of This Manual + +The A4 Full Annotation Manual provides comprehensive documentation for all URT v5.1 classification codes, metadata dimensions, and annotation rules. This manual serves as: + +- **Definitive reference** for all 140 subcodes across 7 domains +- **Training resource** for annotators advancing beyond the A1 Quickstart Guide +- **Disambiguation authority** when codes appear similar or overlapping +- **Quality standard** aligned with A2 QA Protocol requirements +- **Calibration source** supporting A3 Calibration Test Set exercises + +### 1.2 How to Use This Manual + +| User Need | Recommended Approach | +|-----------|---------------------| +| **Quick code lookup** | Use Section 3 domain tables with Ctrl+F | +| **Understand a subcode** | Read the inclusion/exclusion criteria and examples | +| **Resolve confusion between codes** | Check Section 7 Disambiguation Guide | +| **Learn metadata assignment** | Study Section 4 with worked examples | +| **Understand causal analysis** | Review Section 5 Causal Codes | +| **Verify span boundaries** | Consult Section 6 Span Boundary Rules | + +### 1.3 Relationship to Other Training Documents + +| Document | Relationship to A4 | +|----------|-------------------| +| **A1-Annotator-Quickstart.md** | A4 expands on A1's summary tables with full definitions | +| **A2-QA-Protocol.md** | A4 provides the standards A2 measures against | +| **A3-Calibration-Test-Set.md** | A4 explains the rationale behind A3's gold answers | +| **URT-Specification-v5.1.md** | A4 reformats the spec for annotator workflows | + +### 1.4 Document Conventions + +Throughout this manual: +- **(+)** indicates a positive example +- **(-)** indicates a negative example +- **Include** criteria define what belongs in a code +- **Exclude** criteria clarify what does NOT belong +- **Common Errors** highlight frequent mistakes + +--- + +## 2. URT Framework Overview + +### 2.1 Taxonomy Structure + +URT organizes customer feedback into a three-tier hierarchy: + +``` +TIER 1: DOMAINS (7) + └── TIER 2: CATEGORIES (28 = 4 per domain) + └── TIER 3: SUBCODES (140 = 5 per category) +``` + +**Canonical Counts**: +- 7 experience domains +- 28 categories (4 per domain) +- 140 diagnostic subcodes (5 per category) +- 16 causal codes (optional root-cause layer) +- 7 metadata dimensions with 24 total values + +### 2.2 The Seven Domains + +| Code | Domain | Core Question | Default Owner | +|------|--------|---------------|---------------| +| **O** | Offering | Does the core product/service deliver? | Product / Operations | +| **P** | People | How do personnel behave and perform? | HR / Training | +| **J** | Journey | Is the process smooth and timely? | Operations / Process | +| **E** | Environment | Is the space functional and pleasant? | Facilities / IT | +| **A** | Access | Can everyone participate fully? | Compliance / Design | +| **V** | Value | Is the exchange fair and transparent? | Finance / Pricing | +| **R** | Relationship | Is trust built and maintained? | Leadership / CX | + +**Memory Aid**: O-P-J-E-A-V-R = "**O**ffer **P**eople a **J**ourney in an **E**nvironment with **A**ccess to **V**alue and **R**elationship" + +### 2.3 Quick Decision Tree + +Use this flowchart for domain selection. Go top-to-bottom; first "YES" wins. + +``` +START: Read the span + | + v ++-----------------------------------------------+ +| Is it about the THING they bought/received? | +| (product, service, treatment, outcome) | ++-----------------------------------------------+ + | YES --> O (Offering) + | NO | + v ++-----------------------------------------------+ +| Is it about HOW PEOPLE behaved? | +| (staff attitude, skill, communication) | ++-----------------------------------------------+ + | YES --> P (People) + | NO | + v ++-----------------------------------------------+ +| Is it about TIME, STEPS, or FRICTION? | +| (waiting, process, ease, resolution steps) | ++-----------------------------------------------+ + | YES --> J (Journey) + | NO | + v ++-----------------------------------------------+ +| Is it about the SPACE or INTERFACE? | +| (physical place, app/website, ambiance) | ++-----------------------------------------------+ + | YES --> E (Environment) + | NO | + v ++-----------------------------------------------+ +| Is it about ABILITY TO ACCESS or INCLUSION? | +| (availability, disability, language, bias) | ++-----------------------------------------------+ + | YES --> A (Access) + | NO | + v ++-----------------------------------------------+ +| Is it about PRICE, COST, or WORTH? | +| (money, effort, value, transparency) | ++-----------------------------------------------+ + | YES --> V (Value) + | NO | + v ++-----------------------------------------------+ +| Is it about TRUST, PATTERNS, or LOYALTY? | +| (honesty over time, brand, recovery, bond) | ++-----------------------------------------------+ + | YES --> R (Relationship) + | NO | + v + RE-READ SPAN -- may need splitting +``` + +### 2.4 Implementation Profiles + +URT supports four implementation profiles with increasing complexity: + +| Profile | Primary Code Level | Metadata Required | Use Case | +|---------|-------------------|-------------------|----------| +| **URT-Lite** | Domain (O, P, J...) | Valence only | Micro-business, quick triage | +| **URT-Core** | Category (O1, P2...) | Valence + Intensity | Small business, dashboards | +| **URT-Standard** | Subcode (O1.01, P2.03...) | All 7 dimensions | Operations, routing, analytics | +| **URT-Full** | Subcode + Causal | All dimensions + Causal | Enterprise, root cause, audit | + +### 2.5 Profile Requirements Matrix + +| Field | Lite | Core | Standard | Full | +|-------|:----:|:----:|:--------:|:----:| +| primary_code | Domain | Category | Subcode | Subcode | +| secondary_codes | Forbidden | Max 2 (Cat) | Max 2 (Sub) | Max 2 (Sub) | +| valence | Required | Required | Required | Required | +| intensity | Optional | Required | Required | Required | +| specificity | -- | -- | Required | Required | +| actionability | -- | -- | Required | Required | +| temporal | -- | Optional | Required | Required | +| evidence | -- | -- | Required | Required | +| comparative | -- | Optional | Required | Required | +| causal_chain | -- | -- | Optional | Required* | + +*Required when evidence supports + +--- + +## 3. Complete Domain Reference + +### 3.1 Domain O: Offering + +**Definition**: The core product, service, or outcome delivered to the customer. + +**Core Question**: Does what we provide actually work and meet expectations? + +**Default Owner**: Product / Operations + +**Scope**: +- The thing itself (product, service, treatment, meal, deliverable) +- Its functionality, quality, completeness, and fit +- Outcomes and results achieved (or not achieved) + +**NOT in Scope**: +- How staff behaved during delivery (P domain) +- The process of obtaining it (J domain) +- The environment where it was delivered (E domain) + +#### O1: Function + +**Category Definition**: Does the product/service do what it's supposed to do? + +##### O1.01 Works/Doesn't Work + +**Definition**: Basic functionality success or failure - whether the product/service performs its fundamental purpose. + +**Include**: +- Complete functional failure ("won't turn on," "doesn't work at all") +- Core functionality issues ("can't make calls," "won't connect") +- Binary working/not working assessments + +**Exclude**: +- Performance quality issues (use O1.02) +- System/service availability (use J3.03) +- Interface/app functionality (use E2.02) + +**Examples**: +- (+) "Software runs perfectly on my machine" +- (+) "Phone works exactly as expected" +- (-) "Car won't start at all" +- (-) "The blender doesn't turn on - completely dead" + +**Common Errors**: +- Confusing with J3.03 (System Uptime): "Website was down" = J3.03; "Feature is broken" = O1.01 +- Confusing with E2.02 (Digital Functionality): App features not working = E2.02; Core product functionality = O1.01 + +##### O1.02 Performance Level + +**Definition**: How well the product/service operates when it does work. + +**Include**: +- Speed of operation ("lightning fast," "sluggish") +- Efficiency metrics ("great battery life," "fuel efficient") +- Capability levels ("powerful," "weak") + +**Exclude**: +- Interface/app speed (use E2.03) +- Basic functionality (use O1.01) +- Durability over time (use O1.03) + +**Examples**: +- (+) "Incredibly fast processor - handles everything I throw at it" +- (+) "Best vacuum suction I've ever experienced" +- (-) "Sluggish and laggy even with simple tasks" +- (-) "Motor is weak - struggles with thick materials" + +**Common Errors**: +- Confusing with E2.03 (Interface Performance): E2.03 is app/website speed; O1.02 is the core product's performance + +##### O1.03 Durability + +**Definition**: Longevity and resistance to wear over time. + +**Include**: +- How long it lasted before failing +- Wear and tear assessments +- Build quality affecting lifespan + +**Exclude**: +- Material quality itself (use O2.01) +- One-time damage at delivery (use O2.05) +- Consistency of function (use O1.04) + +**Examples**: +- (+) "Still perfect after 5 years of daily use" +- (+) "Built like a tank - survived multiple drops" +- (-) "Fell apart in a month" +- (-) "Zipper broke after just two washes" + +**Common Errors**: +- Confusing with O2.01 (Materials): O2.01 is about material quality observed; O1.03 is about how long it lasted + +##### O1.04 Reliability + +**Definition**: Consistency of function over time - whether it works dependably. + +**Include**: +- Intermittent failures ("works sometimes") +- Consistency of performance over uses +- Dependability assessments + +**Exclude**: +- Process reliability (use J3.01) +- Organizational dependability (use R2.02) +- Single instance failure (use O1.01) + +**Examples**: +- (+) "Never fails me - works every single time" +- (+) "Reliable connection, never drops" +- (-) "Works sometimes, not others - frustrating" +- (-) "Intermittent issues - can't depend on it" + +**Common Errors**: +- Confusing with J3.01 (Process Consistency): J3.01 = "They deliver the same quality each time"; O1.04 = "The product itself works consistently" + +##### O1.05 Outcome Achievement + +**Definition**: Whether the customer accomplished their intended goal through the product/service. + +**Include**: +- Treatment/therapy results +- Learning/certification outcomes +- Problem resolution via product +- Goal attainment through service + +**Exclude**: +- General satisfaction (use V4.03) +- Value judgment (use V4.01) +- Quality assessment (use O2) + +**Examples**: +- (+) "Passed my certification exam on the first try!" +- (+) "Back pain is completely gone after treatment" +- (-) "Treatment didn't work - still in pain" +- (-) "Course was useless - didn't learn what I needed" + +**Common Errors**: +- Confusing with V4.03 (Satisfaction): V4.03 is general contentment; O1.05 is specific goal achievement + +--- + +#### O2: Quality + +**Category Definition**: How well is the product/service made or executed? + +##### O2.01 Materials/Inputs + +**Definition**: Quality of the components, ingredients, or raw materials used. + +**Include**: +- Material quality observations ("real leather," "cheap plastic") +- Ingredient quality ("fresh," "stale") +- Component quality ("premium parts") + +**Exclude**: +- Durability over time (use O1.03) +- How it was assembled (use O2.02) +- Visual presentation (use O2.03) + +**Examples**: +- (+) "Real leather, premium feel to the touch" +- (+) "Fresh ingredients - you can taste the quality" +- (-) "Cheap plastic parts that feel flimsy" +- (-) "Obviously low-grade materials" + +**Common Errors**: +- Confusing with O1.03 (Durability): "Cheap materials" = O2.01; "Broke quickly" = O1.03 + +##### O2.02 Craftsmanship + +**Definition**: Skill of construction, assembly, or execution. + +**Include**: +- Build quality and assembly +- Skill of preparation or creation +- Attention to construction details + +**Exclude**: +- Visual presentation (use O2.03) +- Staff technical skill (use P2.02) +- Finishing details only (use O2.04) + +**Examples**: +- (+) "Beautifully sewn seams - masterful tailoring" +- (+) "Perfectly cooked - restaurant quality" +- (-) "Sloppy assembly - seams coming apart" +- (-) "Amateur hour - clearly unskilled preparation" + +**Common Errors**: +- Confusing with P2.02 (Technical Skill): P2.02 is about the person's skill; O2.02 is about the result's quality + +##### O2.03 Presentation + +**Definition**: Visual and aesthetic quality of the product itself. + +**Include**: +- How the product looks +- Plating and display of food +- Packaging aesthetics +- Visual appeal of deliverables + +**Exclude**: +- Space/environment aesthetics (use E3.05) +- Interface design (use E2.01) +- Finishing details (use O2.04) + +**Examples**: +- (+) "Gorgeous plating - almost too pretty to eat" +- (+) "Beautiful packaging - felt like a gift" +- (-) "Looked thrown together - no care taken" +- (-) "Presentation was awful - food slapped on plate" + +**Common Errors**: +- Confusing with E3.05 (Space Aesthetics): E3.05 is the environment's beauty; O2.03 is the product's visual quality + +##### O2.04 Attention to Detail + +**Definition**: Finishing touches, refinement, and care in the small things. + +**Include**: +- Polish and refinement +- Thoughtful small touches +- Thoroughness in details + +**Exclude**: +- Missing components (use O3.01) +- Major quality issues (use O2.02) +- Presentation overall (use O2.03) + +**Examples**: +- (+) "Every corner perfect - remarkable attention to detail" +- (+) "Little touches that show they care" +- (-) "Full of typos and errors - no proofreading" +- (-) "Rough edges and sloppy finishing" + +**Common Errors**: +- Confusing with O3.01 (Components): O3.01 is about missing parts; O2.04 is about refinement of what's there + +##### O2.05 Condition at Delivery + +**Definition**: The state of the product when received by the customer. + +**Include**: +- Damage during shipping +- Temperature of food upon arrival +- Freshness at time of receipt +- Physical condition at handoff + +**Exclude**: +- Original manufacturing quality (use O2.02) +- Accuracy of delivery (use J3.02) +- Packaging quality (use O2.03) + +**Examples**: +- (+) "Still warm from the oven when it arrived" +- (+) "Arrived in perfect condition, well-protected" +- (-) "Arrived damaged - box was crushed" +- (-) "Food was cold by the time it got here" + +**Common Errors**: +- Confusing with J3.02 (Accuracy): J3.02 is "wrong item delivered"; O2.05 is "right item, wrong condition" + +--- + +#### O3: Completeness + +**Category Definition**: Is everything included that should be? + +##### O3.01 All Components Present + +**Definition**: Nothing missing from what was promised or expected. + +**Include**: +- Missing parts or accessories +- Incomplete orders +- Missing pieces from sets + +**Exclude**: +- Wrong item (use O4.01) +- Missing features (use O3.02) +- Incomplete work scope (use O3.03) + +**Examples**: +- (+) "Everything in the box - all accessories included" +- (+) "Complete set, nothing missing" +- (-) "Missing the charger - had to buy separately" +- (-) "Several pieces missing from the kit" + +**Common Errors**: +- Confusing with O4.01 (Specification Match): O4.01 is wrong item; O3.01 is incomplete item + +##### O3.02 Feature Availability + +**Definition**: Promised or expected features actually exist and work. + +**Include**: +- Advertised features not available +- Menu items unavailable +- Promised capabilities missing + +**Exclude**: +- Physical inventory (use A1.03) +- Features that are broken (use O1.01) +- Features not matching ads (use V2.03) + +**Examples**: +- (+) "All menu items available as advertised" +- (+) "Every feature works as promised" +- (-) "Half the features are disabled" +- (-) "Feature has been 'coming soon' for 8 months" + +**Common Errors**: +- Confusing with A1.03 (Inventory): A1.03 is physical stock; O3.02 is feature/capability availability + +##### O3.03 Scope Delivery + +**Definition**: Full scope of work or service completed as agreed. + +**Include**: +- Incomplete service delivery +- Partial completion of work +- Unfinished portions + +**Exclude**: +- Quality of completed work (use O2.02) +- Resolution completeness (use J4.04) +- Missing components (use O3.01) + +**Examples**: +- (+) "Cleaned entire house top to bottom" +- (+) "Completed all the agreed-upon items" +- (-) "Left the bathrooms undone" +- (-) "Only finished half the project" + +**Common Errors**: +- Confusing with J4.04 (Resolution Quality): J4.04 is about fixes; O3.03 is about initial scope + +##### O3.04 Documentation + +**Definition**: Supporting materials, instructions, and documentation provided. + +**Include**: +- Manuals and instructions +- Documentation quality +- Reference materials provided + +**Exclude**: +- Process simplicity (use J2.01 when docs affect onboarding) +- Staff explanations (use P4.01) +- Information accuracy (use P4.04) + +**Examples**: +- (+) "Great user manual - very helpful" +- (+) "Comprehensive documentation included" +- (-) "No instructions at all" +- (-) "Documentation was outdated and useless" + +**Common Errors**: +- **Documentation Rule**: Use O3.04 when docs are a product artifact ("manual was helpful"). Use J2.01 when docs affect onboarding friction ("couldn't figure out how to start"). + +--- + +#### O4: Fit + +**Category Definition**: Does the product/service match the customer's specific needs? + +##### O4.01 Specification Match + +**Definition**: Whether the product matches what was ordered or specified. + +**Include**: +- Wrong size, color, model delivered +- Not matching order specifications +- Different than what was requested + +**Exclude**: +- Process accuracy errors (use J3.02) +- Missing parts (use O3.01) +- Not meeting needs (use O4.04) + +**Examples**: +- (+) "Exactly what I ordered - perfect match" +- (+) "Right size, right color, exactly as specified" +- (-) "Wrong size delivered - ordered medium, got large" +- (-) "Ordered blue, received red" + +**Common Errors**: +- Confusing with J3.02 (Process Accuracy): O4.01 = "This isn't what I need"; J3.02 = "They made a fulfillment error" + +##### O4.02 Personalization + +**Definition**: Adaptation to individual preferences and remembered settings. + +**Include**: +- Remembering customer preferences +- Customization options +- Personal settings saved + +**Exclude**: +- Staff attentiveness (use P3.01) +- Customer recognition (use R4.01) +- Flexibility in modifications (use O4.03) + +**Examples**: +- (+) "Remembered my usual order" +- (+) "Saved my preferences perfectly" +- (-) "No way to save my settings" +- (-) "Had to explain my preferences every time" + +**Common Errors**: +- Confusing with R4.01 (Recognition): R4.01 is "they remember me"; O4.02 is "they remember my preferences" + +##### O4.03 Flexibility + +**Definition**: Ability to modify or adjust the product/service to customer needs. + +**Include**: +- Modification options +- Customization capability +- Willingness to adjust + +**Exclude**: +- Policy flexibility (use V2.04) +- Staff accommodation attitude (use P1) +- Dietary accommodation (use A3.03) + +**Examples**: +- (+) "Happy to substitute ingredients" +- (+) "Easily customizable to my needs" +- (-) "No modifications allowed - take it or leave it" +- (-) "Completely rigid - no flexibility at all" + +**Common Errors**: +- Confusing with V2.04 (Terms Fairness): V2.04 is about policy reasonableness; O4.03 is about product flexibility + +##### O4.04 Appropriateness + +**Definition**: Whether the right solution was provided for the customer's need. + +**Include**: +- Right recommendation for the problem +- Suitable solution selected +- Appropriate service chosen + +**Exclude**: +- Staff knowledge (use P2.01) +- Specification match (use O4.01) +- Wrong item sent (use J3.02) + +**Examples**: +- (+) "Perfect recommendation for my needs" +- (+) "Exactly the right solution" +- (-) "Sold me completely the wrong thing for my needs" +- (-) "Not appropriate for my use case at all" + +**Common Errors**: +- Confusing with P2.01 (Knowledge): P2.01 is about staff knowing products; O4.04 is about the solution's appropriateness + +--- + +#### O Domain Common Errors Summary + +| Error Pattern | Incorrect Code | Correct Code | Key Distinction | +|--------------|----------------|--------------|-----------------| +| "App won't load" | O1.01 | E2.02 | App = digital interface | +| "Website was down" | O1.01 | J3.03 | Downtime = system availability | +| "App is slow" | O1.02 | E2.03 | App performance = digital interface | +| "Broke after a month" | O2.01 | O1.03 | Durability = time-based | +| "Wrong item sent" | O4.01 | J3.02 | Focus on process error vs product mismatch | +| "Feature doesn't exist" | O1.01 | O3.02 | Non-existence vs broken | + +--- + +### 3.2 Domain P: People + +**Definition**: Human interactions and personnel behavior during the customer experience. + +**Core Question**: How do the people we interact with treat us and perform their roles? + +**Default Owner**: HR / Training + +**Scope**: +- Staff attitude, demeanor, and emotional tone +- Employee competence, knowledge, and skill +- Responsiveness, attentiveness, and follow-through +- Communication quality and style + +**NOT in Scope**: +- Organizational trust patterns (R domain) +- Process/operational issues (J domain) +- Product quality outcomes (O domain) + +--- + +#### P1: Attitude + +**Category Definition**: Disposition, manner, and emotional tone of personnel. + +##### P1.01 Warmth/Friendliness + +**Definition**: Approachability, pleasantness, and welcoming demeanor. + +**Include**: +- Friendly greetings and interactions +- Welcoming behavior +- Pleasant demeanor +- Kind and nice treatment + +**Exclude**: +- Relationship building over time (use R4.03) +- Professional conduct (use P2.04) +- Respect for dignity (use P1.02) + +**Examples**: +- (+) "So welcoming and kind from the moment I walked in" +- (+) "Sarah at the front desk was incredibly friendly" +- (-) "Cold and unfriendly - made me feel unwelcome" +- (-) "Staff seemed bothered by my presence" + +**Common Errors**: +- Confusing with R4.03 (Relationship Building): R4.03 is ongoing investment in connection; P1.01 is single-interaction warmth + +##### P1.02 Respect + +**Definition**: Treating the customer with dignity and consideration. + +**Include**: +- Making customer feel valued +- Treating with courtesy +- Not talking down or dismissing +- Showing consideration + +**Exclude**: +- Identity-based discrimination (use A3.05) +- Communication tone (use P4.05) +- Professionalism violations (use P2.04) + +**Examples**: +- (+) "Made me feel valued as a customer" +- (+) "Treated me with complete respect and dignity" +- (-) "Talked down to me like I was stupid" +- (-) "Dismissive and condescending attitude" + +**Common Errors**: +- Confusing with A3.05 (Equal Treatment): Use A3.05 when identity-based discrimination is perceived ("treated differently because of X"). Use P1.02 for general disrespect without identity framing. + +##### P1.03 Empathy + +**Definition**: Understanding and acknowledging the customer's situation and feelings. + +**Include**: +- Understanding frustration +- Showing they "get it" +- Emotional connection +- Acknowledging feelings + +**Exclude**: +- Listening skills (use P4.02) +- Problem-solving ability (use P2.03) +- Apologies for issues (use R3.02) + +**Examples**: +- (+) "Really understood my frustration and showed they cared" +- (+) "Could tell she genuinely felt for my situation" +- (-) "Couldn't care less about my problem" +- (-) "No understanding of what I was going through" + +**Common Errors**: +- Confusing with P4.02 (Listening): P4.02 is cognitive processing; P1.03 is emotional understanding + +##### P1.04 Patience + +**Definition**: Tolerance, calm under pressure, and not rushing the customer. + +**Include**: +- Taking time with customers +- Not showing frustration +- Staying calm when pressed +- Allowing customers to take their time + +**Exclude**: +- Appropriate pacing of service (use J1.05) +- Professional conduct (use P2.04) +- Enthusiasm level (use P1.05) + +**Examples**: +- (+) "Never rushed me, took all the time I needed" +- (+) "So patient with all my questions" +- (-) "Visibly annoyed that I was taking time" +- (-) "Kept sighing and checking the clock" + +**Common Errors**: +- Confusing with J1.05 (Pacing): J1.05 is service timing; P1.04 is staff patience with customer + +##### P1.05 Enthusiasm + +**Definition**: Energy, genuine interest, and passion in helping. + +**Include**: +- Showing excitement about helping +- Genuine interest in the work +- Energy and engagement +- Passion for service + +**Exclude**: +- Staff experience level (use P2.05) +- Friendliness (use P1.01) +- Initiative (use P3.02) + +**Examples**: +- (+) "Passionate about helping - you could tell he loved his job" +- (+) "Genuinely excited to help me find the right solution" +- (-) "Just going through the motions" +- (-) "Zero enthusiasm - felt like a burden to them" + +**Common Errors**: +- Confusing with P1.01 (Warmth): P1.01 is friendly demeanor; P1.05 is energy and passion + +--- + +#### P2: Competence + +**Category Definition**: Knowledge, skill, and professional capability of personnel. + +##### P2.01 Knowledge + +**Definition**: Understanding of products, services, policies, and domain expertise. + +**Include**: +- Product knowledge +- Policy understanding +- Technical knowledge +- Industry expertise + +**Exclude**: +- Documentation availability (use O3.04) +- Problem-solving ability (use P2.03) +- Technical execution skill (use P2.02) + +**Examples**: +- (+) "Knew every detail about the product line" +- (+) "Incredibly knowledgeable about the options" +- (-) "Couldn't answer basic questions" +- (-) "Had no idea what they were talking about" + +**Common Errors**: +- Confusing with P2.03 (Problem-Solving): P2.01 is having knowledge; P2.03 is applying it to solve problems + +##### P2.02 Technical Skill + +**Definition**: Ability to perform required tasks competently. + +**Include**: +- Execution quality +- Technical proficiency +- Skilled performance +- Task completion ability + +**Exclude**: +- Product craftsmanship (use O2.02) +- Knowledge of products (use P2.01) +- Professional conduct (use P2.04) + +**Examples**: +- (+) "Masterful technique - clearly an expert" +- (+) "Flawless execution of the procedure" +- (-) "Clearly undertrained - made multiple mistakes" +- (-) "Fumbled through the whole process" + +**Common Errors**: +- Confusing with O2.02 (Craftsmanship): P2.02 is the person's skill; O2.02 is the resulting product's quality + +##### P2.03 Problem-Solving + +**Definition**: Ability to address issues, find solutions, and overcome obstacles. + +**Include**: +- Finding creative solutions +- Overcoming obstacles +- Resolving issues effectively +- Troubleshooting ability + +**Exclude**: +- Resolution process (use J4.02) +- Taking ownership (use R3.05) +- Following through (use P3.04) + +**Examples**: +- (+) "Found a creative solution to my problem" +- (+) "Figured out a workaround when the first approach failed" +- (-) "Just said 'can't help you' and gave up" +- (-) "No ability to think outside the box" + +**Common Errors**: +- Confusing with J4.02 (Resolution Process): J4.02 is the operational process; P2.03 is the individual's problem-solving ability + +##### P2.04 Professionalism + +**Definition**: Appropriate conduct, appearance, and adherence to professional standards. + +**Include**: +- Professional behavior +- Appropriate appearance +- Following professional norms +- Proper conduct + +**Exclude**: +- Respect for customers (use P1.02) +- Technical skill (use P2.02) +- Communication tone (use P4.05) + +**Examples**: +- (+) "Very professional throughout the interaction" +- (+) "Impeccable professionalism - exactly what you'd expect" +- (-) "Inappropriate jokes that made me uncomfortable" +- (-) "Showed up in dirty clothes, on personal phone the whole time" + +**Common Errors**: +- Confusing with P1.02 (Respect): P1.02 is treating customer with dignity; P2.04 is professional conduct standards + +##### P2.05 Experience + +**Definition**: Depth of expertise demonstrated through seasoned performance. + +**Include**: +- Expert-level performance +- Seasoned professional feel +- Years of experience evident +- Depth of expertise + +**Exclude**: +- Organizational track record (use R2.01) +- Technical skill (use P2.02) +- Knowledge breadth (use P2.01) + +**Examples**: +- (+) "Clearly an expert with years of experience" +- (+) "You could tell this wasn't their first rodeo" +- (-) "Felt like talking to a complete beginner" +- (-) "Obvious they were new and unsure" + +**Common Errors**: +- Confusing with R2.01 (Track Record): R2.01 is organizational history; P2.05 is individual experience + +--- + +#### P3: Responsiveness + +**Category Definition**: Attentiveness, initiative, and follow-through in meeting customer needs. + +##### P3.01 Attentiveness + +**Definition**: Awareness of customer needs and proactive checking in. + +**Include**: +- Noticing customer needs +- Checking in regularly +- Being aware of situation +- Anticipating needs + +**Exclude**: +- Personalization of product (use O4.02) +- Proactive information sharing (use P3.02) +- Staff availability (use P3.03) + +**Examples**: +- (+) "Always checking in to see if we needed anything" +- (+) "Noticed I was looking for help before I even asked" +- (-) "Had to flag them down every time I needed something" +- (-) "Completely oblivious to our needs" + +**Common Errors**: +- Confusing with O4.02 (Personalization): O4.02 is product customization; P3.01 is staff awareness + +##### P3.02 Initiative + +**Definition**: Proactive assistance without being asked. + +**Include**: +- Offering help unprompted +- Going beyond asked duties +- Proactive suggestions +- Volunteering assistance + +**Exclude**: +- Proactive communication (use P4.03) +- Urgency in handling (use P3.05) +- Attentiveness (use P3.01) + +**Examples**: +- (+) "Offered help without me having to ask" +- (+) "Proactively suggested options I hadn't considered" +- (-) "Did the absolute bare minimum" +- (-) "Wouldn't lift a finger unless specifically asked" + +**Common Errors**: +- Confusing with P4.03 (Proactive Updates): P4.03 is communication; P3.02 is action/assistance + +##### P3.03 Availability + +**Definition**: Presence and accessibility when the customer needs assistance. + +**Include**: +- Being present when needed +- Easy to find or reach +- Accessible for help +- Available to assist + +**Exclude**: +- Staffing levels (use A1.04) +- Operating hours (use A1.01) +- Response time (use J1.03) + +**Examples**: +- (+) "Easy to find someone whenever I needed help" +- (+) "Staff was always available and accessible" +- (-) "Impossible to find anyone to help" +- (-) "Could never get anyone on the phone" + +**Common Errors**: +- Confusing with A1.04 (Staffing Levels): A1.04 is organizational staffing; P3.03 is individual staff availability + +##### P3.04 Follow-Through + +**Definition**: Completing promised or implied actions from an interaction. + +**Include**: +- Doing what they said they'd do +- Completing promised callbacks +- Following up as promised +- Delivering on stated commitments + +**Exclude**: +- Organizational promise keeping (use R1.02) +- Resolution speed (use J4.03) +- Response time (use J1.03) + +**Examples**: +- (+) "Did exactly what they promised - called back right on time" +- (+) "Followed through on every commitment" +- (-) "Said they'd call back within 24 hours - never did" +- (-) "Promised to email the quote - nothing came" + +**Common Errors**: +- **Critical Distinction**: Use P3.04 for a specific interaction ("said they'd call back, didn't"). Use R1.02 when framed as trust/pattern ("they never keep their word"). + +##### P3.05 Urgency + +**Definition**: Appropriate prioritization and sense of importance given to customer needs. + +**Include**: +- Treating as priority +- Showing importance +- Acting with appropriate speed +- Prioritizing the issue + +**Exclude**: +- Response time metrics (use J1.03) +- Service speed (use J1.02) +- Patience with customer (use P1.04) + +**Examples**: +- (+) "Treated my issue as a priority" +- (+) "Could tell they understood the urgency" +- (-) "No sense of urgency at all" +- (-) "Acted like they had all the time in the world while I waited" + +**Common Errors**: +- Confusing with J1.03 (Response Time): J1.03 is measured time; P3.05 is perceived prioritization + +--- + +#### P4: Communication + +**Category Definition**: Quality of information exchange with personnel. + +##### P4.01 Clarity + +**Definition**: Understandable, clear information delivery. + +**Include**: +- Clear explanations +- Understandable language +- Well-communicated information +- Easy to follow + +**Exclude**: +- Documentation quality (use O3.04) +- Listening skills (use P4.02) +- Information accuracy (use P4.04) + +**Examples**: +- (+) "Explained everything clearly in plain language" +- (+) "Made complex topics easy to understand" +- (-) "Used confusing jargon I couldn't follow" +- (-) "Explanation made no sense at all" + +**Common Errors**: +- Confusing with O3.04 (Documentation): O3.04 is written materials; P4.01 is verbal/personal communication + +##### P4.02 Listening + +**Definition**: Hearing, understanding, and processing what the customer says. + +**Include**: +- Actually hearing what's said +- Understanding the message +- Not interrupting +- Processing customer input + +**Exclude**: +- Empathy for feelings (use P1.03) +- Taking action on input (use P2.03) +- Proactive updates (use P4.03) + +**Examples**: +- (+) "Really heard what I was saying" +- (+) "Listened carefully to my whole situation" +- (-) "Kept interrupting me" +- (-) "Just read from a script - didn't hear a word I said" + +**Common Errors**: +- Confusing with P1.03 (Empathy): P4.02 is cognitive processing; P1.03 is emotional understanding + +##### P4.03 Proactive Updates + +**Definition**: Keeping the customer informed without being asked. + +**Include**: +- Status updates +- Progress communication +- Information without prompting +- Keeping informed + +**Exclude**: +- Problem acknowledgment (use J4.01) +- Initiative to help (use P3.02) +- Handoff communication (use J2.04) + +**Examples**: +- (+) "Regular status updates throughout the process" +- (+) "Kept me informed every step of the way" +- (-) "Radio silence for weeks - had to chase them" +- (-) "Never heard anything until I called to ask" + +**Common Errors**: +- Confusing with J4.01 (Problem Acknowledgment): J4.01 is recognizing an issue; P4.03 is ongoing communication + +##### P4.04 Accuracy + +**Definition**: Correctness of information provided by staff. + +**Include**: +- Correct information given +- Accurate details shared +- Truthful in communication +- Reliable information + +**Exclude**: +- Honest representation (use V2.05) +- Truthfulness as character (use R1.01) +- Process accuracy (use J3.02) + +**Examples**: +- (+) "Everything they told me was completely accurate" +- (+) "Information was spot-on - no surprises" +- (-) "Given completely wrong information" +- (-) "What they said turned out to be false" + +**Common Errors**: +- Confusing with R1.01 (Truthfulness): R1.01 is organizational honesty pattern; P4.04 is specific information accuracy + +##### P4.05 Tone + +**Definition**: Appropriate communication style and manner of delivery. + +**Include**: +- Tone of voice +- Communication style +- Manner of speaking +- Delivery approach + +**Exclude**: +- Respect for dignity (use P1.02) +- Clarity of message (use P4.01) +- Professionalism (use P2.04) + +**Examples**: +- (+) "Professional but warm tone throughout" +- (+) "Perfect balance of friendly and businesslike" +- (-) "Condescending tone that made me feel small" +- (-) "Sarcastic and dismissive in how they spoke" + +**Common Errors**: +- Confusing with P1.02 (Respect): P1.02 is about treating with dignity; P4.05 is about communication style + +--- + +#### P Domain Common Errors Summary + +| Error Pattern | Incorrect Code | Correct Code | Key Distinction | +|--------------|----------------|--------------|-----------------| +| "They never keep promises" | P3.04 | R1.02 | Pattern = R; Instance = P | +| "Felt discriminated against" | P1.02 | A3.05 | Identity-based = A3.05 | +| "Product was poorly made" | P2.02 | O2.02 | Product outcome = O | +| "Always friendly over years" | P1.01 | R4.03 | Long-term = R | +| "Understood my feelings" | P4.02 | P1.03 | Emotional = Empathy | +| "Took weeks to reply" | P3.04 | J1.03 | Time metric = J | + +--- + +### 3.3 Domain J: Journey + +**Definition**: The process, timing, and operational flow of the customer experience. + +**Core Question**: Is the experience smooth, timely, and friction-free? + +**Default Owner**: Operations / Process + +**Scope**: +- Timing: waiting, speed, punctuality +- Ease: simplicity, friction, handoffs +- Reliability: consistency, accuracy, uptime +- Resolution: problem handling and fixes + +**NOT in Scope**: +- Staff behavior during process (P domain) +- The product/service itself (O domain) +- Environmental factors (E domain) + +--- + +#### J1: Timing + +**Category Definition**: Speed, punctuality, and time management aspects of the experience. + +##### J1.01 Wait Time + +**Definition**: Time spent waiting for service to begin. + +**Include**: +- Queue wait times +- Time past appointment +- Waiting to be served +- Delay before service starts + +**Exclude**: +- Booking access difficulty (use A1.02) +- Service delivery speed (use J1.02) +- Resolution speed (use J4.03) + +**Examples**: +- (+) "Seated immediately - no wait at all" +- (+) "Seen right at my appointment time" +- (-) "45 minutes past my appointment and still waiting" +- (-) "Hour-long wait just to be seen" + +**Common Errors**: +- Confusing with A1.02 (Booking Access): A1.02 is getting the appointment; J1.01 is waiting at the appointment + +##### J1.02 Service Speed + +**Definition**: Time for delivery or completion of the service/product. + +**Include**: +- Delivery speed +- How long the service took +- Production time +- Completion duration + +**Exclude**: +- Resolution/fix speed (use J4.03) +- Wait before service (use J1.01) +- Response to inquiries (use J1.03) + +**Examples**: +- (+) "Next day delivery - impressively fast" +- (+) "Completed the work in record time" +- (-) "Took three weeks to arrive" +- (-) "Service took way longer than quoted" + +**Common Errors**: +- Confusing with J4.03 (Resolution Speed): J1.02 is initial delivery; J4.03 is fixing problems + +##### J1.03 Response Time + +**Definition**: Time to address inquiries, questions, or requests. + +**Include**: +- Reply speed to messages +- Call back time +- Response to inquiries +- Time to answer questions + +**Exclude**: +- Staff urgency demeanor (use P3.05) +- Service delivery (use J1.02) +- Wait at location (use J1.01) + +**Examples**: +- (+) "Replied to my email in minutes" +- (+) "Called back within the hour as promised" +- (-) "Days to get any response" +- (-) "Waited on hold for an hour" + +**Common Errors**: +- Confusing with P3.05 (Urgency): P3.05 is staff demeanor; J1.03 is actual time measurement + +##### J1.04 Punctuality + +**Definition**: Meeting scheduled times and appointments. + +**Include**: +- Being on time +- Meeting schedules +- Arriving as promised +- Schedule adherence + +**Exclude**: +- Consistency over time (use R2.02) +- Wait time (use J1.01) +- Service speed (use J1.02) + +**Examples**: +- (+) "Always arrives exactly on time" +- (+) "Technician showed up at the scheduled time" +- (-) "Two hours late with no notice" +- (-) "Never on time - always running behind" + +**Common Errors**: +- Confusing with R2.02 (Consistency): R2.02 is overall dependability pattern; J1.04 is schedule adherence + +##### J1.05 Pacing + +**Definition**: Appropriate speed of service - not too rushed or too slow. + +**Include**: +- Service feels appropriately timed +- Not being rushed through +- Not dragging on +- Natural flow of timing + +**Exclude**: +- Staff patience (use P1.04) +- Wait times (use J1.01) +- Service speed (use J1.02) + +**Examples**: +- (+) "Perfect timing - never felt rushed" +- (+) "Let us enjoy our meal without hovering" +- (-) "Rushed us out like they needed the table" +- (-) "Dragged on forever - felt like it would never end" + +**Common Errors**: +- Confusing with P1.04 (Patience): P1.04 is staff's patience with customer; J1.05 is timing of service delivery + +--- + +#### J2: Ease + +**Category Definition**: Effort required and friction encountered in the process. + +##### J2.01 Simplicity + +**Definition**: Straightforward, uncomplicated processes. + +**Include**: +- Easy processes +- Simple procedures +- Uncomplicated steps +- Streamlined experience + +**Exclude**: +- Interface navigation (use E2.04) +- Physical layout (use E1.03) +- Mental effort (use V3.02) + +**Examples**: +- (+) "So easy to do - couldn't be simpler" +- (+) "Straightforward process from start to finish" +- (-) "Needlessly complicated - way too many steps" +- (-) "Why do they make it so hard?" + +**Common Errors**: +- **J2 vs E2 Rule**: J2.01 = effort/friction in the process itself ("too many steps"). E2.04 = qualities of the digital interface ("buttons don't work"). + +##### J2.02 Navigation + +**Definition**: Finding what's needed within a process or location. + +**Include**: +- Finding things easily +- Locating information +- Following the process +- Getting to the right place + +**Exclude**: +- Physical layout (use E1.03) +- Interface navigation (use E2.04) +- Signage quality (use E1.05) + +**Examples**: +- (+) "Found exactly what I needed right away" +- (+) "Easy to navigate through the options" +- (-) "Couldn't find anything - totally lost" +- (-) "Took forever to figure out where to go" + +**Common Errors**: +- Confusing with E2.04 (Interface Navigation): E2.04 is digital interface; J2.02 is process/location finding + +##### J2.03 Paperwork/Forms + +**Definition**: Documentation burden and form-filling requirements. + +**Include**: +- Amount of paperwork +- Form complexity +- Documentation requirements +- Bureaucratic burden + +**Exclude**: +- Mental effort (use V3.02) +- Process simplicity (use J2.01) +- Documentation provided (use O3.04) + +**Examples**: +- (+) "Minimal paperwork - just a few fields" +- (+) "Quick online form took 2 minutes" +- (-) "Endless paperwork - filled out the same info five times" +- (-) "Mountains of forms to complete" + +**Common Errors**: +- Confusing with V3.02 (Mental Effort): V3.02 is cognitive load; J2.03 is specifically paperwork burden + +##### J2.04 Handoffs + +**Definition**: Transitions between steps, people, or departments. + +**Include**: +- Transfers between departments +- Handoff quality +- Transition smoothness +- Information passing between staff + +**Exclude**: +- Proactive updates (use P4.03) +- Team dynamics issues (use CD-T causal) +- Resolution process (use J4.02) + +**Examples**: +- (+) "Seamless transfer between departments" +- (+) "Next person knew exactly what was going on" +- (-) "Transferred to 4 departments - explained from scratch each time" +- (-) "Every handoff lost my information" + +**Common Errors**: +- Confusing with J4.02 (Resolution Process): J4.02 is problem-fixing process; J2.04 is general handoff quality + +##### J2.05 Self-Service + +**Definition**: Customer autonomy and self-service options available. + +**Include**: +- Online portals +- Self-checkout options +- DIY capabilities +- Autonomous options + +**Exclude**: +- Digital functionality (use E2.02) +- Contact options (use A4.05) +- Staff availability (use P3.03) + +**Examples**: +- (+) "Great online portal - did everything myself" +- (+) "Easy self-service kiosk" +- (-) "Forced to call for everything" +- (-) "No way to do anything online" + +**Common Errors**: +- Confusing with E2.02 (Digital Functionality): E2.02 is whether features work; J2.05 is whether self-service exists + +--- + +#### J3: Reliability + +**Category Definition**: Consistency and predictability of the process. + +##### J3.01 Consistency + +**Definition**: Same result delivered each time - process-level consistency. + +**Include**: +- Reliable outcomes each visit +- Consistent experience +- Same quality repeatedly +- Predictable results + +**Exclude**: +- Product reliability (use O1.04) +- Organizational dependability (use R2.02) +- Order accuracy (use J3.02) + +**Examples**: +- (+) "Always reliable - same great experience every time" +- (+) "Consistently excellent across many visits" +- (-) "Hit or miss quality - never know what you'll get" +- (-) "Totally inconsistent - varies wildly" + +**Common Errors**: +- **Key Distinction**: J3.01 = process delivers same result each time. O1.04 = the product itself works consistently. "Pizza is always good" = J3.01. "Phone always connects" = O1.04. + +##### J3.02 Accuracy + +**Definition**: Correct execution of requests and orders. + +**Include**: +- Order accuracy +- Correct fulfillment +- Request execution +- Right item/service delivered + +**Exclude**: +- Specification match (use O4.01) +- Information accuracy (use P4.04) +- Error frequency (use J3.05) + +**Examples**: +- (+) "Order exactly right - everything perfect" +- (+) "Got exactly what I asked for" +- (-) "Wrong items delivered" +- (-) "They messed up my order completely" + +**Common Errors**: +- Confusing with O4.01 (Specification Match): J3.02 = "They made a mistake"; O4.01 = "This isn't right for me" + +##### J3.03 Availability + +**Definition**: System and service uptime - whether the service is accessible. + +**Include**: +- System uptime +- Service availability +- Outages and downtime +- Platform accessibility + +**Exclude**: +- Product functionality (use O1.01) +- Inventory availability (use A1.03) +- Staff availability (use P3.03) + +**Examples**: +- (+) "Never goes down - always available" +- (+) "System is rock solid - never experienced an outage" +- (-) "Constant outages - can never access when I need it" +- (-) "Website was down for maintenance all weekend" + +**Common Errors**: +- Confusing with O1.01 (Works/Doesn't Work): O1.01 = product is broken; J3.03 = service is unavailable + +##### J3.04 Predictability + +**Definition**: Expectations being matched - knowing what to expect. + +**Include**: +- No surprises +- Expected outcomes +- Clear expectations met +- Known experience + +**Exclude**: +- Pricing clarity (use V2.01) +- Process consistency (use J3.01) +- Communication clarity (use P4.01) + +**Examples**: +- (+) "No surprises - exactly what I expected" +- (+) "Predictable experience every time" +- (-) "Never know what to expect" +- (-) "Completely different from what I was told" + +**Common Errors**: +- Confusing with V2.01 (Pricing Clarity): V2.01 is about understanding costs; J3.04 is general predictability + +##### J3.05 Error Rate + +**Definition**: Frequency of mistakes and problems. + +**Include**: +- How often mistakes happen +- Pattern of errors +- Frequency of issues +- Recurring problems + +**Exclude**: +- Dependability pattern (use R2.02) +- Single accuracy issue (use J3.02) +- Consistency of quality (use J3.01) + +**Examples**: +- (+) "Rarely makes mistakes - highly reliable" +- (+) "In dozens of orders, never a single error" +- (-) "Something wrong every single time" +- (-) "Constant mistakes - can't get it right" + +**Common Errors**: +- Confusing with R2.02 (Consistency): R2.02 is overall dependability; J3.05 is specifically error frequency + +--- + +#### J4: Resolution + +**Category Definition**: How problems are handled when they arise. + +##### J4.01 Problem Acknowledgment + +**Definition**: Recognition that an issue exists - operational acknowledgment. + +**Include**: +- Recognizing the problem +- Accepting there's an issue +- Confirming the complaint +- Noting the problem exists + +**Exclude**: +- Admitting fault (use R3.01) +- Taking responsibility (use R3.05) +- Apology (use R3.02) + +**Examples**: +- (+) "Immediately recognized there was a problem" +- (+) "Confirmed the issue right away" +- (-) "Denied there was any problem" +- (-) "Wouldn't even acknowledge the issue" + +**Common Errors**: +- **Critical Distinction**: J4.01 = "Yes, there's a problem" (operational). R3.01 = "Yes, we were wrong" (accountability). + +##### J4.02 Resolution Process + +**Definition**: How problems are handled operationally. + +**Include**: +- Steps to resolve +- Escalation process +- Handling procedures +- Fix workflow + +**Exclude**: +- Staff problem-solving ability (use P2.03) +- Compensation offered (use R3.03) +- Resolution speed (use J4.03) + +**Examples**: +- (+) "Clear escalation path to resolution" +- (+) "Smooth process to get it fixed" +- (-) "Transferred in circles - nobody could help" +- (-) "No process at all - just chaos" + +**Common Errors**: +- Confusing with P2.03 (Problem-Solving): P2.03 is individual ability; J4.02 is organizational process + +##### J4.03 Resolution Speed + +**Definition**: Time taken to fix problems. + +**Include**: +- Speed of fix +- How long to resolve +- Time to solution +- Fix turnaround + +**Exclude**: +- Initial service speed (use J1.02) +- Response time (use J1.03) +- Resolution quality (use J4.04) + +**Examples**: +- (+) "Fixed the same day" +- (+) "Problem resolved within hours" +- (-) "Took weeks to resolve" +- (-) "Still waiting after a month" + +**Common Errors**: +- Confusing with J1.02 (Service Speed): J1.02 is initial delivery; J4.03 is problem-fixing speed + +##### J4.04 Resolution Quality + +**Definition**: Adequacy and completeness of the solution provided. + +**Include**: +- Quality of the fix +- Completeness of resolution +- Whether issue is truly resolved +- Adequacy of solution + +**Exclude**: +- Compensation (use R3.03) +- Prevention of recurrence (use J4.05) +- Scope completion (use O3.03) + +**Examples**: +- (+) "Completely fixed - problem gone" +- (+) "Perfect solution that addressed everything" +- (-) "Band-aid fix that didn't last" +- (-) "Issue wasn't really resolved" + +**Common Errors**: +- Confusing with R3.03 (Compensation): J4.04 = was it fixed? R3.03 = did they make amends? + +##### J4.05 Prevention + +**Definition**: Efforts to prevent the problem from recurring. + +**Include**: +- Process changes made +- Steps to prevent recurrence +- Systemic fixes implemented +- Learning from issues + +**Exclude**: +- Organizational improvement commitment (use R3.04) +- Resolution quality (use J4.04) +- Problem acknowledgment (use J4.01) + +**Examples**: +- (+) "Changed their process so it won't happen again" +- (+) "Implemented safeguards to prevent future issues" +- (-) "Same issue happened again next visit" +- (-) "No effort to prevent recurrence" + +**Common Errors**: +- Confusing with R3.04 (Improvement): J4.05 = process change made; R3.04 = organizational commitment to improve + +--- + +#### J4 vs R3: Process vs Ownership + +This is one of the most critical disambiguations in URT: + +| Aspect | J4 (Resolution) | R3 (Recovery) | +|--------|-----------------|---------------| +| **Focus** | What they did to fix it | How they took responsibility | +| **Question** | Was the fix adequate? | Did they own it and make amends? | +| **Owner** | Operations | Leadership | + +**Decision Guide**: +- Mechanics of fixing → J4 +- Accountability and relationship repair → R3 + +| Example Span | Primary Code | Rationale | +|--------------|--------------|-----------| +| "They sent a replacement quickly" | J4.02/J4.03 | Process focus | +| "They sincerely apologized" | R3.02 | Accountability focus | +| "Owned their mistake" | R3.01 | Admitting fault | +| "Transferred me 4 times" | J4.02 | Process dysfunction | +| "Offered nothing for my trouble" | R3.03 | Compensation failure | + +--- + +#### J Domain Common Errors Summary + +| Error Pattern | Incorrect Code | Correct Code | Key Distinction | +|--------------|----------------|--------------|-----------------| +| "Booking was hard to get" | J1.01 | A1.02 | Getting appointment = A | +| "Interface was confusing" | J2.01 | E2.04 | Digital interface = E | +| "Product sometimes fails" | J3.01 | O1.04 | Product = O | +| "Website was down" | O1.01 | J3.03 | System availability = J | +| "They apologized" | J4.01 | R3.02 | Apology = R | +| "Never keeps promises" | J4 | R1.02 | Pattern = R | + +--- + +#### Billing/Returns/Refunds Decision Table + +| Feedback Type | Primary Code | Secondary | Rationale | +|---------------|--------------|-----------|-----------| +| "Returns process was easy" | J4.02 | -- | Resolution process ease | +| "Returns process was a nightmare" | J4.02 | -- | Resolution process friction | +| "Refund took too long" | J4.03 | -- | Resolution speed | +| "Refund policy is unfair" | V2.04 | -- | Terms fairness | +| "They refused to refund me" (trust framing) | R3.03 | V2.04 | Compensation failure | +| "Wrong amount refunded" | J3.02 | V1.04 | Accuracy + hidden costs | +| "They honored the warranty" | R2.05 | -- | Guarantee honor | +| "Charged me twice" | J3.02 | -- | Process accuracy | + +--- + +### 3.4 Domain E: Environment + +**Definition**: Physical, digital, and ambient context where the experience occurs. + +**Core Question**: Is the space where the experience occurs functional, safe, and pleasant? + +**Default Owner**: Facilities / IT + +**Scope**: +- Physical spaces: cleanliness, maintenance, layout +- Digital spaces: interface design, functionality, performance +- Ambiance: atmosphere, noise, temperature +- Safety: physical safety, health, security + +**NOT in Scope**: +- Staff behavior in the space (P domain) +- The product itself (O domain) +- Process friction (J domain) + +--- + +#### E1: Physical Space + +**Category Definition**: Tangible environment attributes of the physical space. + +##### E1.01 Cleanliness + +**Definition**: Hygiene, tidiness, and general cleanliness of the space. + +**Include**: +- General cleanliness +- Tidiness of space +- Hygiene appearance +- Clean facilities + +**Exclude**: +- Sanitation protocols (use E4.02) +- Maintenance issues (use E1.02) +- Staff appearance (use P2.04) + +**Examples**: +- (+) "Spotless facilities - incredibly clean" +- (+) "Immaculately maintained space" +- (-) "Filthy bathrooms - disgusting" +- (-) "Dirty tables and floors everywhere" + +**Common Errors**: +- Confusing with E4.02 (Health/Hygiene): E1.01 = general tidiness; E4.02 = sanitation protocols and food safety + +##### E1.02 Maintenance + +**Definition**: Condition and upkeep of equipment and facilities. + +**Include**: +- Working equipment +- Maintained facilities +- Repairs needed/done +- Functional amenities + +**Exclude**: +- Product functionality (use O1.01) +- Equipment quality (use E1.04) +- Cleanliness (use E1.01) + +**Examples**: +- (+) "Everything works perfectly - well maintained" +- (+) "Clearly take pride in upkeep" +- (-) "Broken equipment everywhere" +- (-) "Half the machines don't work" + +**Common Errors**: +- Confusing with O1.01 (Product Function): E1.02 = facility equipment; O1.01 = the product you're buying + +##### E1.03 Layout/Design + +**Definition**: Functional arrangement and design of the physical space. + +**Include**: +- Space arrangement +- Functional design +- Layout effectiveness +- Space organization + +**Exclude**: +- Process navigation (use J2.02) +- Signage (use E1.05) +- Aesthetics (use E3.05) + +**Examples**: +- (+) "Well-designed layout - easy to navigate" +- (+) "Thoughtful space arrangement" +- (-) "Confusing layout - got lost immediately" +- (-) "Poorly designed space - awkward flow" + +**Common Errors**: +- Confusing with J2.02 (Navigation): J2.02 = finding things in a process; E1.03 = physical space design + +##### E1.04 Equipment + +**Definition**: Tools, machines, and amenities available in the space. + +**Include**: +- Quality of equipment +- Modernity of machines +- Available amenities +- Tool condition + +**Exclude**: +- Product performance (use O1.02) +- Equipment maintenance (use E1.02) +- Digital interface (use E2) + +**Examples**: +- (+) "Modern, high-quality equipment throughout" +- (+) "State-of-the-art machines" +- (-) "Outdated equipment from the 90s" +- (-) "Cheap, worn-out machines" + +**Common Errors**: +- Confusing with O1.02 (Product Performance): E1.04 = facility equipment quality; O1.02 = product performance + +##### E1.05 Signage + +**Definition**: Navigation aids, signs, and directional information. + +**Include**: +- Directional signs +- Information displays +- Wayfinding aids +- Posted instructions + +**Exclude**: +- Location accessibility (use A4.01) +- Emergency signage (use E4.05) +- Interface navigation (use E2.04) + +**Examples**: +- (+) "Clear signs everywhere - easy to find anything" +- (+) "Excellent wayfinding throughout" +- (-) "No signs anywhere - completely lost" +- (-) "Confusing and contradictory signage" + +**Common Errors**: +- Confusing with A4.01 (Location): A4.01 = where the business is; E1.05 = signage within the space + +--- + +#### E2: Digital Space + +**Category Definition**: Online and application interface characteristics. + +##### E2.01 Interface Design + +**Definition**: Visual and interaction quality of digital interfaces. + +**Include**: +- Visual design quality +- UI appearance +- Layout of interface +- Aesthetic appeal of digital + +**Exclude**: +- Product presentation (use O2.03) +- Interface functionality (use E2.02) +- Interface speed (use E2.03) + +**Examples**: +- (+) "Beautiful app design - clean and modern" +- (+) "Gorgeous interface - pleasure to use" +- (-) "Cluttered mess - ugly design" +- (-) "Looks like it was made in 2005" + +**Common Errors**: +- Confusing with O2.03 (Product Presentation): O2.03 = product aesthetics; E2.01 = interface aesthetics + +##### E2.02 Functionality + +**Definition**: Whether digital features work correctly. + +**Include**: +- Buttons working +- Features functioning +- App capabilities working +- Website features operational + +**Exclude**: +- Product functionality (use O1.01) +- Interface speed (use E2.03) +- System availability (use J3.03) + +**Examples**: +- (+) "Everything works perfectly - no bugs" +- (+) "All features function as expected" +- (-) "Buttons don't work - totally broken" +- (-) "Half the features are buggy" + +**Common Errors**: +- Confusing with O1.01 (Works/Doesn't Work): O1.01 = core product; E2.02 = app/interface features + +##### E2.03 Performance + +**Definition**: Speed and responsiveness of digital interfaces. + +**Include**: +- App/website speed +- Loading times +- Responsiveness +- Interface lag + +**Exclude**: +- Product performance (use O1.02) +- System uptime (use J3.03) +- Interface design (use E2.01) + +**Examples**: +- (+) "Lightning fast - pages load instantly" +- (+) "Incredibly responsive interface" +- (-) "Painfully slow - takes forever to load" +- (-) "Laggy and unresponsive" + +**Common Errors**: +- **Key Rule**: E2.03 = the interface/app is slow. O1.02 = the core product performs poorly ("car accelerates slowly"). + +##### E2.04 Navigation + +**Definition**: Ease of finding things within digital interfaces. + +**Include**: +- Menu structure +- Finding features +- Digital wayfinding +- Information architecture + +**Exclude**: +- Process simplicity (use J2.01) +- Physical navigation (use E1.03) +- Interface design (use E2.01) + +**Examples**: +- (+) "Intuitive menus - found everything easily" +- (+) "Excellent navigation - nothing is hidden" +- (-) "Buried 5 menus deep" +- (-) "Impossible to find basic features" + +**Common Errors**: +- **J2 vs E2 Rule**: E2.04 = interface navigation specifically. J2.01 = process simplicity generally. + +##### E2.05 Mobile Experience + +**Definition**: Smartphone optimization and mobile usability. + +**Include**: +- Mobile-specific issues +- Phone optimization +- Responsive design +- Mobile app quality + +**Exclude**: +- Digital accessibility (use A2.05) +- General functionality (use E2.02) +- Interface design (use E2.01) + +**Examples**: +- (+) "Works great on my phone" +- (+) "Perfect mobile experience" +- (-) "Completely unusable on mobile" +- (-) "Buttons are tiny, text overlaps on phone" + +**Common Errors**: +- Confusing with A2.05 (Digital Accessibility): A2.05 = assistive technology support; E2.05 = mobile optimization + +--- + +#### E3: Ambiance + +**Category Definition**: Intangible environmental qualities affecting mood and comfort. + +##### E3.01 Atmosphere/Vibe + +**Definition**: Overall mood and feel of the space. + +**Include**: +- Overall vibe +- Mood of space +- General atmosphere +- Feel of the environment + +**Exclude**: +- Staff attitude (use P1) +- Aesthetics (use E3.05) +- Specific elements like noise (use E3.02) + +**Examples**: +- (+) "Calm and relaxing atmosphere" +- (+) "Great vibe - felt welcoming" +- (-) "Stressful, chaotic environment" +- (-) "Depressing atmosphere" + +**Common Errors**: +- Confusing with P1 (Attitude): P1 is staff demeanor; E3.01 is the overall space vibe + +##### E3.02 Noise Level + +**Definition**: Sound environment and acoustic qualities. + +**Include**: +- Volume levels +- Background noise +- Acoustic quality +- Sound environment + +**Exclude**: +- Comfort in general (use E4.04) +- Atmosphere overall (use E3.01) +- Equipment noise (use E1.02) + +**Examples**: +- (+) "Pleasantly quiet - could have conversations" +- (+) "Great acoustics, not too loud" +- (-) "Deafening noise - couldn't hear ourselves" +- (-) "Music was way too loud" + +**Common Errors**: +- Confusing with E3.01 (Atmosphere): E3.01 is general vibe; E3.02 is specifically about sound + +##### E3.03 Temperature/Climate + +**Definition**: Thermal comfort and climate control. + +**Include**: +- Temperature +- Heating/cooling +- Climate comfort +- Thermal environment + +**Exclude**: +- General comfort (use E4.04) +- Atmosphere (use E3.01) +- Equipment (use E1.02) + +**Examples**: +- (+) "Perfect temperature - very comfortable" +- (+) "Great climate control" +- (-) "Freezing cold - couldn't enjoy the meal" +- (-) "Way too hot - no AC" + +**Common Errors**: +- Confusing with E4.04 (Comfort): E4.04 is general physical comfort; E3.03 is specifically temperature + +##### E3.04 Crowding + +**Definition**: Density, personal space, and capacity management. + +**Include**: +- How crowded it feels +- Personal space +- Density of people +- Capacity relative to crowd + +**Exclude**: +- Capacity availability (use A1.03) +- Layout design (use E1.03) +- Atmosphere (use E3.01) + +**Examples**: +- (+) "Plenty of room - never felt crowded" +- (+) "Well-spaced, comfortable density" +- (-) "Packed like sardines" +- (-) "So crowded you couldn't move" + +**Common Errors**: +- Confusing with A1.03 (Capacity): A1.03 = availability of spots; E3.04 = feeling of crowdedness + +##### E3.05 Aesthetics + +**Definition**: Beauty and visual appeal of the space. + +**Include**: +- Decor and design +- Visual beauty +- Artistic elements +- Space attractiveness + +**Exclude**: +- Product presentation (use O2.03) +- Interface design (use E2.01) +- Layout function (use E1.03) + +**Examples**: +- (+) "Beautiful decor - stunning space" +- (+) "Gorgeous restaurant - Instagram-worthy" +- (-) "Depressing, ugly space" +- (-) "Tired decor - needs updating" + +**Common Errors**: +- Confusing with O2.03 (Product Presentation): O2.03 = product aesthetics; E3.05 = space aesthetics + +--- + +#### E4: Safety + +**Category Definition**: Security and wellbeing factors in the environment. + +##### E4.01 Physical Safety + +**Definition**: Protection from physical harm. + +**Include**: +- Feeling safe from harm +- Hazard-free environment +- Physical protection +- Danger prevention + +**Exclude**: +- Physical accessibility (use A2.01) +- Security of property (use E4.03) +- Health/sanitation (use E4.02) + +**Examples**: +- (+) "Felt completely safe the entire time" +- (+) "No safety hazards - well managed" +- (-) "Dangerous conditions - felt unsafe" +- (-) "Tripping hazards everywhere" + +**Common Errors**: +- Confusing with A2.01 (Physical Accessibility): A2.01 = disability accommodation; E4.01 = safety from harm + +##### E4.02 Health/Hygiene + +**Definition**: Sanitation standards and health protocols. + +**Include**: +- Food safety protocols +- Sanitation standards +- Health measures +- Hygiene practices + +**Exclude**: +- General cleanliness (use E1.01) +- Staff professionalism (use P2.04) +- Physical safety (use E4.01) + +**Examples**: +- (+) "Strict hygiene protocols - very reassuring" +- (+) "Impeccable food safety standards" +- (-) "Staff not wearing gloves handling food" +- (-) "Questionable hygiene practices" + +**Common Errors**: +- Confusing with E1.01 (Cleanliness): E1.01 = general tidiness; E4.02 = health/sanitation protocols + +##### E4.03 Security + +**Definition**: Protection of person and property. + +**Include**: +- Property security +- Personal security +- Data security (physical) +- Theft prevention + +**Exclude**: +- Physical safety (use E4.01) +- Trust in organization (use R1) +- Privacy policies (use V2.04) + +**Examples**: +- (+) "Secure facility - felt protected" +- (+) "Great security measures in place" +- (-) "Things were stolen from my car" +- (-) "No security - felt vulnerable" + +**Common Errors**: +- **Data Privacy/Security Rule**: Security incident = E4.03. "I don't trust them with my data" = R1.03/R1.04. Privacy policy = V2.04. + +##### E4.04 Comfort + +**Definition**: Physical ease and wellbeing in the space. + +**Include**: +- Seating comfort +- Physical comfort +- Ergonomic quality +- Bodily ease + +**Exclude**: +- Temperature (use E3.03) +- Atmosphere (use E3.01) +- Crowding (use E3.04) + +**Examples**: +- (+) "Comfortable seating - could sit for hours" +- (+) "Ergonomic and supportive" +- (-) "Torture chairs - my back hurt" +- (-) "Incredibly uncomfortable seating" + +**Common Errors**: +- Confusing with E3 (Ambiance): E4.04 = physical comfort of furniture/seating; E3 = environmental qualities + +##### E4.05 Emergency Readiness + +**Definition**: Preparedness for incidents and emergencies. + +**Include**: +- Emergency exits +- Safety equipment +- Emergency procedures +- Preparedness measures + +**Exclude**: +- Signage (use E1.05) +- Physical safety (use E4.01) +- Security (use E4.03) + +**Examples**: +- (+) "Clear emergency exits marked" +- (+) "Fire extinguishers and first aid visible" +- (-) "No visible safety measures" +- (-) "Emergency exits blocked" + +**Common Errors**: +- Confusing with E1.05 (Signage): E1.05 = general signage; E4.05 = emergency preparedness specifically + +--- + +#### E Domain Common Errors Summary + +| Error Pattern | Incorrect Code | Correct Code | Key Distinction | +|--------------|----------------|--------------|-----------------| +| "Product was ugly" | E3.05 | O2.03 | Product = O | +| "App crashed" | E1.02 | E2.02 | Digital = E2 | +| "Website slow" | O1.02 | E2.03 | Interface = E2 | +| "Staff wasn't wearing gloves" | E1.01 | E4.02 | Sanitation = E4.02 | +| "Screen reader doesn't work" | E2.05 | A2.05 | Accessibility = A | +| "Too many steps online" | E2.04 | J2.01 | Process = J | + +--- + +#### Data Privacy/Security Decision Table + +| Feedback Type | Primary Code | Secondary | Rationale | +|---------------|--------------|-----------|-----------| +| "Security incident occurred" | E4.03 | -- | Security breach | +| "I don't trust them with my data" | R1.03 or R1.04 | E4.03 | Trust + security | +| "Data breach notification" | E4.03 | R1.03 | Security + transparency | +| "Privacy policy concerns" | V2.04 | R1.04 | Terms + ethics | +| "Account was hacked" | E4.03 | -- | Security failure | +| "They sell my data" | R1.04 | V2.04 | Ethics + terms | + +--- + +### 3.5 Domain A: Access + +**Definition**: Availability, accessibility, and inclusivity - whether everyone can participate fully. + +**Core Question**: Can everyone who wants to participate do so fully and fairly? + +**Default Owner**: Compliance / Design + +**Scope**: +- Availability: hours, booking, inventory, staffing +- Accessibility: disability accommodations (physical, visual, hearing, cognitive, digital) +- Inclusivity: language, culture, dietary, family, equal treatment +- Convenience: location, parking, transit, payment, contact options + +**NOT in Scope**: +- Wait times at appointment (J domain) +- Staff behavior (P domain) +- Digital interface design (E domain) + +--- + +#### A Domain Disambiguation + +The Access domain covers three distinct concerns: + +| Category | Focus | Key Question | Example | +|----------|-------|--------------|---------| +| **A1/A4** | Operational convenience | Can I get there, book it, reach it? | "Hard to park," "Never in stock" | +| **A2** | Disability/ability barriers | Can people with disabilities use it? | "No wheelchair ramp" | +| **A3** | Cultural/social inclusion | Does it work for diverse backgrounds? | "English only," "Felt discriminated against" | + +--- + +#### A1: Availability + +**Category Definition**: Can you get the service when you need it? + +##### A1.01 Operating Hours + +**Definition**: When the service is accessible. + +**Include**: +- Business hours +- Hours of operation +- When they're open +- Schedule availability + +**Exclude**: +- Staff availability during hours (use P3.03) +- Booking access (use A1.02) +- System uptime (use J3.03) + +**Examples**: +- (+) "Open 24/7 - perfect for my schedule" +- (+) "Great extended hours on weekends" +- (-) "Banker's hours only - impossible for working people" +- (-) "Only open 9-5 when everyone's at work" + +**Common Errors**: +- Confusing with P3.03 (Staff Availability): A1.01 = business hours; P3.03 = staff present during hours + +##### A1.02 Booking Access + +**Definition**: Ability to schedule appointments or reservations. + +**Include**: +- Appointment availability +- Reservation ability +- Scheduling ease +- Getting an appointment + +**Exclude**: +- Wait time at appointment (use J1.01) +- Online booking interface (use E2.02) +- Response time (use J1.03) + +**Examples**: +- (+) "Easy online booking - got an appointment quickly" +- (+) "Plenty of availability when I needed it" +- (-) "3-month wait just to get an appointment" +- (-) "Impossible to book - always full" + +**Common Errors**: +- **Key Distinction**: A1.02 = getting the appointment. J1.01 = waiting at the appointment. + +##### A1.03 Inventory/Capacity + +**Definition**: Product or service availability - whether it's in stock. + +**Include**: +- Stock availability +- Capacity availability +- Service slots available +- Product in stock + +**Exclude**: +- Feature availability (use O3.02) +- Crowding feeling (use E3.04) +- Staffing levels (use A1.04) + +**Examples**: +- (+) "Always in stock - never disappointed" +- (+) "Plenty of capacity - got in immediately" +- (-) "Perpetually sold out" +- (-) "Never have what I'm looking for" + +**Common Errors**: +- Confusing with O3.02 (Feature Availability): O3.02 = features exist but unavailable; A1.03 = physical stock + +##### A1.04 Staffing Levels + +**Definition**: Adequate personnel available to serve customers. + +**Include**: +- Number of staff +- Staffing adequacy +- Personnel availability +- Team size + +**Exclude**: +- Individual staff availability (use P3.03) +- Wait time caused by understaffing (use J1.01 primary) +- Staff quality (use P2) + +**Examples**: +- (+) "Plenty of staff - well-staffed operation" +- (+) "Always enough people to help" +- (-) "Severely understaffed - one person for everything" +- (-) "Not enough staff to handle the crowd" + +**Common Errors**: +- **Causal Relationship**: If "long wait because understaffed," primary = J1.01 (Wait), secondary = A1.04 (Staffing) + +##### A1.05 Geographic Reach + +**Definition**: Service area coverage - whether they serve your location. + +**Include**: +- Delivery area +- Service coverage +- Geographic availability +- Area served + +**Exclude**: +- Location convenience (use A4.01) +- Availability of service (use A1.03) +- Hours of operation (use A1.01) + +**Examples**: +- (+) "Serves my area - convenient coverage" +- (+) "Wide delivery range" +- (-) "Doesn't serve my neighborhood" +- (-) "Outside their coverage area" + +**Common Errors**: +- Confusing with A4.01 (Location): A4.01 = how convenient to reach; A1.05 = whether they serve the area + +--- + +#### A2: Accessibility (Ability-Based) + +**Category Definition**: Can everyone use it regardless of ability or disability? + +##### A2.01 Physical Accessibility + +**Definition**: Mobility accommodations for people with physical disabilities. + +**Include**: +- Wheelchair access +- Ramps and elevators +- Mobility accommodations +- Physical barrier removal + +**Exclude**: +- Physical safety (use E4.01) +- Layout design (use E1.03) +- Comfort (use E4.04) + +**Examples**: +- (+) "Fully wheelchair accessible - ramps and elevators" +- (+) "Great mobility accommodations throughout" +- (-) "No ramps or elevators - stairs only" +- (-) "Not accessible for wheelchair users" + +**Common Errors**: +- Confusing with E4.01 (Physical Safety): E4.01 = safety from harm; A2.01 = disability access + +##### A2.02 Visual Accessibility + +**Definition**: Accommodations for people with visual impairments. + +**Include**: +- Braille signage +- Large print options +- High contrast +- Visual accommodation + +**Exclude**: +- Interface design (use E2.01) +- Digital accessibility (use A2.05) +- Signage quality (use E1.05) + +**Examples**: +- (+) "Braille menus available" +- (+) "Large print options for everything" +- (-) "No accommodations for visually impaired" +- (-) "Impossible to read for low vision" + +**Common Errors**: +- Confusing with A2.05 (Digital Accessibility): A2.02 = physical visual aids; A2.05 = screen readers etc. + +##### A2.03 Hearing Accessibility + +**Definition**: Accommodations for people with hearing impairments. + +**Include**: +- Captions +- Sign language +- Hearing loop +- Audio accommodations + +**Exclude**: +- Digital functionality (use E2.02) +- Noise levels (use E3.02) +- Communication clarity (use P4.01) + +**Examples**: +- (+) "Captions available on all videos" +- (+) "Sign language interpreter provided" +- (-) "No transcripts available" +- (-) "Videos without captions" + +**Common Errors**: +- Confusing with E3.02 (Noise Level): E3.02 = ambient noise; A2.03 = hearing accessibility features + +##### A2.04 Cognitive Accessibility + +**Definition**: Accommodations for people with cognitive or learning differences. + +**Include**: +- Plain language +- Simple instructions +- Clear communication +- Cognitive accommodations + +**Exclude**: +- Process simplicity (use J2.01) +- Communication clarity (use P4.01) +- Interface navigation (use E2.04) + +**Examples**: +- (+) "Clear, simple language throughout" +- (+) "Easy to understand instructions" +- (-) "Unnecessarily complex - not accessible" +- (-) "Confusing for people with learning differences" + +**Common Errors**: +- Confusing with J2.01 (Simplicity): J2.01 = general process ease; A2.04 = cognitive accessibility specifically + +##### A2.05 Digital Accessibility + +**Definition**: Assistive technology support in digital interfaces. + +**Include**: +- Screen reader compatibility +- WCAG compliance +- Assistive technology support +- Alt text quality + +**Exclude**: +- Mobile experience (use E2.05) +- Interface functionality (use E2.02) +- Interface design (use E2.01) + +**Examples**: +- (+) "Works perfectly with my screen reader" +- (+) "WCAG compliant - fully accessible" +- (-) "Screen reader can't interpret the buttons" +- (-) "Completely inaccessible for blind users" + +**Common Errors**: +- **Key Distinction**: A2.05 = assistive technology (screen readers, etc.). E2.05 = mobile phone optimization. + +--- + +#### A3: Inclusivity (Culture/Identity-Based) + +**Category Definition**: Does it work for people from diverse backgrounds? + +##### A3.01 Language Support + +**Definition**: Multiple language options and language accessibility. + +**Include**: +- Staff language ability +- Translated materials +- Language options +- Multilingual support + +**Exclude**: +- Staff knowledge (use P2.01) +- Communication clarity (use P4.01) +- Cultural sensitivity (use A3.02) + +**Examples**: +- (+) "Staff spoke my language fluently" +- (+) "Materials available in multiple languages" +- (-) "English only - no help for non-English speakers" +- (-) "No signs or menus in my language" + +**Common Errors**: +- Confusing with P2.01 (Knowledge): P2.01 = product knowledge; A3.01 = language capability + +##### A3.02 Cultural Sensitivity + +**Definition**: Respect for cultural backgrounds and customs. + +**Include**: +- Understanding customs +- Cultural awareness +- Respecting traditions +- Cultural accommodation + +**Exclude**: +- General respect (use P1.02) +- Discrimination (use A3.05) +- Religious accommodations (use A3.03) + +**Examples**: +- (+) "Understood and respected our customs" +- (+) "Culturally aware and sensitive" +- (-) "Insensitive comments about my culture" +- (-) "No awareness of cultural differences" + +**Common Errors**: +- Confusing with P1.02 (Respect): P1.02 = general respect; A3.02 = cultural awareness specifically + +##### A3.03 Dietary/Medical + +**Definition**: Accommodations for dietary restrictions and medical needs. + +**Include**: +- Food allergies +- Dietary restrictions +- Medical accommodations +- Health-related needs + +**Exclude**: +- Product flexibility (use O4.03) +- Menu options (use O3.02) +- Health safety (use E4.02) + +**Examples**: +- (+) "Handled my allergies perfectly" +- (+) "Great vegetarian options" +- (-) "No options for dietary restrictions" +- (-) "Couldn't accommodate my allergy" + +**Common Errors**: +- Confusing with O4.03 (Flexibility): O4.03 = general modifications; A3.03 = dietary/medical specifically + +##### A3.04 Family Friendly + +**Definition**: Accommodation for children and families. + +**Include**: +- Kid-friendly options +- Family accommodations +- Children's needs +- Family facilities + +**Exclude**: +- Atmosphere (use E3.01) +- Safety (use E4.01) +- Noise (use E3.02) + +**Examples**: +- (+) "Great for kids - family-friendly" +- (+) "Excellent children's facilities" +- (-) "Not child-friendly at all" +- (-) "No accommodations for families" + +**Common Errors**: +- Confusing with E3.01 (Atmosphere): E3.01 = general vibe; A3.04 = family-specific accommodation + +##### A3.05 Equal Treatment + +**Definition**: Non-discrimination and equal treatment regardless of identity. + +**Include**: +- Discrimination experiences +- Equal treatment +- Bias-based treatment +- Identity-based differential treatment + +**Exclude**: +- General respect (use P1.02) +- Cultural sensitivity (use A3.02) +- Fair dealing (use R1.05) + +**Examples**: +- (+) "Treated exactly the same as everyone else" +- (+) "No differential treatment - felt welcome" +- (-) "Felt discriminated against because of how I looked" +- (-) "Clearly treated differently than other customers" + +**Common Errors**: +- **Key Distinction**: Use A3.05 when identity-based discrimination is perceived ("treated differently because of X"). Use P1.02 for general disrespect without identity framing. + +--- + +#### A4: Convenience + +**Category Definition**: Is it easy to reach and engage with? + +##### A4.01 Location + +**Definition**: Physical accessibility and convenience of location. + +**Include**: +- Location convenience +- Easy to get to +- Geographic convenience +- Physical location + +**Exclude**: +- Geographic reach (use A1.05) +- Parking (use A4.02) +- Transit (use A4.03) + +**Examples**: +- (+) "Convenient location - easy to get to" +- (+) "Right in the center of town" +- (-) "Middle of nowhere - hard to find" +- (-) "Terrible location - not convenient" + +**Common Errors**: +- Confusing with A1.05 (Geographic Reach): A1.05 = whether they serve your area; A4.01 = how convenient the location is + +##### A4.02 Parking + +**Definition**: Vehicle accommodation and parking availability. + +**Include**: +- Parking availability +- Parking convenience +- Parking cost +- Parking ease + +**Exclude**: +- Security of parking (use E4.03) +- Location (use A4.01) +- Transit (use A4.03) + +**Examples**: +- (+) "Easy free parking right in front" +- (+) "Plenty of parking spaces" +- (-) "Parking nightmare - impossible to find spots" +- (-) "Expensive parking adds to cost" + +**Common Errors**: +- Confusing with E4.03 (Security): E4.03 = safety of parked car; A4.02 = availability of parking + +##### A4.03 Transit Access + +**Definition**: Public transportation options for accessing the business. + +**Include**: +- Public transit access +- Bus/train proximity +- Transportation options +- Transit convenience + +**Exclude**: +- Location (use A4.01) +- Parking (use A4.02) +- Geographic reach (use A1.05) + +**Examples**: +- (+) "Right by the subway - easy transit access" +- (+) "Multiple bus lines stop here" +- (-) "No transit options - car required" +- (-) "Far from any public transportation" + +**Common Errors**: +- Confusing with A4.01 (Location): A4.01 = general location convenience; A4.03 = transit specifically + +##### A4.04 Payment Options + +**Definition**: Available methods for payment. + +**Include**: +- Payment methods accepted +- Credit card options +- Digital payment +- Payment flexibility + +**Exclude**: +- Payment flexibility terms (use V1.05) +- Contact options (use A4.05) +- Self-service (use J2.05) + +**Examples**: +- (+) "Takes all payment methods" +- (+) "Apple Pay, cards, everything accepted" +- (-) "Cash only - no cards" +- (-) "Limited payment options" + +**Common Errors**: +- Confusing with V1.05 (Payment Flexibility): V1.05 = payment terms/financing; A4.04 = payment methods + +##### A4.05 Contact Options + +**Definition**: Ways to reach and communicate with the business. + +**Include**: +- Contact methods available +- Communication channels +- Ways to reach them +- Multi-channel options + +**Exclude**: +- Self-service (use J2.05) +- Response time (use J1.03) +- Staff availability (use P3.03) + +**Examples**: +- (+) "Chat, phone, email - all options available" +- (+) "Easy to reach through multiple channels" +- (-) "Phone only - and always on hold" +- (-) "No way to contact them online" + +**Common Errors**: +- Confusing with J2.05 (Self-Service): J2.05 = doing things yourself; A4.05 = reaching the business + +--- + +#### A Domain Common Errors Summary + +| Error Pattern | Incorrect Code | Correct Code | Key Distinction | +|--------------|----------------|--------------|-----------------| +| "Waited an hour at appointment" | A1.02 | J1.01 | Waiting there = J | +| "App doesn't work with screen reader" | E2.02 | A2.05 | Accessibility = A | +| "Staff didn't speak English" | P2.01 | A3.01 | Language = A | +| "Rude to me specifically" | A3.05 | P1.02 | No identity = P | +| "Crowded and uncomfortable" | A1.03 | E3.04 | Feeling crowded = E | +| "Good vegetarian options" | O4.03 | A3.03 | Dietary = A | + +--- + +### 3.6 Domain V: Value + +**Definition**: Cost, pricing, worth, and the fairness of the exchange. + +**Core Question**: Is what I'm giving up fair for what I'm getting? + +**Default Owner**: Finance / Pricing + +**Scope**: +- Price: absolute cost, expectations, market comparison, hidden costs +- Transparency: pricing clarity, fee disclosure, advertising accuracy, terms +- Effort: time, mental load, physical effort, hassle, opportunity cost +- Worth: overall value, quality-price ratio, satisfaction, recommendation + +**NOT in Scope**: +- Organizational ethics/trust patterns (R domain) +- Process friction (J domain) +- Product quality itself (O domain) + +--- + +#### V vs R: The Critical Distinction + +This is one of the most important disambiguations in URT: + +| If the complaint is about... | Use Domain | +|------------------------------|------------| +| The exchange itself (what I got vs. what I paid) | **V** (Value) | +| Their intent to deceive or organizational character | **R** (Relationship) | + +**Criminal metaphor mapping**: +| Word/Phrase | Domain | Reasoning | +|-------------|--------|-----------| +| "scam," "fraud," "crooks" | R1.04 | Character judgment | +| "rip-off," "robbery," "highway robbery" | V4.01 | Exchange complaint | +| "overpriced" | V1.01 or V4.02 | Price/value complaint | + +--- + +#### V1: Price + +**Category Definition**: The monetary cost of the product or service. + +##### V1.01 Absolute Price + +**Definition**: The actual cost itself - is it expensive or cheap? + +**Include**: +- Raw price level +- Cost magnitude +- Expensive/affordable assessments +- Price itself + +**Exclude**: +- Quality-price ratio (use V4.02) +- Comparison to competitors (use V1.03) +- Hidden costs (use V1.04) + +**Examples**: +- (+) "Very affordable prices" +- (+) "Reasonable cost for the area" +- (-) "Outrageously expensive" +- (-) "$25 for a basic salad is ridiculous" + +**Common Errors**: +- Confusing with V4.02 (Quality-Price Ratio): V4.02 includes quality assessment; V1.01 is price alone + +##### V1.02 Price vs Expectation + +**Definition**: How the price compared to what was anticipated. + +**Include**: +- Sticker shock +- Better than expected +- Surprising price +- Expectation vs reality + +**Exclude**: +- Pricing clarity (use V2.01) +- Market comparison (use V1.03) +- Hidden costs (use V1.04) + +**Examples**: +- (+) "Cheaper than I expected" +- (+) "Pleasant surprise on the bill" +- (-) "Major sticker shock" +- (-) "Way more expensive than I thought" + +**Common Errors**: +- Confusing with V2.01 (Pricing Clarity): V2.01 = understanding the price; V1.02 = price vs expectations + +##### V1.03 Price vs Market + +**Definition**: Comparison to competitor pricing. + +**Include**: +- Competitor comparison +- Market positioning +- Relative pricing +- Industry comparison + +**Exclude**: +- Overall value (use V4.01) +- Absolute price (use V1.01) +- Quality-price ratio (use V4.02) + +**Examples**: +- (+) "Best prices in the area" +- (+) "Much cheaper than competitors" +- (-) "Way overpriced compared to alternatives" +- (-) "Competitors charge half as much" + +**Common Errors**: +- Confusing with V4.01 (Overall Value): V1.03 = competitor price comparison; V4.01 = total value assessment + +##### V1.04 Hidden Costs + +**Definition**: Unexpected or undisclosed charges. + +**Include**: +- Surprise fees +- Undisclosed charges +- Unexpected costs +- Add-on fees + +**Exclude**: +- Fee disclosure (use V2.02) +- Terms fairness (use V2.04) +- Absolute price (use V1.01) + +**Examples**: +- (+) "No hidden fees - price as quoted" +- (+) "Transparent pricing, no surprises" +- (-) "Surprise $50 charge at checkout" +- (-) "$15 'service fee' that wasn't mentioned" + +**Common Errors**: +- **Distinction**: V1.04 = the charge itself. V2.02 = the disclosure failure. + +##### V1.05 Payment Flexibility + +**Definition**: Terms and options for payment. + +**Include**: +- Financing options +- Payment plans +- Payment terms +- Credit options + +**Exclude**: +- Payment methods (use A4.04) +- Pricing clarity (use V2.01) +- Terms fairness (use V2.04) + +**Examples**: +- (+) "Great financing options available" +- (+) "Flexible payment plans" +- (-) "All upfront required - no payment plans" +- (-) "Rigid payment terms" + +**Common Errors**: +- Confusing with A4.04 (Payment Options): A4.04 = what methods accepted; V1.05 = payment terms/financing + +--- + +#### V2: Transparency + +**Category Definition**: Clarity and honesty about costs and terms. + +##### V2.01 Pricing Clarity + +**Definition**: Understanding what costs what. + +**Include**: +- Clear pricing +- Easy to understand costs +- Price transparency +- Clear price list + +**Exclude**: +- Predictability (use J3.04) +- Hidden costs (use V1.04) +- Fee disclosure (use V2.02) + +**Examples**: +- (+) "Clear price list - easy to understand" +- (+) "Transparent pricing structure" +- (-) "Impossible to understand the pricing" +- (-) "Confusing cost structure" + +**Common Errors**: +- Confusing with J3.04 (Predictability): J3.04 = general predictability; V2.01 = pricing clarity specifically + +##### V2.02 Fee Disclosure + +**Definition**: Upfront disclosure of all charges and fees. + +**Include**: +- Disclosing all fees +- Transparency about charges +- Upfront about costs +- Full disclosure + +**Exclude**: +- Hidden costs (use V1.04) +- Pricing clarity (use V2.01) +- Terms fairness (use V2.04) + +**Examples**: +- (+) "Full disclosure of all fees upfront" +- (+) "Every charge explained in advance" +- (-) "Fees hidden in fine print" +- (-) "Didn't tell me about extra charges" + +**Common Errors**: +- **Distinction**: V2.02 = the disclosure (or lack thereof). V1.04 = the surprise cost itself. + +##### V2.03 Advertising Accuracy + +**Definition**: Whether marketing matches reality. + +**Include**: +- Advertising vs reality +- Marketing accuracy +- Promotional honesty +- Ads matching product + +**Exclude**: +- Truthfulness as character (use R1.01) +- Honest representation (use V2.05) +- Terms fairness (use V2.04) + +**Examples**: +- (+) "Exactly as advertised" +- (+) "Marketing matched the experience" +- (-) "Total bait and switch" +- (-) "Photos nothing like reality" + +**Common Errors**: +- Confusing with R1.01 (Truthfulness): V2.03 = advertising specifically; R1.01 = organizational honesty pattern + +##### V2.04 Terms Fairness + +**Definition**: Reasonableness of contracts, policies, and terms. + +**Include**: +- Policy fairness +- Contract terms +- Return policies +- Cancellation policies + +**Exclude**: +- Fair dealing (use R1.05) +- Fee disclosure (use V2.02) +- Ethics (use R1.04) + +**Examples**: +- (+) "Fair cancellation policy" +- (+) "Reasonable terms and conditions" +- (-) "Predatory contract terms" +- (-) "Criminal cancellation policy - lose 50% for any reason" + +**Common Errors**: +- Confusing with R1.05 (Fair Dealing): V2.04 = specific policy terms; R1.05 = equitable treatment pattern + +##### V2.05 Honest Representation + +**Definition**: Truthful claims and representations about the product/service. + +**Include**: +- Accurate descriptions +- Truthful claims +- Honest representation +- Not misleading + +**Exclude**: +- Truthfulness as character (use R1.01) +- Advertising (use V2.03) +- Information accuracy (use P4.04) + +**Examples**: +- (+) "Accurate description of the product" +- (+) "What they said matched what I got" +- (-) "Totally misleading description" +- (-) "Not at all what they claimed" + +**Common Errors**: +- **V2 vs R1 Rule**: Use V2 for pricing/terms/advertising specifically. Use R1 for trust/integrity/organizational character framing. + +--- + +#### V3: Effort + +**Category Definition**: Non-monetary costs - time, hassle, mental and physical effort. + +##### V3.01 Time Investment + +**Definition**: Hours required for the experience. + +**Include**: +- Total time required +- Hours spent +- Time commitment +- Duration of engagement + +**Exclude**: +- Wait time (use J1.01) +- Service speed (use J1.02) +- Hassle factor (use V3.04) + +**Examples**: +- (+) "Quick 10 minutes - in and out" +- (+) "Didn't take much time at all" +- (-) "Wasted my whole day" +- (-) "Hours of my life I won't get back" + +**Common Errors**: +- Confusing with J1 (Timing): J1 = wait/service/response times; V3.01 = overall time investment value + +##### V3.02 Mental Effort + +**Definition**: Cognitive load and mental energy required. + +**Include**: +- Thinking required +- Mental energy +- Cognitive load +- Figuring things out + +**Exclude**: +- Process simplicity (use J2.01) +- Paperwork (use J2.03) +- Cognitive accessibility (use A2.04) + +**Examples**: +- (+) "Effortless experience - no thinking required" +- (+) "Easy and stress-free" +- (-) "Exhausting to figure out" +- (-) "Mental gymnastics required" + +**Common Errors**: +- Confusing with J2.01 (Simplicity): J2.01 = process complexity; V3.02 = mental effort as cost + +##### V3.03 Physical Effort + +**Definition**: Bodily exertion required. + +**Include**: +- Physical labor required +- Bodily effort +- Physical demands +- Exertion needed + +**Exclude**: +- Convenience (use A4) +- Location (use A4.01) +- Physical accessibility (use A2.01) + +**Examples**: +- (+) "Delivered right to my door" +- (+) "No heavy lifting required" +- (-) "Had to lug it upstairs myself" +- (-) "Physically exhausting experience" + +**Common Errors**: +- Confusing with A4 (Convenience): A4 = access convenience; V3.03 = physical effort as cost + +##### V3.04 Hassle Factor + +**Definition**: Cumulative frustration and friction. + +**Include**: +- Overall hassle +- Cumulative frustration +- Death by thousand cuts +- Total friction + +**Exclude**: +- Process ease (use J2) +- Mental effort (use V3.02) +- Time investment (use V3.01) + +**Examples**: +- (+) "Smooth, hassle-free experience" +- (+) "So easy - no friction at all" +- (-) "Death by a thousand cuts" +- (-) "Everything was a hassle" + +**Common Errors**: +- Confusing with J2 (Ease): J2 = process ease; V3.04 = cumulative hassle as cost + +##### V3.05 Opportunity Cost + +**Definition**: What else could have been done with the time/resources. + +**Include**: +- Worth the trip +- Could have done something else +- Trade-off assessment +- Alternative use of time + +**Exclude**: +- Overall value (use V4.01) +- Time investment (use V3.01) +- Satisfaction (use V4.03) + +**Examples**: +- (+) "Worth every minute of the drive" +- (+) "Glad I made the trip" +- (-) "Not worth the drive" +- (-) "Could have done better things with my time" + +**Common Errors**: +- Confusing with V4.01 (Overall Value): V4.01 = total value; V3.05 = opportunity cost specifically + +--- + +#### V4: Worth + +**Category Definition**: Overall value assessment of the exchange. + +##### V4.01 Overall Value + +**Definition**: Total assessment of value received. + +**Include**: +- Worth it or not +- Value received +- Overall value judgment +- "Rip-off" language + +**Exclude**: +- Absolute price (use V1.01) +- Quality-price ratio (use V4.02) +- Ethics judgment (use R1.04 for "scam") + +**Examples**: +- (+) "Excellent value - totally worth it" +- (+) "Great value for what you get" +- (-) "Total rip-off" +- (-) "Not worth the money" + +**Common Errors**: +- **Critical Rule**: "Rip-off" = V4.01 (exchange complaint). "Scam" = R1.04 (character judgment). + +##### V4.02 Quality-Price Ratio + +**Definition**: What you get for what you pay. + +**Include**: +- Quality relative to price +- Value for money +- What you get vs. cost +- Price-quality balance + +**Exclude**: +- Product quality (use O2) +- Absolute price (use V1.01) +- Overall value (use V4.01) + +**Examples**: +- (+) "Great quality for the price" +- (+) "Excellent value for money" +- (-) "Pay more, get less" +- (-) "Overpriced for the quality" + +**Common Errors**: +- Confusing with O2 (Quality): V4.02 includes price comparison; O2 is quality alone + +##### V4.03 Satisfaction + +**Definition**: Contentment with the overall exchange. + +**Include**: +- General satisfaction +- Happy with experience +- Content with outcome +- Pleased overall + +**Exclude**: +- Outcome achievement (use O1.05) +- Overall value (use V4.01) +- Recommendation (use V4.04) + +**Examples**: +- (+) "Very satisfied with my purchase" +- (+) "Completely happy with the experience" +- (-) "Deeply regret this purchase" +- (-) "Left unsatisfied" + +**Common Errors**: +- Confusing with O1.05 (Outcome Achievement): O1.05 = specific goal met; V4.03 = general satisfaction + +##### V4.04 Recommendation + +**Definition**: Willingness to suggest to others. + +**Include**: +- Would recommend +- Tell others about it +- Suggest to friends +- Advocate for + +**Exclude**: +- Relationship building (use R4.03) +- Return intent (use V4.05) +- Loyalty (use R4) + +**Examples**: +- (+) "Highly recommend to everyone" +- (+) "Told all my friends about it" +- (-) "Would warn everyone to avoid" +- (-) "Don't recommend at all" + +**Common Errors**: +- Confusing with R4 (Loyalty): V4.04 = recommending to others; R4 = ongoing relationship + +##### V4.05 Return Intent + +**Definition**: Willingness to come back. + +**Include**: +- Would return +- Coming back +- Future visits +- Repeat business intent + +**Exclude**: +- Loyalty (use R4) +- Recommendation (use V4.04) +- Overall value (use V4.01) + +**Examples**: +- (+) "Definitely coming back" +- (+) "Will return for sure" +- (-) "Never coming back" +- (-) "Won't return" + +**Common Errors**: +- Confusing with R4 (Loyalty): V4.05 = simple return intent; R4 = ongoing relationship and trust + +--- + +#### V Domain Common Errors Summary + +| Error Pattern | Incorrect Code | Correct Code | Key Distinction | +|--------------|----------------|--------------|-----------------| +| "Total scam" | V4.01 | R1.04 | Character = R | +| "Product was bad quality" | V4.02 | O2 | Quality alone = O | +| "Waited forever" | V3.01 | J1.01 | Wait = J | +| "Policy is unfair" | R1.05 | V2.04 | Policy = V | +| "Hidden fees" (the fee) | V2.02 | V1.04 | Fee = V1.04 | +| "They lied about features" | V2.03 | R1.01 | Pattern = R | + +--- + +### 3.7 Domain R: Relationship + +**Definition**: Trust, reliability, and the ongoing connection between customer and business. + +**Core Question**: Can I trust this business and do they value our relationship? + +**Default Owner**: Leadership / CX + +**Scope**: +- Integrity: truthfulness, promise keeping, transparency, ethics, fair dealing +- Dependability: track record, consistency, stability, trustworthiness, guarantees +- Recovery: acknowledging failures, apology, compensation, improvement, ownership +- Loyalty: recognition, rewards, relationship building, communication, community + +**NOT in Scope**: +- Specific interaction issues (P domain) +- Specific process issues (J domain) +- Specific pricing issues (V domain) + +--- + +#### When to Use R Domain + +Use R when feedback is about: +- **Trust/commitment over time** ("They always/never...") +- **Organizational intent** ("They don't care about customers") +- **Pattern of behavior** ("This is the third time...") +- **Character judgment** ("Shady company," "Stand behind their product") +- **Moral assessment of the business** ("They're crooks," "Ethical company") + +Use P/J/V when feedback is about: +- **A specific interaction** ("The cashier was rude today") +- **A specific process** ("This refund took too long") +- **A specific price/term** ("This fee is unfair") + +--- + +#### R1: Integrity + +**Category Definition**: Honesty and ethical behavior of the organization. + +##### R1.01 Truthfulness + +**Definition**: Accurate, honest representations by the organization. + +**Include**: +- Organizational honesty +- Lying accusations (pattern) +- Truthful communications +- Honest dealings + +**Exclude**: +- Advertising accuracy (use V2.03) +- Staff information accuracy (use P4.04) +- Honest representation (use V2.05) + +**Examples**: +- (+) "Everything they say is accurate and true" +- (+) "Completely honest company" +- (-) "They flat out lied to me" +- (-) "Nothing they say is true" + +**Common Errors**: +- Confusing with V2.03 (Advertising): V2.03 = advertising specifically; R1.01 = organizational honesty pattern + +##### R1.02 Promise Keeping + +**Definition**: Honoring commitments and keeping promises. + +**Include**: +- Keeping word over time +- Organizational commitments +- Pattern of promises +- Delivering on commitments + +**Exclude**: +- Specific follow-through (use P3.04) +- Resolution speed (use J4.03) +- Guarantees (use R2.05) + +**Examples**: +- (+) "Always deliver on their word" +- (+) "Keep every promise they make" +- (-) "Never keep their promises" +- (-) "Every commitment is an empty word" + +**Common Errors**: +- **Critical Distinction**: R1.02 = pattern ("they never keep promises"). P3.04 = specific instance ("said they'd call back, didn't"). + +##### R1.03 Transparency + +**Definition**: Openness about practices, policies, and operations. + +**Include**: +- Organizational transparency +- Openness about operations +- Hidden agendas +- Disclosure patterns + +**Exclude**: +- Fee disclosure (use V2.02) +- Pricing clarity (use V2.01) +- Data security (use E4.03) + +**Examples**: +- (+) "Completely transparent about everything" +- (+) "Full disclosure, no secrets" +- (-) "Hidden agendas everywhere" +- (-) "Never know what's really going on" + +**Common Errors**: +- Confusing with V2.02 (Fee Disclosure): V2.02 = pricing transparency; R1.03 = organizational transparency + +##### R1.04 Ethics + +**Definition**: Moral and ethical business conduct. + +**Include**: +- "Scam" language +- Ethical/unethical judgment +- Moral business character +- Predatory behavior + +**Exclude**: +- Terms fairness (use V2.04) +- Fair dealing (use R1.05) +- Overall value (use V4.01 for "rip-off") + +**Examples**: +- (+) "Ethical company - do the right thing" +- (+) "Stand-up organization with integrity" +- (-) "Total scam company" +- (-) "Shady business practices" + +**Common Errors**: +- **Critical Rule**: "Scam" = R1.04 (moral judgment). "Rip-off" = V4.01 (value complaint). + +##### R1.05 Fair Dealing + +**Definition**: Equitable treatment and fair practices. + +**Include**: +- Fair treatment overall +- Equitable practices +- Not taking advantage +- Fair business practices + +**Exclude**: +- Equal treatment (use A3.05) +- Terms fairness (use V2.04) +- Respect (use P1.02) + +**Examples**: +- (+) "Always treated fairly" +- (+) "Fair and square dealings" +- (-) "Felt taken advantage of" +- (-) "Completely unfair treatment" + +**Common Errors**: +- Confusing with A3.05 (Equal Treatment): A3.05 = identity-based discrimination; R1.05 = general fair dealing + +--- + +#### R2: Dependability + +**Category Definition**: Consistency and reliability over time. + +##### R2.01 Track Record + +**Definition**: Historical performance and reliability. + +**Include**: +- History of performance +- Long-term reliability +- Past experiences +- Overall record + +**Exclude**: +- Staff experience (use P2.05) +- Process consistency (use J3.01) +- Product reliability (use O1.04) + +**Examples**: +- (+) "Never let me down in 10 years" +- (+) "Impeccable track record" +- (-) "History of problems" +- (-) "Long record of failures" + +**Common Errors**: +- Confusing with P2.05 (Experience): P2.05 = individual expertise; R2.01 = organizational track record + +##### R2.02 Consistency + +**Definition**: Same experience delivered over time. + +**Include**: +- Consistent quality over visits +- Same experience each time +- Reliability of experience +- Dependable outcomes + +**Exclude**: +- Process consistency (use J3.01) +- Product reliability (use O1.04) +- Error rate (use J3.05) + +**Examples**: +- (+) "Always great - consistent quality" +- (+) "Same excellent experience every time" +- (-) "Varies wildly - never know what you'll get" +- (-) "Completely inconsistent" + +**Common Errors**: +- Confusing with J3.01 (Process Consistency): J3.01 = process level; R2.02 = organizational/relationship level + +##### R2.03 Stability + +**Definition**: Organizational continuity and stability. + +**Include**: +- Company stability +- Organizational continuity +- Business changes +- Management stability + +**Exclude**: +- System uptime (use J3.03) +- Track record (use R2.01) +- Trustworthiness (use R2.04) + +**Examples**: +- (+) "Stable company - been around for years" +- (+) "Consistent ownership and leadership" +- (-) "Constant changes - nothing stable" +- (-) "Different management every month" + +**Common Errors**: +- Confusing with J3.03 (System Availability): J3.03 = system uptime; R2.03 = organizational stability + +##### R2.04 Trustworthiness + +**Definition**: Warranting confidence and trust. + +**Include**: +- Can count on them +- Trust in organization +- Confidence in business +- Reliable partner + +**Exclude**: +- Integrity specifics (use R1) +- Track record (use R2.01) +- Consistency (use R2.02) + +**Examples**: +- (+) "Can absolutely count on them" +- (+) "Completely trustworthy organization" +- (-) "Don't trust them at all" +- (-) "Lost all confidence in them" + +**Common Errors**: +- Confusing with R1 (Integrity): R1 = specific integrity aspects; R2.04 = overall trustworthiness assessment + +##### R2.05 Guarantee Honor + +**Definition**: Standing behind products and honoring guarantees. + +**Include**: +- Warranty honor +- Guarantee fulfillment +- Standing behind product +- Promise of quality upheld + +**Exclude**: +- Resolution quality (use J4.04) +- Promise keeping (use R1.02) +- Compensation (use R3.03) + +**Examples**: +- (+) "Honored the warranty without question" +- (+) "Stand behind their products 100%" +- (-) "Worthless guarantee - wouldn't honor it" +- (-) "Warranty is meaningless" + +**Common Errors**: +- Confusing with J4.04 (Resolution Quality): J4.04 = fix quality; R2.05 = guarantee/warranty honor + +--- + +#### R3: Recovery + +**Category Definition**: Response to failures and making things right. + +##### R3 vs J4 Disambiguation + +This is critical: + +| If the span is about... | Use | +|------------------------|-----| +| *What they did* to fix the problem | J4 | +| *How they took responsibility* (acknowledgment, apology, ownership) | R3 | + +| Aspect | J4 (Resolution) | R3 (Recovery) | +|--------|-----------------|---------------| +| **Focus** | Mechanics of fixing | Accountability | +| **Question** | Was it fixed? | Did they own it? | +| **Owner** | Operations | Leadership | + +##### R3.01 Acknowledgment + +**Definition**: Admitting failures and wrongdoing. + +**Include**: +- Owning mistakes +- Admitting fault +- Acknowledging wrongdoing +- Taking blame + +**Exclude**: +- Problem acknowledgment (use J4.01) +- Apology (use R3.02) +- Ownership (use R3.05) + +**Examples**: +- (+) "Immediately admitted their mistake" +- (+) "Owned up to the error" +- (-) "Denied any wrongdoing" +- (-) "Refused to admit fault" + +**Common Errors**: +- **Key Distinction**: J4.01 = "Yes, there's a problem" (operational). R3.01 = "Yes, we were wrong" (accountability). + +##### R3.02 Apology + +**Definition**: Expression of regret and sorrow for issues. + +**Include**: +- Saying sorry +- Expressing regret +- Apologizing +- Showing remorse + +**Exclude**: +- Empathy (use P1.03) +- Acknowledgment (use R3.01) +- Compensation (use R3.03) + +**Examples**: +- (+) "Sincere, heartfelt apology" +- (+) "Genuinely apologized for the issue" +- (-) "Non-apology apology" +- (-) "Never said sorry" + +**Common Errors**: +- Confusing with P1.03 (Empathy): P1.03 = emotional understanding; R3.02 = formal apology + +##### R3.03 Compensation + +**Definition**: Making amends beyond just fixing the problem. + +**Include**: +- Offering compensation +- Making up for issues +- Extra gestures +- Amends beyond the fix + +**Exclude**: +- Resolution quality (use J4.04) +- Terms fairness (use V2.04) +- Overall value (use V4.01) + +**Examples**: +- (+) "Refunded plus gave store credit" +- (+) "More than made up for the problem" +- (-) "Offered nothing for my trouble" +- (-) "Refused any compensation" + +**Common Errors**: +- **Key Distinction**: J4.04 = "Was it fixed?" R3.03 = "Did they make amends?" + +##### R3.04 Improvement + +**Definition**: Actions demonstrating commitment to prevent recurrence. + +**Include**: +- Organizational commitment to change +- Promised improvements +- Learning from mistakes +- Systemic changes announced + +**Exclude**: +- Prevention actions (use J4.05) +- Track record (use R2.01) +- Consistency (use R2.02) + +**Examples**: +- (+) "Committed to changing their processes" +- (+) "Showed they learned from the mistake" +- (-) "No indication anything will change" +- (-) "Same problems keep happening" + +**Common Errors**: +- **Key Distinction**: J4.05 = process change made. R3.04 = organizational commitment to improve. + +##### R3.05 Ownership + +**Definition**: Taking full responsibility for issues. + +**Include**: +- Taking responsibility +- Not blaming others +- Owning the problem +- Full accountability + +**Exclude**: +- Problem-solving (use P2.03) +- Acknowledgment (use R3.01) +- Apology (use R3.02) + +**Examples**: +- (+) "Took full responsibility" +- (+) "Didn't blame anyone else" +- (-) "Blamed me for the problem" +- (-) "Shifted responsibility to others" + +**Common Errors**: +- Confusing with P2.03 (Problem-Solving): P2.03 = ability to solve; R3.05 = willingness to own + +--- + +#### R4: Loyalty + +**Category Definition**: Investment in the ongoing customer relationship. + +##### R4.01 Recognition + +**Definition**: Acknowledging repeat customers. + +**Include**: +- Remembering customers +- Recognizing regulars +- Knowing their history +- Personal acknowledgment + +**Exclude**: +- Personalization (use O4.02) +- Warmth (use P1.01) +- Rewards (use R4.02) + +**Examples**: +- (+) "They remember me every time I come in" +- (+) "Recognized as a valued regular" +- (-) "Treated like a stranger every time" +- (-) "No acknowledgment of my loyalty" + +**Common Errors**: +- Confusing with O4.02 (Personalization): O4.02 = preferences remembered; R4.01 = personal recognition + +##### R4.02 Rewards + +**Definition**: Loyalty benefits and programs. + +**Include**: +- Loyalty programs +- Points and rewards +- Member benefits +- Loyalty perks + +**Exclude**: +- Price (use V1) +- Recognition (use R4.01) +- Compensation (use R3.03) + +**Examples**: +- (+) "Great loyalty rewards program" +- (+) "Excellent perks for regulars" +- (-) "Worthless points system" +- (-) "No loyalty benefits at all" + +**Common Errors**: +- Confusing with V1 (Price): R4.02 = loyalty programs; V1 = general pricing + +##### R4.03 Relationship Building + +**Definition**: Investment in building a personal connection. + +**Include**: +- Personal relationship +- Connection beyond transaction +- Genuine interest in customer +- Long-term relationship focus + +**Exclude**: +- Friendliness (use P1.01) +- Recognition (use R4.01) +- Community (use R4.05) + +**Examples**: +- (+) "Feel like I have a personal relationship" +- (+) "Genuinely invest in customers" +- (-) "Purely transactional" +- (-) "No interest in relationship" + +**Common Errors**: +- Confusing with P1.01 (Friendliness): P1.01 = single-interaction warmth; R4.03 = ongoing relationship investment + +##### R4.04 Communication + +**Definition**: Quality of ongoing relationship communication. + +**Include**: +- Newsletters and updates +- Ongoing communication quality +- Relationship communication +- Regular engagement + +**Exclude**: +- Proactive updates (use P4.03) +- Contact options (use A4.05) +- Information accuracy (use P4.04) + +**Examples**: +- (+) "Helpful, relevant newsletters" +- (+) "Great ongoing communication" +- (-) "Nothing but spam" +- (-) "No useful communication" + +**Common Errors**: +- Confusing with P4.03 (Proactive Updates): P4.03 = transaction updates; R4.04 = ongoing relationship communication + +##### R4.05 Community + +**Definition**: Sense of belonging and connection with brand community. + +**Include**: +- Feeling part of something +- Brand community +- Customer community +- Belonging + +**Exclude**: +- Atmosphere (use E3.01) +- Relationship building (use R4.03) +- Family friendly (use A3.04) + +**Examples**: +- (+) "Feel part of a community" +- (+) "Great sense of belonging" +- (-) "No sense of community" +- (-) "Just another number" + +**Common Errors**: +- Confusing with E3.01 (Atmosphere): E3.01 = space vibe; R4.05 = community belonging + +--- + +#### R Domain Common Errors Summary + +| Error Pattern | Incorrect Code | Correct Code | Key Distinction | +|--------------|----------------|--------------|-----------------| +| "This call they didn't follow up" | R1.02 | P3.04 | Specific = P | +| "Price is unfair" | R1.05 | V2.04 | Price = V | +| "They fixed it quickly" | R3.03 | J4.03 | Process = J | +| "Apologized nicely" | P1.03 | R3.02 | Apology = R | +| "Great every time I go" | R2.02 | J3.01 | Process level = J | +| "Rip-off prices" | R1.04 | V4.01 | Exchange = V | + +--- + +## 4. Metadata Dimensions + +Every span classification includes metadata dimensions. There are **7 dimensions with 24 total values**. + +### 4.1 Valence (V) - ALWAYS REQUIRED + +Valence captures the sentiment direction of the feedback. + +| Code | Label | Definition | Linguistic Markers | +|------|-------|------------|-------------------| +| **V+** | Positive | Praise, satisfaction, approval | "great," "loved," "excellent," "perfect," "amazing" | +| **V-** | Negative | Complaint, dissatisfaction, criticism | "terrible," "hated," "worst," "awful," "disappointing" | +| **V0** | Neutral | Factual observation without judgment | "they have," "it was," "there are," descriptive only | +| **V+-** | Mixed | Both positive and negative in same span | "good but," "despite," "however," contrasting elements | + +**V+- Usage Rule**: Prefer splitting over V+- unless truly inseparable. + +| Feedback | Action | Rationale | +|----------|--------|-----------| +| "Great product, terrible onboarding" | SPLIT | Two different targets | +| "Good but overpriced" | KEEP with V+- | Same target, mixed assessment | +| "Nice staff despite the chaos" | SPLIT if chaos is separate | Different domains likely | + +**Test**: If the positive and negative parts have different domain targets, split them. + +--- + +### 4.2 Intensity (I) - REQUIRED FOR CORE+ + +Intensity captures how strongly the sentiment is expressed. + +| Code | Label | Definition | Linguistic Markers | +|------|-------|------------|-------------------| +| **I1** | Mild | Slight preference/concern | "a bit," "somewhat," "could be better," "slightly," "minor" | +| **I2** | Moderate | Clear but not extreme | Standard adjectives, no intensifiers, normal language | +| **I3** | Strong | Emphatic, intense expression | "extremely," "absolutely," "worst ever," CAPS, !!!, profanity | + +**I3 Indicators**: +- Intensifying adverbs: extremely, absolutely, totally, completely +- Superlatives: best ever, worst I've seen, most terrible +- ALL CAPS in review text +- Multiple exclamation marks (!!!) +- Profanity or extreme language +- Words like "unbelievable," "outrageous," "incredible" + +**Default**: When in doubt, use I2 (moderate). + +--- + +### 4.3 Specificity (S) - STANDARD+ ONLY + +Specificity measures how much detail is provided in the feedback. + +| Code | Label | Definition | Example | +|------|-------|------------|---------| +| **S1** | Vague | General impression only, no details | "Service was bad" | +| **S2** | Moderate | Some details or context | "Service was slow at dinner" | +| **S3** | Specific | Concrete details: names, times, amounts | "Waiter John took 40 mins for appetizers at 7pm Saturday" | + +**S3 Indicators**: +- Named individuals +- Specific times or dates +- Exact amounts or quantities +- Precise locations within a space +- Specific product models or items + +--- + +### 4.4 Actionability (A) - STANDARD+ ONLY + +Actionability measures how clearly the feedback points to a specific action. + +| Code | Label | Definition | Example | +|------|-------|------------|---------| +| **A1** | Low | Feeling with no clear action path | "I just didn't like it" | +| **A2** | Medium | Suggests improvement area | "Food could be warmer" | +| **A3** | High | Specific implementable fix possible | "West bathroom stall lock is broken" | + +**Important**: Specificity and Actionability are correlated but NOT identical. + +| Example | Specificity | Actionability | Why Different | +|---------|-------------|---------------|---------------| +| "John was rude" | S3 (named) | A2 (unclear action) | Specific but action not obvious | +| "Website is confusing" | S1 (vague) | A3 (triggers UX audit) | Vague but actionable category | +| "Bathroom stall lock broken" | S3 | A3 | High both - ideal feedback | +| "I didn't enjoy it" | S1 | A1 | Low both - least useful | + +--- + +### 4.5 Temporal Reference (T) - STANDARD+ (OPTIONAL FOR CORE) + +Temporal Reference indicates the time frame of the feedback. + +| Code | Label | Definition | Examples | +|------|-------|------------|----------| +| **TC** | Current | This specific visit/experience | "Today's visit," "This time" (DEFAULT) | +| **TR** | Recent | Recent pattern of experiences | "Lately," "Last few visits," "Recently" | +| **TH** | Historical | Long-standing pattern | "For years," "Since I can remember," "Always been" | +| **TF** | Future | Expectations or predictions | "If they don't improve," "Will come back" | + +**Default**: TC (Current) when no temporal language is present. + +--- + +### 4.6 Evidence Type (E) - STANDARD+ ONLY + +Evidence Type indicates how the classification is derived from the text. + +| Code | Label | Definition | Constraint | +|------|-------|------------|------------| +| **ES** | Stated | Explicitly said by customer | Text directly says it (DEFAULT) | +| **EI** | Inferred | Logically entailed by text | Must be directly deducible, not speculative | +| **EC** | Contextual | Requires surrounding text | Span uses "that," "they," "it" referencing earlier content | + +**EI Rules**: +- Use only when text logically entails the inference +- OK: "Took 3 weeks to reply" = EI for slow response time +- OK: "Fifth time calling about this" = EI for error rate pattern +- NOT OK: "Seemed tired" = Cannot infer fatigue without more evidence + +**EC Rules**: +- Use when span depends on earlier referents +- "The same issue happened again" (depends on knowing what issue) +- "They did the same thing" (requires prior context) +- "That was disappointing" (references unstated subject) + +--- + +### 4.7 Comparative Reference (CR) - STANDARD+ (OPTIONAL FOR CORE) + +Comparative Reference captures when customers compare current experience to their past experience. + +| Code | Label | Definition | Trigger Words | +|------|-------|------------|---------------| +| **CR-N** | None | No comparison to past | (default - ~90% of spans) | +| **CR-B** | Better | Explicit improvement | "better now," "improved," "finally fixed," "turned around" | +| **CR-W** | Worse | Explicit decline | "worse now," "used to be good," "gone downhill," "no longer" | +| **CR-S** | Same | Explicitly unchanged | "still," "as always," "same as before," "nothing changed" | + +**CR Assignment Rules**: + +1. **Only assign CR-B/W/S when the customer explicitly compares to their own past.** +2. **CR-N is the default.** Only change when comparison is explicit. +3. **Self-comparison only.** Competitor comparisons don't trigger CR. +4. **Implicit decline/improvement counts:** + - "used to be good" = CR-W + - "finally fixed" = CR-B + - "still broken" = CR-S + +**CR Trigger Word Reference**: + +| CR-B (Better) | CR-W (Worse) | CR-S (Same) | +|---------------|--------------|-------------| +| "better now" | "worse now" | "still" | +| "improved" | "used to be good" | "as always" | +| "finally fixed" | "gone downhill" | "same as before" | +| "turned it around" | "not what it used to be" | "nothing changed" | +| "much faster than before" | "has declined" | "yet again" | +| "not like last time" (positive) | "was great before" | "same old" | + +**CR + Valence Combinations**: + +| CR | V+ | V- | Interpretation | +|----|----|----|----------------| +| CR-B | Improvement praise | Recovery acknowledgment | Issue resolved/improving | +| CR-W | -- | Decline complaint | Quality deteriorating | +| CR-S | Consistent praise | Persistent complaint | Stable state | +| CR-N | General praise | General complaint | No temporal signal | + +--- + +### 4.8 Metadata by Profile Summary + +| Dimension | Lite | Core | Standard | Full | +|-----------|:----:|:----:|:--------:|:----:| +| Valence | Required | Required | Required | Required | +| Intensity | Optional | Required | Required | Required | +| Specificity | -- | -- | Required | Required | +| Actionability | -- | -- | Required | Required | +| Temporal | -- | Optional | Required | Required | +| Evidence | -- | -- | Required | Required | +| Comparative | -- | Optional | Required | Required | + +--- + +## 5. Causal Codes + +Causal codes provide optional root-cause analysis for Full profile implementations. There are **16 causal codes across 3 layers**. + +### 5.1 Causal Depth Prohibition Rule + +**CRITICAL**: Causal layers (CD/MG/SY) may ONLY be assigned when the review explicitly states or logically entails the condition. Otherwise, leave `causal_chain` empty. + +This rule prevents analysts from inventing plausible-but-unsubstantiated causes. + +| Review Text | Causal Code | Valid? | Why | +|-------------|-------------|--------|-----| +| "Long wait because they were short-staffed" | CD-O | YES | Explicitly stated | +| "The machine was broken" | CD-E | YES | Explicitly stated | +| "Fifth time I've reported this issue" | MG-O | YES | Logically entailed (EI) | +| "They seem understaffed" | -- | NO | "Seem" is speculation | +| "Probably a training issue" | -- | NO | Annotator speculation | +| "Management doesn't care" (stated) | SY-C | YES | Customer explicitly states | + +**When in doubt, omit causal codes.** Better to have no causal chain than an invented one. + +--- + +### 5.2 Conditions Layer (CD-) + +Conditions are immediate factors that allowed the experience to happen. + +| Code | Name | Definition | Example Text | +|------|------|------------|--------------| +| **CD-S** | Staff State | Fatigue, training gaps, motivation | "Server seemed exhausted," "Clearly new" | +| **CD-T** | Team Dynamics | Handoffs, coordination, communication | "Kept passing me around," "No one knew" | +| **CD-E** | Equipment | Malfunction, unavailable, outdated | "Machine was broken," "System was down" | +| **CD-F** | Facility | Maintenance, capacity, hazards | "Place was falling apart," "Too cramped" | +| **CD-O** | Operational | Understaffing, demand surge, time pressure | "Clearly understaffed," "Overwhelmed" | + +--- + +### 5.3 Management Layer (MG-) + +Management factors are decisions that allowed conditions to exist. + +| Code | Name | Definition | Example Text | +|------|------|------------|--------------| +| **MG-P** | Planning | Scheduling, forecasting failure | "No one scheduled for weekend" | +| **MG-T** | Training | Training gaps, development failure | "Clearly not trained properly" | +| **MG-O** | Oversight | Supervision, monitoring failure | "Third time reporting this" (EI) | +| **MG-R** | Resources | Resource allocation issues | "No supplies available" | +| **MG-C** | Communication | Policy relay, expectation setting | "Staff didn't know the policy" | + +**Repeated Complaints Rule**: Multiple unresolved complaints (e.g., "third time," "keep reporting") may justify MG-O (Oversight) via EI, as the pattern logically entails failure to monitor/correct. + +--- + +### 5.4 Systemic Layer (SY-) + +Systemic factors are organizational-level issues that create management failures. + +| Code | Name | Definition | Example Text | +|------|------|------------|--------------| +| **SY-R** | Resource Decisions | Budget, investment, staffing | "Cheap owners," "Cutting corners" | +| **SY-P** | Policy/Procedure | Rules, bureaucracy | "Company policy is the problem" | +| **SY-C** | Culture | Values, priorities, norms | "Management doesn't care" | +| **SY-S** | Standards | Quality thresholds, expectations | "Lowered their standards" | +| **SY-H** | Human Capital | Compensation, hiring, retention | "Can't keep good employees" | +| **SY-X** | External | Market, regulatory, competition | "Ever since COVID," "New regulations" | + +--- + +### 5.5 Causal Chain Structure + +``` +LAYER 4: SYSTEMIC (Why does the organization create these conditions?) +┌─────────────────────────────────────────────────────────────────┐ +│ SY-R: Resources | SY-P: Policy | SY-C: Culture | SY-S: Standards│ +│ SY-H: Human Capital | SY-X: External │ +└─────────────────────────────────────────────────────────────────┘ + ↑ constrains +LAYER 3: MANAGEMENT (What decisions allowed enabling conditions?) +┌─────────────────────────────────────────────────────────────────┐ +│ MG-P: Planning | MG-T: Training | MG-O: Oversight │ +│ MG-R: Resources | MG-C: Communication │ +└─────────────────────────────────────────────────────────────────┘ + ↑ creates +LAYER 2: CONDITIONS (What allowed the experience to happen?) +┌─────────────────────────────────────────────────────────────────┐ +│ CD-S: Staff State | CD-T: Team | CD-E: Equipment │ +│ CD-F: Facility | CD-O: Operational │ +└─────────────────────────────────────────────────────────────────┘ + ↑ enables +LAYER 1: EXPERIENCE (What the customer directly perceived) +┌─────────────────────────────────────────────────────────────────┐ +│ [Primary Domain/Category/Subcode Classification] │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 5.6 Causal Chain Examples + +**Example 1: Explicit Cause** +> "Long wait because they were clearly understaffed" + +| Layer | Code | Evidence | +|-------|------|----------| +| Experience | J1.01 (Wait Time) | ES | +| Conditions | CD-O (Understaffing) | ES | + +**Example 2: Inferred Cause** +> "This is the fourth time I've reported this broken equipment" + +| Layer | Code | Evidence | +|-------|------|----------| +| Experience | E1.02 (Maintenance) | ES | +| Management | MG-O (Oversight failure) | EI | + +**Example 3: Multi-Layer** +> "Staff was exhausted - they've been working 12-hour shifts. Management clearly doesn't care about their employees." + +| Layer | Code | Evidence | +|-------|------|----------| +| Experience | P1.05 (Enthusiasm) | ES | +| Conditions | CD-S (Staff State) | ES | +| Systemic | SY-C (Culture) | ES | + +--- + +## 6. Span Boundary Rules + +### 6.1 When to SPLIT + +Split spans when you encounter: + +1. **Contrasting conjunctions**: but, however, although, despite, yet +2. **Subject changes**: location → service → food +3. **Valence changes**: positive → negative +4. **Domain changes**: different aspect of experience +5. **Different sentences** (unless tightly linked cause-effect) + +### 6.2 When to KEEP TOGETHER + +Keep spans together when: + +1. **Cause-effect in same clause**: "Long wait because understaffed" + - Primary = impact (J1.01 Wait Time) + - Secondary = cause (A1.04 Staffing) + +2. **Same target, mixed assessment**: "Good but overpriced" (same product) + +3. **Elaboration of same point**: "Service was slow. Had to wait 40 minutes." + +### 6.3 Max Spans Guidance + +| Sentence Type | Typical Spans | +|---------------|---------------| +| Simple sentence | 1-2 spans | +| Complex sentence | 2-3 spans | +| If tempted to create 4+ | Re-read; probably over-splitting | + +### 6.4 Cause-Effect Rule + +When a span describes both impact and cause, keep as one span: +- **Primary code** = the impact (what the customer experienced) +- **Secondary code** = the cause (what created the impact) + +| Span | Primary | Secondary | Treatment | +|------|---------|-----------|-----------| +| "Long wait because understaffed" | J1.01 | A1.04 | Single span | +| "Food cold, had to send it back" | O2.05 | J4.02 | Single span | +| "App crashed so I lost my data" | E2.02 | E4.03 | Single span | +| "Rude waiter. Also food was cold." | P1.02 / O2.05 | -- | TWO spans | + +### 6.5 V+- vs Split Decision + +| Feedback | Action | Rationale | +|----------|--------|-----------| +| "Great product, terrible onboarding" | SPLIT | Different domain targets | +| "Good but overpriced" | KEEP with V+- | Same target | +| "Nice staff despite the chaos" | SPLIT if chaos is separate | Different domains | + +**Test**: If positive and negative have *different domain targets*, split. + +--- + +## 7. Disambiguation Guide + +### 7.1 Top 10 Disambiguation Pitfalls + +| # | Mistake | Correct Approach | +|---|---------|------------------| +| 1 | O1.01 vs J3.03 | O1.01 = product function. J3.03 = system uptime. "Car won't start" = O1.01. "Website down" = J3.03. | +| 2 | P3.04 vs R1.02 | P3.04 = specific interaction. R1.02 = trust pattern. "Said they'd call, didn't" = P3.04. "They never keep promises" = R1.02. | +| 3 | J2.01 vs E2.04 | J2.01 = process effort. E2.04 = interface navigation. "Too many steps" = J2.01. "Buried in menus" = E2.04. | +| 4 | J3.01 vs O1.04 | J3.01 = process consistency. O1.04 = product reliability. "Pizza always good" = J3.01. "Phone always connects" = O1.04. | +| 5 | E2.03 vs O1.02 | E2.03 = interface speed. O1.02 = product performance. "App slow" = E2.03. "Car sluggish" = O1.02. | +| 6 | A3.05 vs P1.02 | A3.05 = identity-based discrimination. P1.02 = general disrespect. "Treated differently because of X" = A3.05. | +| 7 | V2.xx vs R1.xx | V2 = pricing/terms specifically. R1 = trust/integrity framing. | +| 8 | Over-splitting | "Long wait because understaffed" = single span. Primary = J1.01, Secondary = A1.04. | +| 9 | CR assignment | CR-N is default. "Service is slow" = CR-N. "Service is *still* slow" = CR-S. | +| 10 | Invented causal | Only when explicitly stated or logically entailed. No speculation. | + +### 7.2 V vs R: Scam vs Rip-off + +| Word/Phrase | Domain | Reasoning | +|-------------|--------|-----------| +| "scam" | R1.04 | Character judgment | +| "fraud" | R1.04 | Character judgment | +| "crooks" | R1.04 | Character judgment | +| "rip-off" | V4.01 | Exchange complaint | +| "robbery" | V4.01 | Exchange complaint | +| "highway robbery" | V4.01 | Exchange complaint | +| "overpriced" | V1.01/V4.02 | Price/value complaint | + +**Decision Rule**: +- About the exchange (what I got vs. what I paid)? → **V** +- About their intent to deceive/harm? → **R** + +### 7.3 J4 vs R3: Process vs Ownership + +| Aspect | J4 (Resolution) | R3 (Recovery) | +|--------|-----------------|---------------| +| Focus | What they DID to fix | How they took RESPONSIBILITY | +| Question | Was the fix adequate? | Did they own it and make amends? | + +| Span | Code | Rationale | +|------|------|-----------| +| "They immediately sent a replacement" | J4.02 | Process focus | +| "Took weeks to resolve" | J4.03 | Resolution speed | +| "They owned their mistake" | R3.01 | Admitting fault | +| "Sincere apology" | R3.02 | Expression of regret | +| "Offered nothing" | R3.03 | Compensation failure | +| "Changed their process" | J4.05 | Prevention action | +| "Blamed me instead" | R3.05 | Ownership failure | + +### 7.4 Quick Disambiguation Tests + +| Question | If YES | If NO | +|----------|--------|-------| +| About the product/service itself? | Likely O | Check P-R | +| Names or describes a person? | Likely P | Check J-R | +| Mentions time, steps, or waiting? | Likely J | Check E-R | +| Describes a place or interface? | Likely E | Check A-R | +| About accessibility or availability? | Likely A | Check V-R | +| About price, cost, or worth? | Likely V | Check R | +| About trust, patterns, or "always/never"? | Likely R | Re-read span | + +--- + +## 8. USN Notation + +URT String Notation (USN) provides compact tagging format. + +### 8.1 Format + +``` +URT:{Profile}:{codes}:{Valence}{Intensity}[:{metadata}][:{causal}] +``` + +### 8.2 Profile Codes + +| Code | Profile | Primary Code Level | +|------|---------|-------------------| +| L | Lite | Domain (O, P, J...) | +| C | Core | Category (O1, P2...) | +| S | Standard | Subcode (O1.01, P2.03...) | +| F | Full | Subcode + Causal | + +### 8.3 Examples + +| Review | Profile | USN | +|--------|---------|-----| +| "Food was cold" | Lite | `URT:L:O:-2` | +| "Food was cold" | Core | `URT:C:O2:-2` | +| "Food was cold, like last time" | Standard | `URT:S:O2.05:-2:22TR.ES.S` | +| "Rude staff and unfair policy" | Standard | `URT:S:P1.02+V2.04:-3:22TC.ES.N` | +| "Much better now!" | Standard | `URT:S:V4.01:+2:11TC.ES.B` | + +### 8.4 Metadata Encoding (Standard+) + +``` +{Specificity}{Actionability}{Temporal}.{Evidence}.{Comparative} + +Example: 22TR.ES.S + ^^ = S2, A2 + ^^ = TR (recent) + ^^ = ES (stated) + ^ = CR-S (same/unchanged) +``` + +### 8.5 Multi-Code Notation + +Use `+` to join primary and secondary codes: +- `P1.02+V2.04` = Primary P1.02 with secondary V2.04 + +--- + +## 9. Appendices + +### 9.1 All 7 Domains Quick Reference + +| Code | Domain | Core Question | Default Owner | +|------|--------|---------------|---------------| +| O | Offering | Does it work? | Product/Operations | +| P | People | How did they treat me? | HR/Training | +| J | Journey | Was it smooth? | Operations/Process | +| E | Environment | Is the space okay? | Facilities/IT | +| A | Access | Can I get it? | Compliance/Design | +| V | Value | Is it worth it? | Finance/Pricing | +| R | Relationship | Can I trust them? | Leadership/CX | + +### 9.2 All 28 Categories Quick Reference + +| Domain | Cat 1 | Cat 2 | Cat 3 | Cat 4 | +|--------|-------|-------|-------|-------| +| **O** | O1 Function | O2 Quality | O3 Completeness | O4 Fit | +| **P** | P1 Attitude | P2 Competence | P3 Responsiveness | P4 Communication | +| **J** | J1 Timing | J2 Ease | J3 Reliability | J4 Resolution | +| **E** | E1 Physical | E2 Digital | E3 Ambiance | E4 Safety | +| **A** | A1 Availability | A2 Accessibility | A3 Inclusivity | A4 Convenience | +| **V** | V1 Price | V2 Transparency | V3 Effort | V4 Worth | +| **R** | R1 Integrity | R2 Dependability | R3 Recovery | R4 Loyalty | + +### 9.3 Metadata Quick Reference + +| Dimension | Values | Default | Profile | +|-----------|--------|---------|---------| +| Valence | V+, V-, V0, V+- | -- | All | +| Intensity | I1, I2, I3 | -- | Core+ | +| Specificity | S1, S2, S3 | -- | Standard+ | +| Actionability | A1, A2, A3 | -- | Standard+ | +| Temporal | TC, TR, TH, TF | TC | Standard+ | +| Evidence | ES, EI, EC | ES | Standard+ | +| Comparative | CR-N, CR-B, CR-W, CR-S | CR-N | Standard+ | + +### 9.4 Glossary + +| Term | Definition | +|------|------------| +| **Domain** | Top-level classification (7 total): O, P, J, E, A, V, R | +| **Category** | Mid-level classification (28 total): O1, O2, P1, P2, etc. | +| **Subcode** | Detailed classification (140 total): O1.01, O1.02, etc. | +| **Primary Code** | The main classification for a span (required) | +| **Secondary Code** | Additional classification (max 2, optional) | +| **Span** | A segment of review text being classified | +| **Valence** | Sentiment direction: positive, negative, neutral, mixed | +| **Intensity** | Strength of sentiment: mild, moderate, strong | +| **Specificity** | Level of detail: vague, moderate, specific | +| **Actionability** | Clarity of action path: low, medium, high | +| **Temporal** | Time reference: current, recent, historical, future | +| **Evidence** | Source: stated, inferred, contextual | +| **Comparative Reference (CR)** | Change signal: none, better, worse, same | +| **Causal Code** | Root cause classification (16 codes across 3 layers) | +| **USN** | URT String Notation - compact tagging format | + +### 9.5 Pre-Submission Checklist + +Before submitting an annotation, verify: + +1. [ ] **One primary code per span** (no exceptions) +2. [ ] **Max 2 secondary codes** (prevents over-tagging) +3. [ ] **Secondary codes are genuinely distinct** (different category preferred) +4. [ ] **Used decision tree** for domain selection +5. [ ] **Split at domain changes** (different aspects = different spans) +6. [ ] **CR-N unless explicit comparison** (default is no comparison) +7. [ ] **No invented causal codes** (only when text supports) +8. [ ] **Verified intensity markers** (I3 requires emphatic language) +9. [ ] **Cause-effect kept together** (impact = primary, cause = secondary) +10. [ ] **V vs R correctly applied** (exchange = V, character = R) + +### 9.6 Document References + +| Document | Location | Purpose | +|----------|----------|---------| +| URT-Specification-v5.1.md | `/urt-taxonomy/spec/` | Full specification | +| A1-Annotator-Quickstart.md | `/urt-taxonomy/track-a-training/` | Quick reference | +| A2-QA-Protocol.md | `/urt-taxonomy/track-a-training/` | QA procedures | +| A3-Calibration-Test-Set.md | `/urt-taxonomy/track-a-training/` | Gold standard tests | + +--- + +*URT v5.1 Full Annotation Manual | Track A: Training Materials* +*Comprehensive Reference for Human Annotators* + diff --git a/urt-taxonomy/track-b-engineering/B1-urt-codes.yaml b/urt-taxonomy/track-b-engineering/B1-urt-codes.yaml new file mode 100644 index 0000000..2346944 --- /dev/null +++ b/urt-taxonomy/track-b-engineering/B1-urt-codes.yaml @@ -0,0 +1,1766 @@ +# ============================================================================= +# B1: URT Code Registry +# Universal Review Taxonomy v5.1 +# ============================================================================= +# +# Canonical Counts (per spec header): +# - 7 Experience Domains +# - 28 Categories +# - 140 Subcodes (spec claims 140, but detailed definitions yield 138) +# - 16 Causal Codes +# - 7 Metadata Dimensions with 24 Values +# - Total Classification Codes: 156 (spec claims), 154 (actual defined) +# +# Status: Frozen - Production Ready +# Release Date: 2026-01-23 +# ============================================================================= + +version: "5.1" +status: "frozen" +release_date: "2026-01-23" + +statistics: + domains: 7 + categories: 28 + subcodes_spec_claims: 140 + subcodes_actual: 138 + causal_codes: 16 + metadata_dimensions: 7 + metadata_values: 24 + total_classification_codes_spec_claims: 156 + total_classification_codes_actual: 154 + note: "Spec v5.1 header claims 140 subcodes/156 total, but O3 has 4 subcodes and O4 has 4 subcodes (not 5 each), yielding 138 subcodes/154 total" + +# ============================================================================= +# EXPERIENCE DOMAINS +# ============================================================================= + +domains: + O: + name: "Offering" + description: "The core product, service, or outcome delivered" + core_question: "Does what we provide actually work and meet expectations?" + default_owner: "Product / Operations" + categories: + O1: + name: "Function" + definition: "Does it do what it's supposed to do?" + subcodes: + O1.01: + name: "Works/Doesn't Work" + definition: "Basic functionality success or failure" + positive_example: "Software runs perfectly" + negative_example: "Car won't start" + dont_confuse_with: "J3.03" + dont_confuse_reason: "J3.03 is system uptime, O1.01 is product function" + O1.02: + name: "Performance Level" + definition: "How well it operates" + positive_example: "Incredibly fast processor" + negative_example: "Sluggish and laggy" + dont_confuse_with: "E2.03" + dont_confuse_reason: "E2.03 is interface speed, O1.02 is product performance" + O1.03: + name: "Durability" + definition: "Longevity and resistance to wear" + positive_example: "Still perfect after 5 years" + negative_example: "Fell apart in a month" + dont_confuse_with: "O2.01" + dont_confuse_reason: "O2.01 is material quality, O1.03 is longevity" + O1.04: + name: "Reliability" + definition: "Consistency of function over time" + positive_example: "Never fails me" + negative_example: "Works sometimes, not others" + dont_confuse_with: "J3.01" + dont_confuse_reason: "J3.01 is process consistency, O1.04 is product reliability" + O1.05: + name: "Outcome Achievement" + definition: "Did customer accomplish their goal?" + positive_example: "Passed my exam!" + negative_example: "Treatment didn't work" + dont_confuse_with: "V4.03" + dont_confuse_reason: "V4.03 is satisfaction with exchange, O1.05 is goal achievement" + + O2: + name: "Quality" + definition: "How well is it made or executed?" + subcodes: + O2.01: + name: "Materials/Inputs" + definition: "Quality of components or ingredients" + positive_example: "Real leather, premium feel" + negative_example: "Cheap plastic parts" + dont_confuse_with: "O1.03" + dont_confuse_reason: "O1.03 is durability, O2.01 is material quality" + O2.02: + name: "Craftsmanship" + definition: "Skill of construction or execution" + positive_example: "Beautifully sewn seams" + negative_example: "Sloppy assembly" + dont_confuse_with: "P2.02" + dont_confuse_reason: "P2.02 is staff skill, O2.02 is product craftsmanship" + O2.03: + name: "Presentation" + definition: "Visual and aesthetic quality" + positive_example: "Gorgeous plating" + negative_example: "Looked thrown together" + dont_confuse_with: "E3.05" + dont_confuse_reason: "E3.05 is space aesthetics, O2.03 is product presentation" + O2.04: + name: "Attention to Detail" + definition: "Finishing touches and refinement" + positive_example: "Every corner perfect" + negative_example: "Full of typos" + dont_confuse_with: "O3.01" + dont_confuse_reason: "O3.01 is completeness, O2.04 is refinement" + O2.05: + name: "Condition at Delivery" + definition: "State when received" + positive_example: "Still warm from oven" + negative_example: "Arrived damaged" + dont_confuse_with: "J3.02" + dont_confuse_reason: "J3.02 is process accuracy, O2.05 is delivery condition" + + O3: + name: "Completeness" + definition: "Is everything included that should be?" + subcodes: + O3.01: + name: "All Components Present" + definition: "Nothing missing from what was promised" + positive_example: "Everything in the box" + negative_example: "Missing the charger" + dont_confuse_with: "O4.01" + dont_confuse_reason: "O4.01 is spec match, O3.01 is completeness" + O3.02: + name: "Feature Availability" + definition: "Promised features actually work" + positive_example: "All menu items available" + negative_example: "Half the features disabled" + dont_confuse_with: "A1.03" + dont_confuse_reason: "A1.03 is inventory, O3.02 is feature availability" + O3.03: + name: "Scope Delivery" + definition: "Full scope of work completed" + positive_example: "Cleaned entire house" + negative_example: "Left the bathrooms" + dont_confuse_with: "J4.04" + dont_confuse_reason: "J4.04 is resolution quality, O3.03 is scope delivery" + O3.04: + name: "Documentation" + definition: "Supporting materials provided" + positive_example: "Great user manual" + negative_example: "No instructions at all" + dont_confuse_with: "J2.01" + dont_confuse_reason: "J2.01 is process simplicity, O3.04 is documentation as product artifact" + + O4: + name: "Fit" + definition: "Does it match the customer's specific needs?" + subcodes: + O4.01: + name: "Specification Match" + definition: "Matches what was ordered" + positive_example: "Exactly what I ordered" + negative_example: "Wrong size delivered" + dont_confuse_with: "J3.02" + dont_confuse_reason: "J3.02 is execution accuracy, O4.01 is spec match" + O4.02: + name: "Personalization" + definition: "Adapted to individual preferences" + positive_example: "Remembered my usual" + negative_example: "No way to save prefs" + dont_confuse_with: "P3.01" + dont_confuse_reason: "P3.01 is attentiveness, O4.02 is personalization" + O4.03: + name: "Flexibility" + definition: "Can be modified or adjusted" + positive_example: "Happy to substitute" + negative_example: "No modifications allowed" + dont_confuse_with: "V2.04" + dont_confuse_reason: "V2.04 is policy fairness, O4.03 is flexibility" + O4.04: + name: "Appropriateness" + definition: "Right solution for the need" + positive_example: "Perfect recommendation" + negative_example: "Sold me wrong thing" + dont_confuse_with: "P2.01" + dont_confuse_reason: "P2.01 is knowledge, O4.04 is appropriateness" + + P: + name: "People" + description: "Human interactions and personnel behavior" + core_question: "How do the people we interact with treat us and perform their roles?" + default_owner: "HR / Training" + categories: + P1: + name: "Attitude" + definition: "Disposition, manner, and emotional tone" + subcodes: + P1.01: + name: "Warmth/Friendliness" + definition: "Approachability and pleasantness" + positive_example: "So welcoming and kind" + negative_example: "Cold and unfriendly" + dont_confuse_with: "R4.03" + dont_confuse_reason: "R4.03 is relationship building, P1.01 is warmth" + P1.02: + name: "Respect" + definition: "Treating customer with dignity" + positive_example: "Made me feel valued" + negative_example: "Talked down to me" + dont_confuse_with: "A3.05" + dont_confuse_reason: "A3.05 is discrimination, P1.02 is general respect" + P1.03: + name: "Empathy" + definition: "Understanding customer's situation" + positive_example: "Really got my frustration" + negative_example: "Couldn't care less" + dont_confuse_with: "P4.02" + dont_confuse_reason: "P4.02 is listening, P1.03 is empathy" + P1.04: + name: "Patience" + definition: "Tolerance and calm under pressure" + positive_example: "Never rushed me" + negative_example: "Visibly annoyed" + dont_confuse_with: "J1.05" + dont_confuse_reason: "J1.05 is pacing, P1.04 is patience" + P1.05: + name: "Enthusiasm" + definition: "Energy and genuine interest" + positive_example: "Passionate about helping" + negative_example: "Going through motions" + dont_confuse_with: "P2.05" + dont_confuse_reason: "P2.05 is experience, P1.05 is enthusiasm" + + P2: + name: "Competence" + definition: "Knowledge, skill, and professional capability" + subcodes: + P2.01: + name: "Knowledge" + definition: "Understanding of products/services" + positive_example: "Knew every detail" + negative_example: "Couldn't answer basics" + dont_confuse_with: "O3.04" + dont_confuse_reason: "O3.04 is documentation, P2.01 is staff knowledge" + P2.02: + name: "Technical Skill" + definition: "Ability to perform required tasks" + positive_example: "Masterful technique" + negative_example: "Clearly undertrained" + dont_confuse_with: "O2.02" + dont_confuse_reason: "O2.02 is craftsmanship, P2.02 is staff skill" + P2.03: + name: "Problem-Solving" + definition: "Ability to address issues" + positive_example: "Found creative solution" + negative_example: "Just said 'can't'" + dont_confuse_with: "J4.02" + dont_confuse_reason: "J4.02 is resolution process, P2.03 is problem-solving ability" + P2.04: + name: "Professionalism" + definition: "Appropriate conduct and standards" + positive_example: "Very professional" + negative_example: "Inappropriate jokes" + dont_confuse_with: "P1.02" + dont_confuse_reason: "P1.02 is respect, P2.04 is professionalism" + P2.05: + name: "Experience" + definition: "Depth of expertise" + positive_example: "Clearly an expert" + negative_example: "Like talking to beginner" + dont_confuse_with: "R2.01" + dont_confuse_reason: "R2.01 is track record, P2.05 is experience" + + P3: + name: "Responsiveness" + definition: "Attentiveness, initiative, and follow-through" + subcodes: + P3.01: + name: "Attentiveness" + definition: "Awareness of customer needs" + positive_example: "Always checking in" + negative_example: "Had to flag them down" + dont_confuse_with: "O4.02" + dont_confuse_reason: "O4.02 is personalization, P3.01 is attentiveness" + P3.02: + name: "Initiative" + definition: "Proactive assistance" + positive_example: "Offered help unprompted" + negative_example: "Did bare minimum" + dont_confuse_with: "P4.03" + dont_confuse_reason: "P4.03 is proactive updates, P3.02 is initiative" + P3.03: + name: "Availability" + definition: "Present when needed" + positive_example: "Easy to find someone" + negative_example: "Impossible to reach" + dont_confuse_with: "A1.04" + dont_confuse_reason: "A1.04 is staffing levels, P3.03 is staff availability" + P3.04: + name: "Follow-Through" + definition: "Completing promised actions" + positive_example: "Did exactly as promised" + negative_example: "Never followed up" + dont_confuse_with: "R1.02" + dont_confuse_reason: "R1.02 is trust/pattern of promises, P3.04 is specific follow-through" + P3.05: + name: "Urgency" + definition: "Appropriate prioritization" + positive_example: "Treated as priority" + negative_example: "No sense of urgency" + dont_confuse_with: "J1.03" + dont_confuse_reason: "J1.03 is response time, P3.05 is urgency" + + P4: + name: "Communication" + definition: "Quality of information exchange" + subcodes: + P4.01: + name: "Clarity" + definition: "Understandable information" + positive_example: "Explained clearly" + negative_example: "Confusing jargon" + dont_confuse_with: "O3.04" + dont_confuse_reason: "O3.04 is documentation, P4.01 is communication clarity" + P4.02: + name: "Listening" + definition: "Hearing and understanding customer" + positive_example: "Really heard me" + negative_example: "Kept interrupting" + dont_confuse_with: "P1.03" + dont_confuse_reason: "P1.03 is empathy, P4.02 is listening" + P4.03: + name: "Proactive Updates" + definition: "Keeping customer informed" + positive_example: "Regular status updates" + negative_example: "Radio silence for weeks" + dont_confuse_with: "J4.01" + dont_confuse_reason: "J4.01 is acknowledgment, P4.03 is proactive updates" + P4.04: + name: "Accuracy" + definition: "Correctness of information" + positive_example: "Everything accurate" + negative_example: "Given wrong info" + dont_confuse_with: "V2.05" + dont_confuse_reason: "V2.05 is honest representation, P4.04 is information accuracy" + P4.05: + name: "Tone" + definition: "Appropriate communication style" + positive_example: "Professional but warm" + negative_example: "Condescending tone" + dont_confuse_with: "P1.02" + dont_confuse_reason: "P1.02 is respect, P4.05 is tone" + + J: + name: "Journey" + description: "The process, timing, and operational flow" + core_question: "Is the experience smooth, timely, and friction-free?" + default_owner: "Operations / Process" + categories: + J1: + name: "Timing" + definition: "Speed, punctuality, and time management" + subcodes: + J1.01: + name: "Wait Time" + definition: "Time spent waiting" + positive_example: "Seated immediately" + negative_example: "45 min past appointment" + dont_confuse_with: "A1.02" + dont_confuse_reason: "A1.02 is booking access, J1.01 is wait time" + J1.02: + name: "Service Speed" + definition: "Time for delivery/completion" + positive_example: "Next day delivery" + negative_example: "Took three weeks" + dont_confuse_with: "J4.03" + dont_confuse_reason: "J4.03 is resolution speed, J1.02 is service speed" + J1.03: + name: "Response Time" + definition: "Time to address inquiries" + positive_example: "Replied in minutes" + negative_example: "Days for a response" + dont_confuse_with: "P3.05" + dont_confuse_reason: "P3.05 is urgency, J1.03 is response time" + J1.04: + name: "Punctuality" + definition: "Meeting scheduled times" + positive_example: "Always on time" + negative_example: "Two hours late" + dont_confuse_with: "R2.02" + dont_confuse_reason: "R2.02 is consistency, J1.04 is punctuality" + J1.05: + name: "Pacing" + definition: "Appropriate speed (not rushed/dragged)" + positive_example: "Perfect timing" + negative_example: "Rushed us out" + dont_confuse_with: "P1.04" + dont_confuse_reason: "P1.04 is patience, J1.05 is pacing" + + J2: + name: "Ease" + definition: "Effort required and friction encountered" + subcodes: + J2.01: + name: "Simplicity" + definition: "Straightforward processes" + positive_example: "So easy to do" + negative_example: "Needlessly complicated" + dont_confuse_with: "E2.04" + dont_confuse_reason: "E2.04 is interface navigation, J2.01 is process simplicity" + J2.02: + name: "Navigation" + definition: "Finding what's needed" + positive_example: "Found it instantly" + negative_example: "Couldn't find anything" + dont_confuse_with: "E1.03" + dont_confuse_reason: "E1.03 is physical layout, J2.02 is finding things" + J2.03: + name: "Paperwork/Forms" + definition: "Documentation burden" + positive_example: "Minimal forms" + negative_example: "Endless paperwork" + dont_confuse_with: "V3.02" + dont_confuse_reason: "V3.02 is mental effort, J2.03 is paperwork" + J2.04: + name: "Handoffs" + definition: "Transitions between steps/people" + positive_example: "Seamless transfer" + negative_example: "Explained to 5 people" + dont_confuse_with: "P4.03" + dont_confuse_reason: "P4.03 is proactive updates, J2.04 is handoffs" + J2.05: + name: "Self-Service" + definition: "Customer autonomy options" + positive_example: "Great online portal" + negative_example: "Forced to call" + dont_confuse_with: "E2.02" + dont_confuse_reason: "E2.02 is digital functionality, J2.05 is self-service" + + J3: + name: "Reliability" + definition: "Consistency and predictability of process" + subcodes: + J3.01: + name: "Consistency" + definition: "Same result each time" + positive_example: "Always reliable" + negative_example: "Hit or miss quality" + dont_confuse_with: "O1.04" + dont_confuse_reason: "O1.04 is product reliability, J3.01 is process consistency" + J3.02: + name: "Accuracy" + definition: "Correct execution of requests" + positive_example: "Order exactly right" + negative_example: "Wrong items delivered" + dont_confuse_with: "O4.01" + dont_confuse_reason: "O4.01 is spec match, J3.02 is execution accuracy" + J3.03: + name: "Availability" + definition: "System/service uptime" + positive_example: "Never goes down" + negative_example: "Constant outages" + dont_confuse_with: "A1.03" + dont_confuse_reason: "A1.03 is inventory, J3.03 is system uptime" + J3.04: + name: "Predictability" + definition: "Expectations matched" + positive_example: "No surprises" + negative_example: "Never know what to expect" + dont_confuse_with: "V2.01" + dont_confuse_reason: "V2.01 is pricing clarity, J3.04 is predictability" + J3.05: + name: "Error Rate" + definition: "Frequency of mistakes" + positive_example: "Rarely makes mistakes" + negative_example: "Something wrong every time" + dont_confuse_with: "R2.02" + dont_confuse_reason: "R2.02 is dependability, J3.05 is error rate" + + J4: + name: "Resolution" + definition: "How problems are handled when they arise" + subcodes: + J4.01: + name: "Problem Acknowledgment" + definition: "Recognition of issues" + positive_example: "Immediately recognized" + negative_example: "Denied any problem" + dont_confuse_with: "R3.01" + dont_confuse_reason: "R3.01 is admitting failures (trust), J4.01 is recognition" + J4.02: + name: "Resolution Process" + definition: "How problems are handled" + positive_example: "Clear escalation path" + negative_example: "Transferred in circles" + dont_confuse_with: "P2.03" + dont_confuse_reason: "P2.03 is problem-solving, J4.02 is resolution process" + J4.03: + name: "Resolution Speed" + definition: "Time to fix" + positive_example: "Fixed same day" + negative_example: "Took weeks to resolve" + dont_confuse_with: "J1.02" + dont_confuse_reason: "J1.02 is service speed, J4.03 is resolution speed" + J4.04: + name: "Resolution Quality" + definition: "Adequacy of solution" + positive_example: "Completely fixed" + negative_example: "Band-aid fix" + dont_confuse_with: "R3.03" + dont_confuse_reason: "R3.03 is compensation, J4.04 is resolution quality" + J4.05: + name: "Prevention" + definition: "Efforts to avoid recurrence" + positive_example: "Changed their process" + negative_example: "Same issue happened again" + dont_confuse_with: "R3.04" + dont_confuse_reason: "R3.04 is improvement (trust), J4.05 is prevention" + + E: + name: "Environment" + description: "Physical, digital, and ambient context" + core_question: "Is the space where the experience occurs functional, safe, and pleasant?" + default_owner: "Facilities / IT" + categories: + E1: + name: "Physical Space" + definition: "Tangible environment attributes" + subcodes: + E1.01: + name: "Cleanliness" + definition: "Hygiene and tidiness" + positive_example: "Spotless facilities" + negative_example: "Filthy bathrooms" + dont_confuse_with: "E4.02" + dont_confuse_reason: "E4.02 is health/hygiene, E1.01 is cleanliness" + E1.02: + name: "Maintenance" + definition: "Condition and upkeep" + positive_example: "Everything works" + negative_example: "Broken equipment" + dont_confuse_with: "O1.01" + dont_confuse_reason: "O1.01 is product function, E1.02 is maintenance" + E1.03: + name: "Layout/Design" + definition: "Functional arrangement" + positive_example: "Easy to navigate" + negative_example: "Confusing layout" + dont_confuse_with: "J2.02" + dont_confuse_reason: "J2.02 is finding things, E1.03 is physical layout" + E1.04: + name: "Equipment" + definition: "Tools and amenities" + positive_example: "Modern machines" + negative_example: "Outdated everything" + dont_confuse_with: "O1.02" + dont_confuse_reason: "O1.02 is product performance, E1.04 is equipment" + E1.05: + name: "Signage" + definition: "Navigation aids" + positive_example: "Clear directions" + negative_example: "No signs anywhere" + dont_confuse_with: "A4.01" + dont_confuse_reason: "A4.01 is location, E1.05 is signage" + + E2: + name: "Digital Space" + definition: "Online and application interface" + subcodes: + E2.01: + name: "Interface Design" + definition: "Visual and interaction quality" + positive_example: "Beautiful app" + negative_example: "Cluttered mess" + dont_confuse_with: "O2.03" + dont_confuse_reason: "O2.03 is product presentation, E2.01 is interface design" + E2.02: + name: "Functionality" + definition: "Features working correctly" + positive_example: "Everything works" + negative_example: "Buttons broken" + dont_confuse_with: "O1.01" + dont_confuse_reason: "O1.01 is product function, E2.02 is digital functionality" + E2.03: + name: "Performance" + definition: "Speed and responsiveness" + positive_example: "Lightning fast" + negative_example: "Painfully slow" + dont_confuse_with: "O1.02" + dont_confuse_reason: "O1.02 is product performance, E2.03 is interface performance" + E2.04: + name: "Navigation" + definition: "Ease of finding things" + positive_example: "Intuitive menus" + negative_example: "Buried in submenus" + dont_confuse_with: "J2.01" + dont_confuse_reason: "J2.01 is process simplicity, E2.04 is interface navigation" + E2.05: + name: "Mobile Experience" + definition: "Smartphone optimization" + positive_example: "Great on phone" + negative_example: "Unusable on mobile" + dont_confuse_with: "A2.05" + dont_confuse_reason: "A2.05 is digital accessibility, E2.05 is mobile experience" + + E3: + name: "Ambiance" + definition: "Intangible environmental qualities" + subcodes: + E3.01: + name: "Atmosphere/Vibe" + definition: "Overall mood of space" + positive_example: "Calm and relaxing" + negative_example: "Stressful chaos" + dont_confuse_with: "P1" + dont_confuse_reason: "P1 is staff attitude, E3.01 is atmosphere" + E3.02: + name: "Noise Level" + definition: "Sound environment" + positive_example: "Pleasantly quiet" + negative_example: "Deafening noise" + dont_confuse_with: "E4.04" + dont_confuse_reason: "E4.04 is comfort, E3.02 is noise level" + E3.03: + name: "Temperature/Climate" + definition: "Thermal comfort" + positive_example: "Perfect temperature" + negative_example: "Freezing cold" + dont_confuse_with: "E4.04" + dont_confuse_reason: "E4.04 is comfort, E3.03 is temperature" + E3.04: + name: "Crowding" + definition: "Density and personal space" + positive_example: "Plenty of room" + negative_example: "Packed like sardines" + dont_confuse_with: "A1.03" + dont_confuse_reason: "A1.03 is capacity, E3.04 is crowding" + E3.05: + name: "Aesthetics" + definition: "Beauty and visual appeal" + positive_example: "Beautiful decor" + negative_example: "Depressing space" + dont_confuse_with: "O2.03" + dont_confuse_reason: "O2.03 is product presentation, E3.05 is space aesthetics" + + E4: + name: "Safety" + definition: "Security and wellbeing factors" + subcodes: + E4.01: + name: "Physical Safety" + definition: "Protection from harm" + positive_example: "Felt completely safe" + negative_example: "Dangerous conditions" + dont_confuse_with: "A2.01" + dont_confuse_reason: "A2.01 is physical accessibility, E4.01 is physical safety" + E4.02: + name: "Health/Hygiene" + definition: "Sanitation standards" + positive_example: "Strict protocols" + negative_example: "Questionable handling" + dont_confuse_with: "E1.01" + dont_confuse_reason: "E1.01 is cleanliness, E4.02 is health/hygiene" + E4.03: + name: "Security" + definition: "Protection of person/property" + positive_example: "Secure facility" + negative_example: "Things were stolen" + dont_confuse_with: "R1.03" + dont_confuse_reason: "R1.03 is transparency, E4.03 is security" + E4.04: + name: "Comfort" + definition: "Physical ease and wellbeing" + positive_example: "Comfortable seating" + negative_example: "Torture chairs" + dont_confuse_with: "E3" + dont_confuse_reason: "E3 is ambiance, E4.04 is comfort" + E4.05: + name: "Emergency Readiness" + definition: "Preparedness for incidents" + positive_example: "Clear exits marked" + negative_example: "No safety measures" + dont_confuse_with: "E1.05" + dont_confuse_reason: "E1.05 is signage, E4.05 is emergency readiness" + + A: + name: "Access" + description: "Availability, accessibility, and inclusivity" + core_question: "Can everyone who wants to participate do so fully and fairly?" + default_owner: "Compliance / Design" + categories: + A1: + name: "Availability" + definition: "Can you get it when you need it?" + subcodes: + A1.01: + name: "Operating Hours" + definition: "When service is accessible" + positive_example: "Open 24/7" + negative_example: "Banker's hours only" + dont_confuse_with: "P3.03" + dont_confuse_reason: "P3.03 is staff availability, A1.01 is operating hours" + A1.02: + name: "Booking Access" + definition: "Ability to schedule" + positive_example: "Easy online booking" + negative_example: "3 weeks for appointment" + dont_confuse_with: "J1.01" + dont_confuse_reason: "J1.01 is wait time, A1.02 is booking access" + A1.03: + name: "Inventory/Capacity" + definition: "Product/service available" + positive_example: "Always in stock" + negative_example: "Perpetually sold out" + dont_confuse_with: "E3.04" + dont_confuse_reason: "E3.04 is crowding, A1.03 is inventory" + A1.04: + name: "Staffing Levels" + definition: "Personnel available" + positive_example: "Plenty of staff" + negative_example: "Severely understaffed" + dont_confuse_with: "P3.03" + dont_confuse_reason: "P3.03 is availability, A1.04 is staffing levels" + A1.05: + name: "Geographic Reach" + definition: "Service area coverage" + positive_example: "Serves my area" + negative_example: "Not available here" + dont_confuse_with: "A4.01" + dont_confuse_reason: "A4.01 is location, A1.05 is geographic reach" + + A2: + name: "Accessibility" + definition: "Can everyone use it regardless of ability?" + subcodes: + A2.01: + name: "Physical Accessibility" + definition: "Mobility accommodations" + positive_example: "Wheelchair accessible" + negative_example: "No ramps or elevators" + dont_confuse_with: "E4.01" + dont_confuse_reason: "E4.01 is physical safety, A2.01 is physical accessibility" + A2.02: + name: "Visual Accessibility" + definition: "Sight accommodations" + positive_example: "Great alt text" + negative_example: "Can't use with screen reader" + dont_confuse_with: "E2.01" + dont_confuse_reason: "E2.01 is interface design, A2.02 is visual accessibility" + A2.03: + name: "Hearing Accessibility" + definition: "Audio accommodations" + positive_example: "Captions available" + negative_example: "No transcripts" + dont_confuse_with: "E2.02" + dont_confuse_reason: "E2.02 is functionality, A2.03 is hearing accessibility" + A2.04: + name: "Cognitive Accessibility" + definition: "Mental/learning accommodations" + positive_example: "Clear simple language" + negative_example: "Unnecessarily complex" + dont_confuse_with: "J2.01" + dont_confuse_reason: "J2.01 is simplicity, A2.04 is cognitive accessibility" + A2.05: + name: "Digital Accessibility" + definition: "Assistive technology support" + positive_example: "Works with JAWS" + negative_example: "Inaccessible app" + dont_confuse_with: "E2.05" + dont_confuse_reason: "E2.05 is mobile experience, A2.05 is digital accessibility" + + A3: + name: "Inclusivity" + definition: "Does it work for diverse backgrounds?" + subcodes: + A3.01: + name: "Language Support" + definition: "Multiple language options" + positive_example: "Staff spoke my language" + negative_example: "English only, no help" + dont_confuse_with: "P2.01" + dont_confuse_reason: "P2.01 is knowledge, A3.01 is language support" + A3.02: + name: "Cultural Sensitivity" + definition: "Respect for backgrounds" + positive_example: "Understood our customs" + negative_example: "Insensitive comments" + dont_confuse_with: "P1.02" + dont_confuse_reason: "P1.02 is respect, A3.02 is cultural sensitivity" + A3.03: + name: "Dietary/Medical" + definition: "Restriction accommodations" + positive_example: "Handled allergies well" + negative_example: "No options for me" + dont_confuse_with: "O4.03" + dont_confuse_reason: "O4.03 is flexibility, A3.03 is dietary/medical" + A3.04: + name: "Family Friendly" + definition: "Children/family accommodation" + positive_example: "Great for kids" + negative_example: "Not child-friendly" + dont_confuse_with: "E3.01" + dont_confuse_reason: "E3.01 is atmosphere, A3.04 is family friendly" + A3.05: + name: "Equal Treatment" + definition: "Non-discrimination" + positive_example: "Treated same as everyone" + negative_example: "Felt discriminated against" + dont_confuse_with: "P1.02" + dont_confuse_reason: "P1.02 is general respect, A3.05 is identity-based discrimination" + + A4: + name: "Convenience" + definition: "Is it easy to reach and engage with?" + subcodes: + A4.01: + name: "Location" + definition: "Physical accessibility" + positive_example: "Convenient location" + negative_example: "Middle of nowhere" + dont_confuse_with: "A1.05" + dont_confuse_reason: "A1.05 is geographic reach, A4.01 is location" + A4.02: + name: "Parking" + definition: "Vehicle accommodation" + positive_example: "Easy free parking" + negative_example: "Parking nightmare" + dont_confuse_with: "E4.03" + dont_confuse_reason: "E4.03 is security, A4.02 is parking" + A4.03: + name: "Transit Access" + definition: "Public transport options" + positive_example: "Right by subway" + negative_example: "No transit options" + dont_confuse_with: "A4.01" + dont_confuse_reason: "A4.01 is location, A4.03 is transit access" + A4.04: + name: "Payment Options" + definition: "How you can pay" + positive_example: "Takes all payments" + negative_example: "Cash only" + dont_confuse_with: "V1.05" + dont_confuse_reason: "V1.05 is payment flexibility, A4.04 is payment options" + A4.05: + name: "Contact Options" + definition: "Ways to reach business" + positive_example: "Chat, phone, email" + negative_example: "Phone only, long hold" + dont_confuse_with: "J2.05" + dont_confuse_reason: "J2.05 is self-service, A4.05 is contact options" + + V: + name: "Value" + description: "Cost, pricing, and worth of the exchange" + core_question: "Is what I'm giving up fair for what I'm getting?" + default_owner: "Finance / Pricing" + categories: + V1: + name: "Price" + definition: "The monetary cost" + subcodes: + V1.01: + name: "Absolute Price" + definition: "The actual cost" + positive_example: "Very affordable" + negative_example: "Outrageously expensive" + dont_confuse_with: "V4.02" + dont_confuse_reason: "V4.02 is quality-price ratio, V1.01 is absolute price" + V1.02: + name: "Price vs. Expectation" + definition: "Compared to anticipated" + positive_example: "Cheaper than expected" + negative_example: "Sticker shock" + dont_confuse_with: "V2.01" + dont_confuse_reason: "V2.01 is pricing clarity, V1.02 is price vs expectation" + V1.03: + name: "Price vs. Market" + definition: "Compared to competitors" + positive_example: "Best prices around" + negative_example: "Overpriced vs. others" + dont_confuse_with: "V4.01" + dont_confuse_reason: "V4.01 is overall value, V1.03 is market comparison" + V1.04: + name: "Hidden Costs" + definition: "Unexpected charges" + positive_example: "No hidden fees" + negative_example: "Surprise $50 charge" + dont_confuse_with: "V2.02" + dont_confuse_reason: "V2.02 is fee disclosure, V1.04 is hidden costs" + V1.05: + name: "Payment Flexibility" + definition: "Terms and options" + positive_example: "Great financing" + negative_example: "All upfront required" + dont_confuse_with: "A4.04" + dont_confuse_reason: "A4.04 is payment options, V1.05 is payment flexibility" + + V2: + name: "Transparency" + definition: "Clarity and honesty about costs" + subcodes: + V2.01: + name: "Pricing Clarity" + definition: "Understanding what costs what" + positive_example: "Clear price list" + negative_example: "Impossible to understand" + dont_confuse_with: "J3.04" + dont_confuse_reason: "J3.04 is predictability, V2.01 is pricing clarity" + V2.02: + name: "Fee Disclosure" + definition: "Upfront about all charges" + positive_example: "Full disclosure" + negative_example: "Hidden in fine print" + dont_confuse_with: "V1.04" + dont_confuse_reason: "V1.04 is hidden costs, V2.02 is fee disclosure" + V2.03: + name: "Advertising Accuracy" + definition: "Marketing matches reality" + positive_example: "As advertised" + negative_example: "Bait and switch" + dont_confuse_with: "R1.01" + dont_confuse_reason: "R1.01 is truthfulness, V2.03 is advertising accuracy" + V2.04: + name: "Terms Fairness" + definition: "Contract/policy reasonableness" + positive_example: "Fair cancellation policy" + negative_example: "Predatory contract" + dont_confuse_with: "R1.05" + dont_confuse_reason: "R1.05 is fair dealing, V2.04 is terms fairness" + V2.05: + name: "Honest Representation" + definition: "Truthful claims" + positive_example: "Accurate description" + negative_example: "Totally misleading" + dont_confuse_with: "R1.01" + dont_confuse_reason: "R1.01 is trust/truthfulness, V2.05 is honest representation" + + V3: + name: "Effort" + definition: "Non-monetary costs (time, hassle)" + subcodes: + V3.01: + name: "Time Investment" + definition: "Hours required" + positive_example: "Quick 10 minutes" + negative_example: "Wasted my whole day" + dont_confuse_with: "J1" + dont_confuse_reason: "J1 is timing, V3.01 is time investment" + V3.02: + name: "Mental Effort" + definition: "Cognitive load" + positive_example: "Effortless experience" + negative_example: "Exhausting to figure out" + dont_confuse_with: "J2.01" + dont_confuse_reason: "J2.01 is simplicity, V3.02 is mental effort" + V3.03: + name: "Physical Effort" + definition: "Bodily exertion" + positive_example: "Brought to my door" + negative_example: "Had to lug it upstairs" + dont_confuse_with: "A4" + dont_confuse_reason: "A4 is convenience, V3.03 is physical effort" + V3.04: + name: "Hassle Factor" + definition: "Cumulative frustration" + positive_example: "Smooth experience" + negative_example: "Death by thousand cuts" + dont_confuse_with: "J2" + dont_confuse_reason: "J2 is ease, V3.04 is hassle factor" + V3.05: + name: "Opportunity Cost" + definition: "What else could be done" + positive_example: "Worth the trip" + negative_example: "Not worth the drive" + dont_confuse_with: "V4.01" + dont_confuse_reason: "V4.01 is overall value, V3.05 is opportunity cost" + + V4: + name: "Worth" + definition: "Overall value assessment" + subcodes: + V4.01: + name: "Overall Value" + definition: "Total assessment" + positive_example: "Excellent value" + negative_example: "Total rip-off" + dont_confuse_with: "V1.01" + dont_confuse_reason: "V1.01 is absolute price, V4.01 is overall value" + V4.02: + name: "Quality-Price Ratio" + definition: "What you get for what you pay" + positive_example: "Great for the price" + negative_example: "Pay more, get less" + dont_confuse_with: "O2" + dont_confuse_reason: "O2 is quality, V4.02 is quality-price ratio" + V4.03: + name: "Satisfaction" + definition: "Contentment with exchange" + positive_example: "Very satisfied" + negative_example: "Deeply regret it" + dont_confuse_with: "O1.05" + dont_confuse_reason: "O1.05 is outcome achievement, V4.03 is satisfaction" + V4.04: + name: "Recommendation" + definition: "Would suggest to others" + positive_example: "Highly recommend" + negative_example: "Would warn everyone" + dont_confuse_with: "R4.03" + dont_confuse_reason: "R4.03 is relationship, V4.04 is recommendation" + V4.05: + name: "Return Intent" + definition: "Would come back" + positive_example: "Definitely returning" + negative_example: "Never again" + dont_confuse_with: "R4" + dont_confuse_reason: "R4 is loyalty, V4.05 is return intent" + + R: + name: "Relationship" + description: "Trust, reliability, and ongoing connection" + core_question: "Can I trust this business and do they value our relationship?" + default_owner: "Leadership / CX" + categories: + R1: + name: "Integrity" + definition: "Honesty and ethical behavior" + subcodes: + R1.01: + name: "Truthfulness" + definition: "Accurate representations" + positive_example: "Everything as stated" + negative_example: "They flat out lied" + dont_confuse_with: "V2.03" + dont_confuse_reason: "V2.03 is advertising accuracy, R1.01 is truthfulness" + R1.02: + name: "Promise Keeping" + definition: "Honoring commitments" + positive_example: "Always deliver on word" + negative_example: "Never keep promises" + dont_confuse_with: "P3.04" + dont_confuse_reason: "P3.04 is specific follow-through, R1.02 is trust/pattern" + R1.03: + name: "Transparency" + definition: "Openness about practices" + positive_example: "Full disclosure always" + negative_example: "Hidden agendas" + dont_confuse_with: "V2.02" + dont_confuse_reason: "V2.02 is fee disclosure, R1.03 is transparency" + R1.04: + name: "Ethics" + definition: "Moral business conduct" + positive_example: "Ethical company" + negative_example: "Shady business practices" + dont_confuse_with: "V2.04" + dont_confuse_reason: "V2.04 is terms fairness, R1.04 is ethics" + R1.05: + name: "Fair Dealing" + definition: "Equitable treatment" + positive_example: "Always treated fairly" + negative_example: "Felt taken advantage of" + dont_confuse_with: "A3.05" + dont_confuse_reason: "A3.05 is equal treatment, R1.05 is fair dealing" + + R2: + name: "Dependability" + definition: "Consistency over time" + subcodes: + R2.01: + name: "Track Record" + definition: "Historical performance" + positive_example: "Never let me down" + negative_example: "History of problems" + dont_confuse_with: "P2.05" + dont_confuse_reason: "P2.05 is experience, R2.01 is track record" + R2.02: + name: "Consistency" + definition: "Same experience over time" + positive_example: "Always great" + negative_example: "Varies wildly" + dont_confuse_with: "J3.01" + dont_confuse_reason: "J3.01 is process consistency, R2.02 is experience consistency" + R2.03: + name: "Stability" + definition: "Organizational continuity" + positive_example: "Stable company" + negative_example: "Constant changes" + dont_confuse_with: "J3.03" + dont_confuse_reason: "J3.03 is uptime, R2.03 is stability" + R2.04: + name: "Trustworthiness" + definition: "Warranting confidence" + positive_example: "Can count on them" + negative_example: "Don't trust them" + dont_confuse_with: "R1" + dont_confuse_reason: "R1 is integrity, R2.04 is trustworthiness" + R2.05: + name: "Guarantee Honor" + definition: "Standing behind product" + positive_example: "Honored warranty" + negative_example: "Worthless guarantee" + dont_confuse_with: "J4.04" + dont_confuse_reason: "J4.04 is resolution quality, R2.05 is guarantee honor" + + R3: + name: "Recovery" + definition: "Response to failures" + subcodes: + R3.01: + name: "Acknowledgment" + definition: "Admitting failures" + positive_example: "Owned their mistake" + negative_example: "Denied any wrongdoing" + dont_confuse_with: "J4.01" + dont_confuse_reason: "J4.01 is problem acknowledgment, R3.01 is admitting failures" + R3.02: + name: "Apology" + definition: "Expression of regret" + positive_example: "Sincere apology" + negative_example: "Non-apology apology" + dont_confuse_with: "P1.03" + dont_confuse_reason: "P1.03 is empathy, R3.02 is apology" + R3.03: + name: "Compensation" + definition: "Making amends" + positive_example: "More than made up for it" + negative_example: "Offered nothing" + dont_confuse_with: "J4.04" + dont_confuse_reason: "J4.04 is resolution quality, R3.03 is compensation" + R3.04: + name: "Improvement" + definition: "Actions to prevent recurrence" + positive_example: "Changed their process" + negative_example: "Same thing happens" + dont_confuse_with: "J4.05" + dont_confuse_reason: "J4.05 is prevention, R3.04 is improvement" + R3.05: + name: "Ownership" + definition: "Taking responsibility" + positive_example: "Took full responsibility" + negative_example: "Blamed me instead" + dont_confuse_with: "P2.03" + dont_confuse_reason: "P2.03 is problem-solving, R3.05 is ownership" + + R4: + name: "Loyalty" + definition: "Investment in ongoing relationship" + subcodes: + R4.01: + name: "Recognition" + definition: "Acknowledging repeat customers" + positive_example: "They remember me" + negative_example: "Stranger every time" + dont_confuse_with: "O4.02" + dont_confuse_reason: "O4.02 is personalization, R4.01 is recognition" + R4.02: + name: "Rewards" + definition: "Loyalty benefits" + positive_example: "Great perks" + negative_example: "Points are worthless" + dont_confuse_with: "V1" + dont_confuse_reason: "V1 is price, R4.02 is rewards" + R4.03: + name: "Relationship Building" + definition: "Investment in connection" + positive_example: "Personal relationship" + negative_example: "Purely transactional" + dont_confuse_with: "P1.01" + dont_confuse_reason: "P1.01 is friendliness, R4.03 is relationship building" + R4.04: + name: "Communication" + definition: "Ongoing contact quality" + positive_example: "Helpful newsletters" + negative_example: "Nothing but spam" + dont_confuse_with: "P4.03" + dont_confuse_reason: "P4.03 is proactive updates, R4.04 is communication" + R4.05: + name: "Community" + definition: "Belonging and connection" + positive_example: "Feel part of something" + negative_example: "No sense of community" + dont_confuse_with: "E3.01" + dont_confuse_reason: "E3.01 is atmosphere, R4.05 is community" + +# ============================================================================= +# CAUSAL CODES +# ============================================================================= + +causal_codes: + conditions: + layer: "conditions" + prefix: "CD-" + description: "What allowed the experience to happen?" + codes: + CD-S: + name: "Staff State" + definition: "Fatigue, training, motivation, experience" + CD-T: + name: "Team Dynamics" + definition: "Handoffs, coordination, communication" + CD-E: + name: "Equipment" + definition: "Malfunction, unavailable, outdated" + CD-F: + name: "Facility" + definition: "Maintenance, capacity, hazards" + CD-O: + name: "Operational" + definition: "Understaffing, demand surge, time pressure" + + management: + layer: "management" + prefix: "MG-" + description: "What decisions allowed enabling conditions?" + codes: + MG-P: + name: "Planning" + definition: "Staffing plans, scheduling, forecasting" + MG-T: + name: "Training" + definition: "Preparation, development, competency" + MG-O: + name: "Oversight" + definition: "Supervision, monitoring, correction" + MG-R: + name: "Resources" + definition: "Maintenance, supplies, equipment" + MG-C: + name: "Communication" + definition: "Policy relay, expectations, culture" + + systemic: + layer: "systemic" + prefix: "SY-" + description: "Why does the organization create these conditions?" + codes: + SY-R: + name: "Resource Decisions" + definition: "Budget, investment, staffing levels" + SY-P: + name: "Policy/Procedure" + definition: "Rules, requirements, bureaucracy" + SY-C: + name: "Culture" + definition: "Values, priorities, norms" + SY-S: + name: "Standards" + definition: "Quality thresholds, metrics, expectations" + SY-H: + name: "Human Capital" + definition: "Compensation, hiring, retention" + SY-X: + name: "External" + definition: "Market, regulatory, competitive pressure" + +# ============================================================================= +# METADATA DIMENSIONS +# ============================================================================= + +metadata_dimensions: + valence: + code: "V" + name: "Valence" + description: "Sentiment direction of the feedback" + values: + "V+": + label: "Positive" + definition: "Praise, satisfaction" + markers: + - "great" + - "loved" + - "excellent" + "V-": + label: "Negative" + definition: "Complaint, dissatisfaction" + markers: + - "terrible" + - "hated" + - "worst" + "V0": + label: "Neutral" + definition: "Observation without judgment" + markers: + - "they have" + - "it was" + - "factual" + "V±": + label: "Mixed" + definition: "Both positive and negative in same span" + markers: + - "good but" + - "despite" + - "however" + + intensity: + code: "I" + name: "Intensity" + description: "Strength of the sentiment" + values: + I1: + label: "Mild" + definition: "Slight preference/concern" + markers: + - "a bit" + - "somewhat" + - "could be better" + - "slightly" + I2: + label: "Moderate" + definition: "Clear but not extreme" + markers: + - "Standard adjectives without intensifiers" + I3: + label: "Strong" + definition: "Emphatic or intense" + markers: + - "extremely" + - "absolutely" + - "worst ever" + - "CAPS" + - "!!!" + - "profanity" + + specificity: + code: "S" + name: "Specificity" + description: "Level of detail provided" + values: + S1: + label: "Vague" + definition: "General impression only" + example: "Service was bad" + S2: + label: "Moderate" + definition: "Some details or context" + example: "Service was slow at dinner" + S3: + label: "Specific" + definition: "Concrete details, names, times, amounts" + example: "Waiter John took 40 mins for appetizers at 7pm Saturday" + + actionability: + code: "A" + name: "Actionability" + description: "How actionable is the feedback" + values: + A1: + label: "Low" + definition: "Feeling with no clear action path" + example: "I just didn't like it" + A2: + label: "Medium" + definition: "Suggests improvement area" + example: "Food could be warmer" + A3: + label: "High" + definition: "Specific implementable feedback" + example: "West bathroom stall lock is broken" + + temporal: + code: "T" + name: "Temporal Reference" + description: "Time frame of the feedback" + default: "TC" + values: + TC: + label: "Current" + definition: "This specific visit/experience" + TR: + label: "Recent" + definition: "Recent pattern of experiences" + TH: + label: "Historical" + definition: "Long-standing pattern" + TF: + label: "Future" + definition: "Expectations or predictions" + + evidence: + code: "E" + name: "Evidence Type" + description: "How the classification is supported" + default: "ES" + values: + ES: + label: "Stated" + definition: "Explicitly said by customer" + constraint: "Text directly says it" + EI: + label: "Inferred" + definition: "Logically entailed by text" + constraint: "Must be directly deducible, not speculative" + EC: + label: "Contextual" + definition: "Requires surrounding text" + constraint: "Span uses 'that,' 'they,' 'it' referencing earlier content" + + comparative: + code: "CR" + name: "Comparative Reference" + description: "Comparison to previous state" + default: "CR-N" + values: + CR-N: + label: "None" + definition: "No comparison to previous state" + trigger_words: [] + CR-B: + label: "Better" + definition: "Explicit improvement vs. before" + trigger_words: + - "better now" + - "improved" + - "finally fixed" + - "much faster than last time" + - "they've turned it around" + - "glad they addressed it" + CR-W: + label: "Worse" + definition: "Explicit decline vs. before" + trigger_words: + - "worse now" + - "used to be good" + - "has really gone downhill" + - "not like it used to be" + - "declining" + - "deteriorating" + - "they've really fallen off" + CR-S: + label: "Same" + definition: "Explicitly unchanged" + trigger_words: + - "still" + - "as always" + - "same as before" + - "nothing has changed" + - "yet again" + - "once again" + - "as usual" + +# ============================================================================= +# IMPLEMENTATION PROFILES +# ============================================================================= + +profiles: + lite: + name: "URT-Lite" + use_case: "Micro-business, quick triage, getting started" + code_tier: 1 + code_count: 7 + code_type: "domains" + complexity: "Minimal" + required_fields: + - "primary_code" + - "valence" + optional_fields: + - "intensity" + forbidden_fields: + - "secondary_codes" + - "specificity" + - "actionability" + - "evidence" + - "comparative" + - "causal_chain" + primary_code_pattern: "^[OPJEAVR]$" + secondary_codes_allowed: false + + core: + name: "URT-Core" + use_case: "Small business, dashboards, trend tracking" + code_tier: 2 + code_count: 28 + code_type: "categories" + complexity: "Low" + required_fields: + - "primary_code" + - "valence" + - "intensity" + optional_fields: + - "secondary_codes" + - "temporal" + - "comparative" + forbidden_fields: + - "specificity" + - "actionability" + - "evidence" + - "causal_chain" + primary_code_pattern: "^[OPJEAVR][1-4]$" + secondary_codes_allowed: true + secondary_codes_max: 2 + secondary_codes_tier: 2 + + standard: + name: "URT-Standard" + use_case: "Mid-size operations, team routing, full analytics" + code_tier: 3 + code_count: 140 + code_type: "subcodes" + complexity: "Medium" + required_fields: + - "primary_code" + - "secondary_codes" + - "valence" + - "intensity" + - "specificity" + - "actionability" + - "temporal" + - "evidence" + - "comparative" + optional_fields: + - "causal_chain" + - "linked_spans" + - "confidence" + forbidden_fields: [] + primary_code_pattern: "^[OPJEAVR][1-4]\\.[0-9]{2}$" + secondary_codes_allowed: true + secondary_codes_max: 2 + secondary_codes_tier: 3 + + full: + name: "URT-Full" + use_case: "Enterprise, root cause analysis, regulated contexts, audit" + code_tier: 3 + code_count: 156 + code_type: "subcodes + causal" + complexity: "High" + required_fields: + - "primary_code" + - "secondary_codes" + - "valence" + - "intensity" + - "specificity" + - "actionability" + - "temporal" + - "evidence" + - "comparative" + - "causal_chain" + - "linked_spans" + - "confidence" + - "annotator_notes" + optional_fields: [] + forbidden_fields: [] + primary_code_pattern: "^[OPJEAVR][1-4]\\.[0-9]{2}$" + secondary_codes_allowed: true + secondary_codes_max: 2 + secondary_codes_tier: 3 + +# ============================================================================= +# CODE LOOKUP INDICES +# ============================================================================= + +indices: + all_domains: + - "O" + - "P" + - "J" + - "E" + - "A" + - "V" + - "R" + + all_categories: + - "O1" + - "O2" + - "O3" + - "O4" + - "P1" + - "P2" + - "P3" + - "P4" + - "J1" + - "J2" + - "J3" + - "J4" + - "E1" + - "E2" + - "E3" + - "E4" + - "A1" + - "A2" + - "A3" + - "A4" + - "V1" + - "V2" + - "V3" + - "V4" + - "R1" + - "R2" + - "R3" + - "R4" + + all_subcodes: + # Offering (18 subcodes) + - "O1.01" + - "O1.02" + - "O1.03" + - "O1.04" + - "O1.05" + - "O2.01" + - "O2.02" + - "O2.03" + - "O2.04" + - "O2.05" + - "O3.01" + - "O3.02" + - "O3.03" + - "O3.04" + - "O4.01" + - "O4.02" + - "O4.03" + - "O4.04" + # People (20 subcodes) + - "P1.01" + - "P1.02" + - "P1.03" + - "P1.04" + - "P1.05" + - "P2.01" + - "P2.02" + - "P2.03" + - "P2.04" + - "P2.05" + - "P3.01" + - "P3.02" + - "P3.03" + - "P3.04" + - "P3.05" + - "P4.01" + - "P4.02" + - "P4.03" + - "P4.04" + - "P4.05" + # Journey (20 subcodes) + - "J1.01" + - "J1.02" + - "J1.03" + - "J1.04" + - "J1.05" + - "J2.01" + - "J2.02" + - "J2.03" + - "J2.04" + - "J2.05" + - "J3.01" + - "J3.02" + - "J3.03" + - "J3.04" + - "J3.05" + - "J4.01" + - "J4.02" + - "J4.03" + - "J4.04" + - "J4.05" + # Environment (20 subcodes) + - "E1.01" + - "E1.02" + - "E1.03" + - "E1.04" + - "E1.05" + - "E2.01" + - "E2.02" + - "E2.03" + - "E2.04" + - "E2.05" + - "E3.01" + - "E3.02" + - "E3.03" + - "E3.04" + - "E3.05" + - "E4.01" + - "E4.02" + - "E4.03" + - "E4.04" + - "E4.05" + # Access (20 subcodes) + - "A1.01" + - "A1.02" + - "A1.03" + - "A1.04" + - "A1.05" + - "A2.01" + - "A2.02" + - "A2.03" + - "A2.04" + - "A2.05" + - "A3.01" + - "A3.02" + - "A3.03" + - "A3.04" + - "A3.05" + - "A4.01" + - "A4.02" + - "A4.03" + - "A4.04" + - "A4.05" + # Value (20 subcodes) + - "V1.01" + - "V1.02" + - "V1.03" + - "V1.04" + - "V1.05" + - "V2.01" + - "V2.02" + - "V2.03" + - "V2.04" + - "V2.05" + - "V3.01" + - "V3.02" + - "V3.03" + - "V3.04" + - "V3.05" + - "V4.01" + - "V4.02" + - "V4.03" + - "V4.04" + - "V4.05" + # Relationship (20 subcodes) + - "R1.01" + - "R1.02" + - "R1.03" + - "R1.04" + - "R1.05" + - "R2.01" + - "R2.02" + - "R2.03" + - "R2.04" + - "R2.05" + - "R3.01" + - "R3.02" + - "R3.03" + - "R3.04" + - "R3.05" + - "R4.01" + - "R4.02" + - "R4.03" + - "R4.04" + - "R4.05" + + all_causal_codes: + - "CD-S" + - "CD-T" + - "CD-E" + - "CD-F" + - "CD-O" + - "MG-P" + - "MG-T" + - "MG-O" + - "MG-R" + - "MG-C" + - "SY-R" + - "SY-P" + - "SY-C" + - "SY-S" + - "SY-H" + - "SY-X" + + subcodes_by_domain: + O: 18 + P: 20 + J: 20 + E: 20 + A: 20 + V: 20 + R: 20 diff --git a/urt-taxonomy/track-b-engineering/B2-database-schema.sql b/urt-taxonomy/track-b-engineering/B2-database-schema.sql new file mode 100644 index 0000000..5c11d59 --- /dev/null +++ b/urt-taxonomy/track-b-engineering/B2-database-schema.sql @@ -0,0 +1,1126 @@ +-- ============================================================================= +-- B2: URT Database Schema +-- Universal Review Taxonomy v5.1 +-- ============================================================================= +-- +-- PostgreSQL schema for URT v5.1 classification storage and analytics. +-- Supports all implementation profiles (Lite, Core, Standard, Full). +-- +-- Design Principles: +-- 1. Normalized reference data (domains, categories, subcodes, causal codes) +-- 2. Flexible span classification with metadata dimensions +-- 3. Full issue lifecycle tracking per C1 framework +-- 4. Comprehensive audit trail for compliance +-- 5. Optimized for analytics with materialized views +-- 6. Partitioning-ready for high-volume scenarios +-- +-- Status: Production Ready +-- Version: 1.0 +-- Date: 2026-01-23 +-- Depends On: B1-urt-codes.yaml, C1-Issue-Lifecycle-Framework.md +-- ============================================================================= + +-- Enable required extensions +CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; +CREATE EXTENSION IF NOT EXISTS "btree_gist"; -- For exclusion constraints + +-- ============================================================================= +-- SECTION 1: REFERENCE TABLES +-- Core URT taxonomy structure from B1-urt-codes.yaml +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 1.1 Experience Domains (7 domains) +-- Top-level organizational structure +-- ----------------------------------------------------------------------------- +CREATE TABLE urt_domains ( + domain_code CHAR(1) PRIMARY KEY, + name VARCHAR(50) NOT NULL, + description TEXT NOT NULL, + core_question TEXT NOT NULL, + default_owner VARCHAR(100) NOT NULL, + display_order SMALLINT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT urt_domains_code_check + CHECK (domain_code IN ('O', 'P', 'J', 'E', 'A', 'V', 'R')) +); + +COMMENT ON TABLE urt_domains IS + 'URT v5.1 Experience Domains - 7 top-level classification areas'; + +-- ----------------------------------------------------------------------------- +-- 1.2 Categories (28 categories) +-- Second-tier classification within domains +-- ----------------------------------------------------------------------------- +CREATE TABLE urt_categories ( + category_code VARCHAR(2) PRIMARY KEY, + domain_code CHAR(1) NOT NULL REFERENCES urt_domains(domain_code), + name VARCHAR(50) NOT NULL, + definition TEXT NOT NULL, + display_order SMALLINT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT urt_categories_code_format + CHECK (category_code ~ '^[OPJEAVR][1-4]$') +); + +CREATE INDEX idx_categories_domain ON urt_categories(domain_code); + +COMMENT ON TABLE urt_categories IS + 'URT v5.1 Categories - 28 second-tier classifications within domains'; + +-- ----------------------------------------------------------------------------- +-- 1.3 Subcodes (138 subcodes per B1 actual count) +-- Third-tier diagnostic codes for detailed classification +-- ----------------------------------------------------------------------------- +CREATE TABLE urt_subcodes ( + subcode VARCHAR(6) PRIMARY KEY, + category_code VARCHAR(2) NOT NULL REFERENCES urt_categories(category_code), + domain_code CHAR(1) NOT NULL REFERENCES urt_domains(domain_code), + name VARCHAR(100) NOT NULL, + definition TEXT NOT NULL, + positive_example TEXT, + negative_example TEXT, + dont_confuse_with VARCHAR(6), + dont_confuse_reason TEXT, + display_order SMALLINT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT urt_subcodes_code_format + CHECK (subcode ~ '^[OPJEAVR][1-4]\.[0-9]{2}$') +); + +CREATE INDEX idx_subcodes_category ON urt_subcodes(category_code); +CREATE INDEX idx_subcodes_domain ON urt_subcodes(domain_code); + +COMMENT ON TABLE urt_subcodes IS + 'URT v5.1 Subcodes - 138 diagnostic-level classification codes'; + +-- ----------------------------------------------------------------------------- +-- 1.4 Causal Codes (16 codes across 3 layers) +-- For root cause analysis in Full profile +-- ----------------------------------------------------------------------------- +CREATE TABLE urt_causal_codes ( + causal_code VARCHAR(4) PRIMARY KEY, + layer VARCHAR(20) NOT NULL, + layer_prefix VARCHAR(3) NOT NULL, + name VARCHAR(50) NOT NULL, + definition TEXT NOT NULL, + display_order SMALLINT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT urt_causal_layer_check + CHECK (layer IN ('conditions', 'management', 'systemic')), + CONSTRAINT urt_causal_prefix_check + CHECK (layer_prefix IN ('CD-', 'MG-', 'SY-')), + CONSTRAINT urt_causal_code_format + CHECK (causal_code ~ '^(CD|MG|SY)-[A-Z]$') +); + +CREATE INDEX idx_causal_layer ON urt_causal_codes(layer); + +COMMENT ON TABLE urt_causal_codes IS + 'URT v5.1 Causal Codes - 16 root cause analysis codes (CD/MG/SY layers)'; + +-- ----------------------------------------------------------------------------- +-- 1.5 Metadata Dimension Values (24 values across 7 dimensions) +-- All possible metadata values for span classification +-- ----------------------------------------------------------------------------- +CREATE TABLE urt_metadata_values ( + dimension_code VARCHAR(2) NOT NULL, + value_code VARCHAR(4) NOT NULL, + dimension_name VARCHAR(30) NOT NULL, + label VARCHAR(30) NOT NULL, + definition TEXT NOT NULL, + is_default BOOLEAN NOT NULL DEFAULT FALSE, + display_order SMALLINT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + PRIMARY KEY (dimension_code, value_code), + + CONSTRAINT urt_metadata_dimension_check + CHECK (dimension_code IN ('V', 'I', 'S', 'A', 'T', 'E', 'CR')) +); + +CREATE INDEX idx_metadata_dimension ON urt_metadata_values(dimension_code); + +COMMENT ON TABLE urt_metadata_values IS + 'URT v5.1 Metadata Values - 24 values across 7 dimensions (V,I,S,A,T,E,CR)'; + +-- ============================================================================= +-- SECTION 2: CORE CLASSIFICATION TABLES +-- Reviews, spans, and classifications +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 2.1 Reviews +-- Original review text and source metadata +-- ----------------------------------------------------------------------------- +CREATE TABLE reviews ( + review_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + external_id VARCHAR(255), -- ID from source system (e.g., Google place_id) + source VARCHAR(50) NOT NULL, -- 'google', 'yelp', 'tripadvisor', etc. + business_id VARCHAR(255), -- Business identifier + author_name VARCHAR(255), + author_id VARCHAR(255), + review_text TEXT NOT NULL, + star_rating NUMERIC(2,1), -- 1.0-5.0 scale + review_date DATE, + language_code VARCHAR(5), -- ISO 639-1 + raw_metadata JSONB, -- Source-specific metadata + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + deleted_at TIMESTAMPTZ, -- Soft delete support + + CONSTRAINT reviews_rating_check + CHECK (star_rating IS NULL OR (star_rating >= 1.0 AND star_rating <= 5.0)) +); + +CREATE INDEX idx_reviews_source ON reviews(source); +CREATE INDEX idx_reviews_business ON reviews(business_id); +CREATE INDEX idx_reviews_date ON reviews(review_date); +CREATE INDEX idx_reviews_external ON reviews(external_id) WHERE external_id IS NOT NULL; +CREATE INDEX idx_reviews_created ON reviews(created_at); +CREATE INDEX idx_reviews_deleted ON reviews(deleted_at) WHERE deleted_at IS NULL; + +COMMENT ON TABLE reviews IS + 'Original customer reviews from various sources'; + +-- ----------------------------------------------------------------------------- +-- 2.2 Spans +-- Individual classified text segments within reviews +-- A single review may contain multiple spans (composite review decomposition) +-- ----------------------------------------------------------------------------- +CREATE TABLE spans ( + span_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + review_id UUID NOT NULL REFERENCES reviews(review_id) ON DELETE CASCADE, + span_text TEXT NOT NULL, + char_start INTEGER, -- Start position in review_text + char_end INTEGER, -- End position in review_text + span_order SMALLINT NOT NULL DEFAULT 1, -- Order within review + + -- Implementation profile used + profile VARCHAR(10) NOT NULL DEFAULT 'standard', + + -- Primary classification (required for all profiles) + primary_code VARCHAR(6) NOT NULL, + primary_tier SMALLINT NOT NULL, -- 1=domain, 2=category, 3=subcode + + -- Metadata dimensions (availability depends on profile) + valence VARCHAR(2) NOT NULL, + intensity VARCHAR(2) NOT NULL, + specificity VARCHAR(2), -- Standard+ only + actionability VARCHAR(2), -- Standard+ only + temporal VARCHAR(2) DEFAULT 'TC', + evidence VARCHAR(2) DEFAULT 'ES', + comparative VARCHAR(4) DEFAULT 'CR-N', + + -- Extended attributes for issue aggregation + entity_reference VARCHAR(255), -- Product, person, feature + location_reference VARCHAR(255), -- Physical or logical location + + -- Confidence and annotation metadata + confidence_score NUMERIC(3,2), -- 0.00-1.00 + annotator_notes TEXT, + annotation_source VARCHAR(20), -- 'human', 'llm', 'hybrid' + + -- Timestamps + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + deleted_at TIMESTAMPTZ, + + CONSTRAINT spans_profile_check + CHECK (profile IN ('lite', 'core', 'standard', 'full')), + CONSTRAINT spans_tier_check + CHECK (primary_tier IN (1, 2, 3)), + CONSTRAINT spans_valence_check + CHECK (valence IN ('V+', 'V-', 'V0', 'V±')), + CONSTRAINT spans_intensity_check + CHECK (intensity IN ('I1', 'I2', 'I3')), + CONSTRAINT spans_specificity_check + CHECK (specificity IS NULL OR specificity IN ('S1', 'S2', 'S3')), + CONSTRAINT spans_actionability_check + CHECK (actionability IS NULL OR actionability IN ('A1', 'A2', 'A3')), + CONSTRAINT spans_temporal_check + CHECK (temporal IS NULL OR temporal IN ('TC', 'TR', 'TH', 'TF')), + CONSTRAINT spans_evidence_check + CHECK (evidence IS NULL OR evidence IN ('ES', 'EI', 'EC')), + CONSTRAINT spans_comparative_check + CHECK (comparative IS NULL OR comparative IN ('CR-N', 'CR-B', 'CR-W', 'CR-S')), + CONSTRAINT spans_confidence_check + CHECK (confidence_score IS NULL OR (confidence_score >= 0 AND confidence_score <= 1)), + CONSTRAINT spans_char_range_check + CHECK ((char_start IS NULL AND char_end IS NULL) OR (char_start < char_end)) +); + +CREATE INDEX idx_spans_review ON spans(review_id); +CREATE INDEX idx_spans_primary_code ON spans(primary_code); +CREATE INDEX idx_spans_valence ON spans(valence); +CREATE INDEX idx_spans_intensity ON spans(intensity); +CREATE INDEX idx_spans_comparative ON spans(comparative) WHERE comparative != 'CR-N'; +CREATE INDEX idx_spans_created ON spans(created_at); +CREATE INDEX idx_spans_deleted ON spans(deleted_at) WHERE deleted_at IS NULL; +CREATE INDEX idx_spans_entity ON spans(entity_reference) WHERE entity_reference IS NOT NULL; +CREATE INDEX idx_spans_location ON spans(location_reference) WHERE location_reference IS NOT NULL; + +-- Composite indexes for common query patterns +CREATE INDEX idx_spans_classification ON spans(primary_code, valence, intensity); +CREATE INDEX idx_spans_negative ON spans(primary_code, created_at) WHERE valence = 'V-'; + +COMMENT ON TABLE spans IS + 'Individual classified text segments from reviews with URT metadata'; + +-- ----------------------------------------------------------------------------- +-- 2.3 Span Classifications (Secondary Codes) +-- Supports up to 2 secondary codes per span (Standard+ profiles) +-- ----------------------------------------------------------------------------- +CREATE TABLE span_classifications ( + classification_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + span_id UUID NOT NULL REFERENCES spans(span_id) ON DELETE CASCADE, + code VARCHAR(6) NOT NULL, + code_tier SMALLINT NOT NULL, + is_primary BOOLEAN NOT NULL DEFAULT FALSE, + classification_order SMALLINT NOT NULL DEFAULT 1, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT span_class_tier_check + CHECK (code_tier IN (1, 2, 3)), + CONSTRAINT span_class_order_check + CHECK (classification_order BETWEEN 1 AND 3), + + -- Ensure max 3 classifications per span (1 primary + 2 secondary) + UNIQUE (span_id, classification_order) +); + +CREATE INDEX idx_span_class_span ON span_classifications(span_id); +CREATE INDEX idx_span_class_code ON span_classifications(code); +CREATE INDEX idx_span_class_primary ON span_classifications(span_id) WHERE is_primary = TRUE; + +COMMENT ON TABLE span_classifications IS + 'Primary and secondary code assignments for spans (max 3 per span)'; + +-- ----------------------------------------------------------------------------- +-- 2.4 Causal Chains +-- Links spans to causal codes (CD -> MG -> SY) for Full profile +-- ----------------------------------------------------------------------------- +CREATE TABLE causal_chains ( + chain_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + span_id UUID NOT NULL REFERENCES spans(span_id) ON DELETE CASCADE, + + -- Causal chain: Conditions -> Management -> Systemic + condition_code VARCHAR(4) REFERENCES urt_causal_codes(causal_code), + management_code VARCHAR(4) REFERENCES urt_causal_codes(causal_code), + systemic_code VARCHAR(4) REFERENCES urt_causal_codes(causal_code), + + -- Confidence in causal attribution + chain_confidence NUMERIC(3,2), + analyst_notes TEXT, + + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT causal_chain_layer_check CHECK ( + (condition_code IS NULL OR condition_code ~ '^CD-') AND + (management_code IS NULL OR management_code ~ '^MG-') AND + (systemic_code IS NULL OR systemic_code ~ '^SY-') + ), + CONSTRAINT causal_chain_minimum CHECK ( + condition_code IS NOT NULL OR management_code IS NOT NULL OR systemic_code IS NOT NULL + ) +); + +CREATE INDEX idx_causal_span ON causal_chains(span_id); +CREATE INDEX idx_causal_condition ON causal_chains(condition_code) WHERE condition_code IS NOT NULL; +CREATE INDEX idx_causal_management ON causal_chains(management_code) WHERE management_code IS NOT NULL; +CREATE INDEX idx_causal_systemic ON causal_chains(systemic_code) WHERE systemic_code IS NOT NULL; + +COMMENT ON TABLE causal_chains IS + 'Root cause analysis chains linking spans to CD/MG/SY causal codes'; + +-- ============================================================================= +-- SECTION 3: ISSUE TRACKING TABLES +-- Based on C1 Issue Lifecycle Framework +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 3.1 Issues +-- Aggregated issue records from negative spans +-- ----------------------------------------------------------------------------- +CREATE TABLE issues ( + issue_id VARCHAR(20) PRIMARY KEY, -- Format: ISSUE-YYYY-NNNN + + -- Classification context + primary_subcode VARCHAR(6) NOT NULL, + domain_code CHAR(1) NOT NULL REFERENCES urt_domains(domain_code), + + -- Aggregation context + entity_reference VARCHAR(255), + location_reference VARCHAR(255), + + -- Current state (per C1 state machine) + state VARCHAR(15) NOT NULL DEFAULT 'DETECTED', + state_changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + -- Metrics from aggregated spans + span_count INTEGER NOT NULL DEFAULT 1, + max_intensity VARCHAR(2) NOT NULL, + priority_score NUMERIC(6,2) NOT NULL, + confidence_score NUMERIC(3,2) NOT NULL, + + -- Ownership + owner_team VARCHAR(100), + owner_individual VARCHAR(100), + + -- Resolution details + resolution_code VARCHAR(20), + resolution_notes TEXT, + decline_reason VARCHAR(10), + + -- Causal analysis (for Full profile) + causal_codes VARCHAR(4)[], + + -- Recurrence tracking + reopen_count INTEGER NOT NULL DEFAULT 0, + verification_window_days INTEGER DEFAULT 60, + + -- Key timestamps + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + acknowledged_at TIMESTAMPTZ, + work_started_at TIMESTAMPTZ, + resolved_at TIMESTAMPTZ, + verified_at TIMESTAMPTZ, + declined_at TIMESTAMPTZ, + + -- Soft delete + deleted_at TIMESTAMPTZ, + + CONSTRAINT issues_state_check CHECK ( + state IN ('DETECTED', 'ACKNOWLEDGED', 'IN_PROGRESS', 'RESOLVED', + 'VERIFIED', 'DECLINED', 'REOPENED', 'STALE') + ), + CONSTRAINT issues_intensity_check + CHECK (max_intensity IN ('I1', 'I2', 'I3')), + CONSTRAINT issues_decline_reason_check CHECK ( + decline_reason IS NULL OR + decline_reason IN ('DEC-DUP', 'DEC-OOS', 'DEC-INS', 'DEC-NAR', + 'DEC-EXT', 'DEC-POL', 'DEC-OLD') + ), + CONSTRAINT issues_verification_window_check + CHECK (verification_window_days IN (30, 60, 90)) +); + +CREATE INDEX idx_issues_state ON issues(state); +CREATE INDEX idx_issues_domain ON issues(domain_code); +CREATE INDEX idx_issues_subcode ON issues(primary_subcode); +CREATE INDEX idx_issues_priority ON issues(priority_score DESC); +CREATE INDEX idx_issues_created ON issues(created_at); +CREATE INDEX idx_issues_owner_team ON issues(owner_team); +CREATE INDEX idx_issues_deleted ON issues(deleted_at) WHERE deleted_at IS NULL; + +-- Partial indexes for active issues +CREATE INDEX idx_issues_open ON issues(priority_score DESC) + WHERE state IN ('DETECTED', 'ACKNOWLEDGED', 'IN_PROGRESS', 'REOPENED'); +CREATE INDEX idx_issues_pending_verification ON issues(resolved_at, verification_window_days) + WHERE state = 'RESOLVED'; + +COMMENT ON TABLE issues IS + 'Aggregated issues from negative feedback spans per C1 lifecycle framework'; + +-- ----------------------------------------------------------------------------- +-- 3.2 Issue-Span Links +-- Many-to-many relationship between issues and contributing spans +-- ----------------------------------------------------------------------------- +CREATE TABLE issue_spans ( + issue_id VARCHAR(20) NOT NULL REFERENCES issues(issue_id) ON DELETE CASCADE, + span_id UUID NOT NULL REFERENCES spans(span_id) ON DELETE CASCADE, + linked_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + link_type VARCHAR(20) NOT NULL DEFAULT 'contributor', + correlation_score NUMERIC(3,2), + + PRIMARY KEY (issue_id, span_id), + + CONSTRAINT issue_spans_link_type_check + CHECK (link_type IN ('contributor', 'verification', 'reopen_trigger')) +); + +CREATE INDEX idx_issue_spans_span ON issue_spans(span_id); +CREATE INDEX idx_issue_spans_linked ON issue_spans(linked_at); + +COMMENT ON TABLE issue_spans IS + 'Links between issues and their contributing spans'; + +-- ----------------------------------------------------------------------------- +-- 3.3 Issue State History +-- Complete audit trail of state transitions +-- ----------------------------------------------------------------------------- +CREATE TABLE issue_state_history ( + history_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + issue_id VARCHAR(20) NOT NULL REFERENCES issues(issue_id) ON DELETE CASCADE, + + from_state VARCHAR(15), + to_state VARCHAR(15) NOT NULL, + trigger_type VARCHAR(20) NOT NULL, -- 'manual', 'auto', 'span', 'sla' + trigger_span_id UUID REFERENCES spans(span_id), + + actor_id VARCHAR(100), + actor_type VARCHAR(20), -- 'user', 'system', 'rule' + notes TEXT, + + transitioned_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT history_state_check CHECK ( + to_state IN ('DETECTED', 'ACKNOWLEDGED', 'IN_PROGRESS', 'RESOLVED', + 'VERIFIED', 'DECLINED', 'REOPENED', 'STALE') + ) +); + +CREATE INDEX idx_history_issue ON issue_state_history(issue_id); +CREATE INDEX idx_history_transition ON issue_state_history(transitioned_at); +CREATE INDEX idx_history_state ON issue_state_history(to_state); + +COMMENT ON TABLE issue_state_history IS + 'Audit trail of all issue state transitions'; + +-- ----------------------------------------------------------------------------- +-- 3.4 Issue Resolutions +-- Detailed resolution records for resolved/verified issues +-- ----------------------------------------------------------------------------- +CREATE TABLE issue_resolutions ( + resolution_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + issue_id VARCHAR(20) NOT NULL REFERENCES issues(issue_id) ON DELETE CASCADE, + + resolution_code VARCHAR(20) NOT NULL, + resolution_type VARCHAR(30) NOT NULL, -- 'fix', 'workaround', 'policy_change', etc. + resolution_summary TEXT NOT NULL, + resolution_details TEXT, + + -- Preventive measures + prevention_notes TEXT, + process_changes TEXT, + + -- Verification + verified_by_span_id UUID REFERENCES spans(span_id), + verification_method VARCHAR(20), -- 'cr_b', 'positive_span', 'time_based' + + resolved_by VARCHAR(100), + resolved_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + verified_at TIMESTAMPTZ, + + CONSTRAINT resolution_type_check CHECK ( + resolution_type IN ('fix', 'workaround', 'policy_change', 'training', + 'process_improvement', 'equipment', 'other') + ) +); + +CREATE INDEX idx_resolutions_issue ON issue_resolutions(issue_id); +CREATE INDEX idx_resolutions_code ON issue_resolutions(resolution_code); +CREATE INDEX idx_resolutions_resolved ON issue_resolutions(resolved_at); + +COMMENT ON TABLE issue_resolutions IS + 'Detailed resolution records with verification tracking'; + +-- ============================================================================= +-- SECTION 4: AUDIT AND HISTORY TABLES +-- Comprehensive tracking for compliance and analytics +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 4.1 Annotation Audit +-- Who annotated what, when, and how +-- ----------------------------------------------------------------------------- +CREATE TABLE annotation_audit ( + audit_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + span_id UUID NOT NULL REFERENCES spans(span_id) ON DELETE CASCADE, + + annotator_id VARCHAR(100) NOT NULL, + annotator_type VARCHAR(20) NOT NULL, -- 'human', 'llm', 'rule' + model_version VARCHAR(50), -- For LLM annotations + + -- What was set + field_name VARCHAR(30) NOT NULL, + old_value TEXT, + new_value TEXT NOT NULL, + + -- Confidence and reasoning + confidence NUMERIC(3,2), + reasoning TEXT, + + annotated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT audit_annotator_type_check + CHECK (annotator_type IN ('human', 'llm', 'rule', 'hybrid')) +); + +CREATE INDEX idx_audit_span ON annotation_audit(span_id); +CREATE INDEX idx_audit_annotator ON annotation_audit(annotator_id); +CREATE INDEX idx_audit_field ON annotation_audit(field_name); +CREATE INDEX idx_audit_time ON annotation_audit(annotated_at); + +COMMENT ON TABLE annotation_audit IS + 'Complete audit trail of all span annotation changes'; + +-- ----------------------------------------------------------------------------- +-- 4.2 Classification History +-- Track changes to span classifications over time +-- ----------------------------------------------------------------------------- +CREATE TABLE classification_history ( + history_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + span_id UUID NOT NULL REFERENCES spans(span_id) ON DELETE CASCADE, + + change_type VARCHAR(20) NOT NULL, -- 'create', 'update', 'delete' + + -- Previous state (null for create) + prev_primary_code VARCHAR(6), + prev_valence VARCHAR(2), + prev_intensity VARCHAR(2), + prev_secondary_codes VARCHAR(6)[], + + -- New state (null for delete) + new_primary_code VARCHAR(6), + new_valence VARCHAR(2), + new_intensity VARCHAR(2), + new_secondary_codes VARCHAR(6)[], + + change_reason TEXT, + changed_by VARCHAR(100) NOT NULL, + changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + CONSTRAINT history_change_type_check + CHECK (change_type IN ('create', 'update', 'delete')) +); + +CREATE INDEX idx_class_history_span ON classification_history(span_id); +CREATE INDEX idx_class_history_time ON classification_history(changed_at); +CREATE INDEX idx_class_history_type ON classification_history(change_type); + +COMMENT ON TABLE classification_history IS + 'Historical record of classification changes for audit and rollback'; + +-- ============================================================================= +-- SECTION 5: ANALYTICS VIEWS AND MATERIALIZED VIEWS +-- Pre-computed aggregations for dashboard and reporting +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 5.1 Domain Summary View +-- Current counts and averages by domain +-- ----------------------------------------------------------------------------- +CREATE MATERIALIZED VIEW mv_domain_summary AS +SELECT + d.domain_code, + d.name AS domain_name, + d.default_owner, + COUNT(DISTINCT s.span_id) AS total_spans, + COUNT(DISTINCT s.span_id) FILTER (WHERE s.valence = 'V+') AS positive_spans, + COUNT(DISTINCT s.span_id) FILTER (WHERE s.valence = 'V-') AS negative_spans, + COUNT(DISTINCT s.span_id) FILTER (WHERE s.valence = 'V0') AS neutral_spans, + COUNT(DISTINCT s.span_id) FILTER (WHERE s.valence = 'V±') AS mixed_spans, + COUNT(DISTINCT s.span_id) FILTER (WHERE s.intensity = 'I3') AS critical_spans, + ROUND(AVG(s.confidence_score), 3) AS avg_confidence, + COUNT(DISTINCT i.issue_id) FILTER (WHERE i.state NOT IN ('VERIFIED', 'DECLINED')) AS open_issues, + MAX(s.created_at) AS last_span_at +FROM urt_domains d +LEFT JOIN spans s ON LEFT(s.primary_code, 1) = d.domain_code + AND s.deleted_at IS NULL +LEFT JOIN issues i ON i.domain_code = d.domain_code + AND i.deleted_at IS NULL +GROUP BY d.domain_code, d.name, d.default_owner +ORDER BY d.display_order; + +CREATE UNIQUE INDEX idx_mv_domain_summary ON mv_domain_summary(domain_code); + +COMMENT ON MATERIALIZED VIEW mv_domain_summary IS + 'Aggregated metrics by URT domain for executive dashboards'; + +-- ----------------------------------------------------------------------------- +-- 5.2 Category Breakdown View +-- Detailed metrics at category level +-- ----------------------------------------------------------------------------- +CREATE MATERIALIZED VIEW mv_category_breakdown AS +SELECT + c.category_code, + c.name AS category_name, + c.domain_code, + d.name AS domain_name, + COUNT(DISTINCT s.span_id) AS total_spans, + COUNT(DISTINCT s.span_id) FILTER (WHERE s.valence = 'V-') AS negative_count, + COUNT(DISTINCT s.span_id) FILTER (WHERE s.valence = 'V+') AS positive_count, + ROUND( + COUNT(DISTINCT s.span_id) FILTER (WHERE s.valence = 'V-')::NUMERIC / + NULLIF(COUNT(DISTINCT s.span_id), 0) * 100, 1 + ) AS negative_pct, + COUNT(DISTINCT i.issue_id) AS total_issues, + COUNT(DISTINCT i.issue_id) FILTER (WHERE i.state = 'VERIFIED') AS resolved_verified, + ROUND(AVG(CASE + WHEN s.intensity = 'I1' THEN 1 + WHEN s.intensity = 'I2' THEN 2 + WHEN s.intensity = 'I3' THEN 3 + END), 2) AS avg_intensity +FROM urt_categories c +JOIN urt_domains d ON c.domain_code = d.domain_code +LEFT JOIN spans s ON s.primary_code LIKE c.category_code || '%' + AND s.deleted_at IS NULL +LEFT JOIN issues i ON i.primary_subcode LIKE c.category_code || '%' + AND i.deleted_at IS NULL +GROUP BY c.category_code, c.name, c.domain_code, d.name +ORDER BY c.domain_code, c.display_order; + +CREATE UNIQUE INDEX idx_mv_category_breakdown ON mv_category_breakdown(category_code); + +COMMENT ON MATERIALIZED VIEW mv_category_breakdown IS + 'Detailed category-level metrics for operational analysis'; + +-- ----------------------------------------------------------------------------- +-- 5.3 Issue Pipeline View +-- Current state of all open issues +-- ----------------------------------------------------------------------------- +CREATE MATERIALIZED VIEW mv_issue_pipeline AS +SELECT + i.state, + i.domain_code, + d.name AS domain_name, + COUNT(*) AS issue_count, + AVG(i.priority_score) AS avg_priority, + AVG(i.span_count) AS avg_span_count, + AVG(EXTRACT(EPOCH FROM (NOW() - i.created_at)) / 3600) AS avg_age_hours, + COUNT(*) FILTER (WHERE i.max_intensity = 'I3') AS critical_count, + COUNT(*) FILTER (WHERE i.reopen_count > 0) AS reopened_count +FROM issues i +JOIN urt_domains d ON i.domain_code = d.domain_code +WHERE i.deleted_at IS NULL + AND i.state NOT IN ('VERIFIED', 'DECLINED') +GROUP BY i.state, i.domain_code, d.name +ORDER BY + CASE i.state + WHEN 'DETECTED' THEN 1 + WHEN 'ACKNOWLEDGED' THEN 2 + WHEN 'IN_PROGRESS' THEN 3 + WHEN 'REOPENED' THEN 4 + WHEN 'RESOLVED' THEN 5 + ELSE 6 + END, + d.display_order; + +CREATE INDEX idx_mv_issue_pipeline ON mv_issue_pipeline(state, domain_code); + +COMMENT ON MATERIALIZED VIEW mv_issue_pipeline IS + 'Current issue pipeline by state and domain for SLA tracking'; + +-- ----------------------------------------------------------------------------- +-- 5.4 Comparative Reference Trends View +-- Track improvement/decline signals over time +-- ----------------------------------------------------------------------------- +CREATE MATERIALIZED VIEW mv_cr_trends AS +SELECT + DATE_TRUNC('week', s.created_at) AS week_start, + s.comparative, + LEFT(s.primary_code, 1) AS domain_code, + COUNT(*) AS span_count, + COUNT(*) FILTER (WHERE s.valence = 'V+') AS positive_count, + COUNT(*) FILTER (WHERE s.valence = 'V-') AS negative_count +FROM spans s +WHERE s.deleted_at IS NULL + AND s.comparative IS NOT NULL + AND s.created_at >= NOW() - INTERVAL '90 days' +GROUP BY DATE_TRUNC('week', s.created_at), s.comparative, LEFT(s.primary_code, 1) +ORDER BY week_start DESC, domain_code; + +CREATE INDEX idx_mv_cr_trends ON mv_cr_trends(week_start, comparative); + +COMMENT ON MATERIALIZED VIEW mv_cr_trends IS + 'Weekly trends of comparative reference signals (CR-B/W/S) for improvement tracking'; + +-- ----------------------------------------------------------------------------- +-- 5.5 Daily Span Volume (for time-series analysis) +-- Partitioning-ready daily aggregation +-- ----------------------------------------------------------------------------- +CREATE MATERIALIZED VIEW mv_daily_volume AS +SELECT + DATE(s.created_at) AS span_date, + LEFT(s.primary_code, 1) AS domain_code, + s.valence, + s.intensity, + COUNT(*) AS span_count, + COUNT(DISTINCT s.review_id) AS review_count, + AVG(s.confidence_score) AS avg_confidence +FROM spans s +WHERE s.deleted_at IS NULL +GROUP BY DATE(s.created_at), LEFT(s.primary_code, 1), s.valence, s.intensity +ORDER BY span_date DESC; + +CREATE INDEX idx_mv_daily_volume_date ON mv_daily_volume(span_date); +CREATE INDEX idx_mv_daily_volume_domain ON mv_daily_volume(domain_code); + +COMMENT ON MATERIALIZED VIEW mv_daily_volume IS + 'Daily span volume by domain/valence/intensity for trend analysis'; + +-- ============================================================================= +-- SECTION 6: HELPER FUNCTIONS +-- Utility functions for common operations +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 6.1 Generate Issue ID +-- Format: ISSUE-YYYY-NNNN (sequential within year) +-- ----------------------------------------------------------------------------- +CREATE SEQUENCE issue_id_seq START 1; + +CREATE OR REPLACE FUNCTION generate_issue_id() +RETURNS VARCHAR(20) AS $$ +DECLARE + year_part VARCHAR(4); + seq_part INTEGER; +BEGIN + year_part := TO_CHAR(NOW(), 'YYYY'); + seq_part := NEXTVAL('issue_id_seq'); + RETURN 'ISSUE-' || year_part || '-' || LPAD(seq_part::TEXT, 4, '0'); +END; +$$ LANGUAGE plpgsql; + +COMMENT ON FUNCTION generate_issue_id IS + 'Generate sequential issue IDs in format ISSUE-YYYY-NNNN'; + +-- ----------------------------------------------------------------------------- +-- 6.2 Calculate Priority Score +-- Based on C1 framework: I_weight * (1 + log(span_count)) * decay * recurrence_boost +-- ----------------------------------------------------------------------------- +CREATE OR REPLACE FUNCTION calculate_priority_score( + p_max_intensity VARCHAR(2), + p_span_count INTEGER, + p_days_old NUMERIC, + p_recurrence_count INTEGER DEFAULT 0, + p_has_cr_w BOOLEAN DEFAULT FALSE +) RETURNS NUMERIC AS $$ +DECLARE + intensity_weight NUMERIC; + decay_factor NUMERIC; + recurrence_boost NUMERIC; + trend_modifier NUMERIC; +BEGIN + -- Intensity weights + intensity_weight := CASE p_max_intensity + WHEN 'I1' THEN 1.0 + WHEN 'I2' THEN 2.0 + WHEN 'I3' THEN 4.0 + ELSE 1.0 + END; + + -- Time decay: exp(-lambda * days), lambda = 0.023 (half-life ~30 days) + decay_factor := EXP(-0.023 * p_days_old); + + -- Recurrence boost: 1.0 + 0.5 * log2(recurrence_count + 1) + IF p_recurrence_count > 0 THEN + recurrence_boost := 1.0 + 0.5 * LOG(2, p_recurrence_count + 1); + ELSE + recurrence_boost := 1.0; + END IF; + + -- Trend modifier (CR-W = worsening = 1.3) + trend_modifier := CASE WHEN p_has_cr_w THEN 1.3 ELSE 1.0 END; + + RETURN ROUND( + intensity_weight * (1 + LOG(GREATEST(p_span_count, 1))) * + decay_factor * recurrence_boost * trend_modifier, + 2 + ); +END; +$$ LANGUAGE plpgsql IMMUTABLE; + +COMMENT ON FUNCTION calculate_priority_score IS + 'Calculate issue priority score per C1 time decay model'; + +-- ----------------------------------------------------------------------------- +-- 6.3 Calculate Confidence Score +-- Based on C1: base_confidence + specificity_bonus, weighted by evidence type +-- ----------------------------------------------------------------------------- +CREATE OR REPLACE FUNCTION calculate_confidence_score( + p_span_count INTEGER, + p_max_specificity VARCHAR(2), + p_avg_evidence_weight NUMERIC +) RETURNS NUMERIC AS $$ +DECLARE + base_confidence NUMERIC; + specificity_bonus NUMERIC; +BEGIN + -- Base confidence by span count + base_confidence := CASE + WHEN p_span_count = 1 THEN 0.50 + WHEN p_span_count = 2 THEN 0.70 + WHEN p_span_count = 3 THEN 0.80 + WHEN p_span_count BETWEEN 4 AND 5 THEN 0.85 + WHEN p_span_count BETWEEN 6 AND 10 THEN 0.90 + ELSE 0.95 + END; + + -- Specificity bonus + specificity_bonus := CASE p_max_specificity + WHEN 'S1' THEN 0.00 + WHEN 'S2' THEN 0.05 + WHEN 'S3' THEN 0.10 + ELSE 0.00 + END; + + RETURN ROUND( + LEAST(0.95, base_confidence + specificity_bonus) * COALESCE(p_avg_evidence_weight, 1.0), + 3 + ); +END; +$$ LANGUAGE plpgsql IMMUTABLE; + +COMMENT ON FUNCTION calculate_confidence_score IS + 'Calculate issue confidence score per C1 framework'; + +-- ============================================================================= +-- SECTION 7: TRIGGERS +-- Automated data maintenance +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 7.1 Auto-update timestamps +-- ----------------------------------------------------------------------------- +CREATE OR REPLACE FUNCTION update_updated_at() +RETURNS TRIGGER AS $$ +BEGIN + NEW.updated_at = NOW(); + RETURN NEW; +END; +$$ LANGUAGE plpgsql; + +CREATE TRIGGER tr_reviews_updated + BEFORE UPDATE ON reviews + FOR EACH ROW EXECUTE FUNCTION update_updated_at(); + +CREATE TRIGGER tr_spans_updated + BEFORE UPDATE ON spans + FOR EACH ROW EXECUTE FUNCTION update_updated_at(); + +CREATE TRIGGER tr_causal_chains_updated + BEFORE UPDATE ON causal_chains + FOR EACH ROW EXECUTE FUNCTION update_updated_at(); + +-- ----------------------------------------------------------------------------- +-- 7.2 Refresh materialized views (scheduled separately) +-- ----------------------------------------------------------------------------- +CREATE OR REPLACE FUNCTION refresh_urt_materialized_views() +RETURNS void AS $$ +BEGIN + REFRESH MATERIALIZED VIEW CONCURRENTLY mv_domain_summary; + REFRESH MATERIALIZED VIEW CONCURRENTLY mv_category_breakdown; + REFRESH MATERIALIZED VIEW mv_issue_pipeline; + REFRESH MATERIALIZED VIEW mv_cr_trends; + REFRESH MATERIALIZED VIEW mv_daily_volume; +END; +$$ LANGUAGE plpgsql; + +COMMENT ON FUNCTION refresh_urt_materialized_views IS + 'Refresh all URT materialized views - call periodically via pg_cron or similar'; + +-- ============================================================================= +-- SECTION 8: REFERENCE DATA INSERTS +-- Populate reference tables from B1-urt-codes.yaml +-- ============================================================================= + +-- ----------------------------------------------------------------------------- +-- 8.1 Insert Domains +-- ----------------------------------------------------------------------------- +INSERT INTO urt_domains (domain_code, name, description, core_question, default_owner, display_order) VALUES +('O', 'Offering', 'The core product, service, or outcome delivered', 'Does what we provide actually work and meet expectations?', 'Product / Operations', 1), +('P', 'People', 'Human interactions and personnel behavior', 'How do the people we interact with treat us and perform their roles?', 'HR / Training', 2), +('J', 'Journey', 'The process, timing, and operational flow', 'Is the experience smooth, timely, and friction-free?', 'Operations / Process', 3), +('E', 'Environment', 'Physical, digital, and ambient context', 'Is the space where the experience occurs functional, safe, and pleasant?', 'Facilities / IT', 4), +('A', 'Access', 'Availability, accessibility, and inclusivity', 'Can everyone who wants to participate do so fully and fairly?', 'Compliance / Design', 5), +('V', 'Value', 'Cost, pricing, and worth of the exchange', 'Is what I am giving up fair for what I am getting?', 'Finance / Pricing', 6), +('R', 'Relationship', 'Trust, reliability, and ongoing connection', 'Can I trust this business and do they value our relationship?', 'Leadership / CX', 7); + +-- ----------------------------------------------------------------------------- +-- 8.2 Insert Categories (28 total) +-- ----------------------------------------------------------------------------- +INSERT INTO urt_categories (category_code, domain_code, name, definition, display_order) VALUES +-- Offering +('O1', 'O', 'Function', 'Does it do what it is supposed to do?', 1), +('O2', 'O', 'Quality', 'How well is it made or executed?', 2), +('O3', 'O', 'Completeness', 'Is everything included that should be?', 3), +('O4', 'O', 'Fit', 'Does it match the customer specific needs?', 4), +-- People +('P1', 'P', 'Attitude', 'Disposition, manner, and emotional tone', 1), +('P2', 'P', 'Competence', 'Knowledge, skill, and professional capability', 2), +('P3', 'P', 'Responsiveness', 'Attentiveness, initiative, and follow-through', 3), +('P4', 'P', 'Communication', 'Quality of information exchange', 4), +-- Journey +('J1', 'J', 'Timing', 'Speed, punctuality, and time management', 1), +('J2', 'J', 'Ease', 'Effort required and friction encountered', 2), +('J3', 'J', 'Reliability', 'Consistency and predictability of process', 3), +('J4', 'J', 'Resolution', 'How problems are handled when they arise', 4), +-- Environment +('E1', 'E', 'Physical Space', 'Tangible environment attributes', 1), +('E2', 'E', 'Digital Space', 'Online and application interface', 2), +('E3', 'E', 'Ambiance', 'Intangible environmental qualities', 3), +('E4', 'E', 'Safety', 'Security and wellbeing factors', 4), +-- Access +('A1', 'A', 'Availability', 'Can you get it when you need it?', 1), +('A2', 'A', 'Accessibility', 'Can everyone use it regardless of ability?', 2), +('A3', 'A', 'Inclusivity', 'Does it work for diverse backgrounds?', 3), +('A4', 'A', 'Convenience', 'Is it easy to reach and engage with?', 4), +-- Value +('V1', 'V', 'Price', 'The monetary cost', 1), +('V2', 'V', 'Transparency', 'Clarity and honesty about costs', 2), +('V3', 'V', 'Effort', 'Non-monetary costs (time, hassle)', 3), +('V4', 'V', 'Worth', 'Overall value assessment', 4), +-- Relationship +('R1', 'R', 'Integrity', 'Honesty and ethical behavior', 1), +('R2', 'R', 'Dependability', 'Consistency over time', 2), +('R3', 'R', 'Recovery', 'Response to failures', 3), +('R4', 'R', 'Loyalty', 'Investment in ongoing relationship', 4); + +-- ----------------------------------------------------------------------------- +-- 8.3 Insert Causal Codes (16 total) +-- ----------------------------------------------------------------------------- +INSERT INTO urt_causal_codes (causal_code, layer, layer_prefix, name, definition, display_order) VALUES +-- Conditions layer (5 codes) +('CD-S', 'conditions', 'CD-', 'Staff State', 'Fatigue, training, motivation, experience', 1), +('CD-T', 'conditions', 'CD-', 'Team Dynamics', 'Handoffs, coordination, communication', 2), +('CD-E', 'conditions', 'CD-', 'Equipment', 'Malfunction, unavailable, outdated', 3), +('CD-F', 'conditions', 'CD-', 'Facility', 'Maintenance, capacity, hazards', 4), +('CD-O', 'conditions', 'CD-', 'Operational', 'Understaffing, demand surge, time pressure', 5), +-- Management layer (5 codes) +('MG-P', 'management', 'MG-', 'Planning', 'Staffing plans, scheduling, forecasting', 1), +('MG-T', 'management', 'MG-', 'Training', 'Preparation, development, competency', 2), +('MG-O', 'management', 'MG-', 'Oversight', 'Supervision, monitoring, correction', 3), +('MG-R', 'management', 'MG-', 'Resources', 'Maintenance, supplies, equipment', 4), +('MG-C', 'management', 'MG-', 'Communication', 'Policy relay, expectations, culture', 5), +-- Systemic layer (6 codes) +('SY-R', 'systemic', 'SY-', 'Resource Decisions', 'Budget, investment, staffing levels', 1), +('SY-P', 'systemic', 'SY-', 'Policy/Procedure', 'Rules, requirements, bureaucracy', 2), +('SY-C', 'systemic', 'SY-', 'Culture', 'Values, priorities, norms', 3), +('SY-S', 'systemic', 'SY-', 'Standards', 'Quality thresholds, metrics, expectations', 4), +('SY-H', 'systemic', 'SY-', 'Human Capital', 'Compensation, hiring, retention', 5), +('SY-X', 'systemic', 'SY-', 'External', 'Market, regulatory, competitive pressure', 6); + +-- ----------------------------------------------------------------------------- +-- 8.4 Insert Metadata Values (24 total across 7 dimensions) +-- ----------------------------------------------------------------------------- +INSERT INTO urt_metadata_values (dimension_code, value_code, dimension_name, label, definition, is_default, display_order) VALUES +-- Valence (4 values) +('V', 'V+', 'Valence', 'Positive', 'Praise, satisfaction', FALSE, 1), +('V', 'V-', 'Valence', 'Negative', 'Complaint, dissatisfaction', FALSE, 2), +('V', 'V0', 'Valence', 'Neutral', 'Observation without judgment', FALSE, 3), +('V', 'V±', 'Valence', 'Mixed', 'Both positive and negative in same span', FALSE, 4), +-- Intensity (3 values) +('I', 'I1', 'Intensity', 'Mild', 'Slight preference/concern', FALSE, 1), +('I', 'I2', 'Intensity', 'Moderate', 'Clear but not extreme', FALSE, 2), +('I', 'I3', 'Intensity', 'Strong', 'Emphatic or intense', FALSE, 3), +-- Specificity (3 values) +('S', 'S1', 'Specificity', 'Vague', 'General impression only', FALSE, 1), +('S', 'S2', 'Specificity', 'Moderate', 'Some details or context', FALSE, 2), +('S', 'S3', 'Specificity', 'Specific', 'Concrete details, names, times, amounts', FALSE, 3), +-- Actionability (3 values) +('A', 'A1', 'Actionability', 'Low', 'Feeling with no clear action path', FALSE, 1), +('A', 'A2', 'Actionability', 'Medium', 'Suggests improvement area', FALSE, 2), +('A', 'A3', 'Actionability', 'High', 'Specific implementable feedback', FALSE, 3), +-- Temporal (4 values) +('T', 'TC', 'Temporal Reference', 'Current', 'This specific visit/experience', TRUE, 1), +('T', 'TR', 'Temporal Reference', 'Recent', 'Recent pattern of experiences', FALSE, 2), +('T', 'TH', 'Temporal Reference', 'Historical', 'Long-standing pattern', FALSE, 3), +('T', 'TF', 'Temporal Reference', 'Future', 'Expectations or predictions', FALSE, 4), +-- Evidence (3 values) +('E', 'ES', 'Evidence Type', 'Stated', 'Explicitly said by customer', TRUE, 1), +('E', 'EI', 'Evidence Type', 'Inferred', 'Logically entailed by text', FALSE, 2), +('E', 'EC', 'Evidence Type', 'Contextual', 'Requires surrounding text', FALSE, 3), +-- Comparative Reference (4 values) +('CR', 'CR-N', 'Comparative Reference', 'None', 'No comparison to previous state', TRUE, 1), +('CR', 'CR-B', 'Comparative Reference', 'Better', 'Explicit improvement vs. before', FALSE, 2), +('CR', 'CR-W', 'Comparative Reference', 'Worse', 'Explicit decline vs. before', FALSE, 3), +('CR', 'CR-S', 'Comparative Reference', 'Same', 'Explicitly unchanged', FALSE, 4); + +-- ----------------------------------------------------------------------------- +-- 8.5 Insert Subcodes (sample - O domain) +-- Full 138 subcodes would be inserted similarly +-- ----------------------------------------------------------------------------- +INSERT INTO urt_subcodes (subcode, category_code, domain_code, name, definition, positive_example, negative_example, dont_confuse_with, dont_confuse_reason, display_order) VALUES +-- O1: Function +('O1.01', 'O1', 'O', 'Works/Doesn''t Work', 'Basic functionality success or failure', 'Software runs perfectly', 'Car won''t start', 'J3.03', 'J3.03 is system uptime, O1.01 is product function', 1), +('O1.02', 'O1', 'O', 'Performance Level', 'How well it operates', 'Incredibly fast processor', 'Sluggish and laggy', 'E2.03', 'E2.03 is interface speed, O1.02 is product performance', 2), +('O1.03', 'O1', 'O', 'Durability', 'Longevity and resistance to wear', 'Still perfect after 5 years', 'Fell apart in a month', 'O2.01', 'O2.01 is material quality, O1.03 is longevity', 3), +('O1.04', 'O1', 'O', 'Reliability', 'Consistency of function over time', 'Never fails me', 'Works sometimes, not others', 'J3.01', 'J3.01 is process consistency, O1.04 is product reliability', 4), +('O1.05', 'O1', 'O', 'Outcome Achievement', 'Did customer accomplish their goal?', 'Passed my exam!', 'Treatment didn''t work', 'V4.03', 'V4.03 is satisfaction with exchange, O1.05 is goal achievement', 5), +-- O2: Quality +('O2.01', 'O2', 'O', 'Materials/Inputs', 'Quality of components or ingredients', 'Real leather, premium feel', 'Cheap plastic parts', 'O1.03', 'O1.03 is durability, O2.01 is material quality', 1), +('O2.02', 'O2', 'O', 'Craftsmanship', 'Skill of construction or execution', 'Beautifully sewn seams', 'Sloppy assembly', 'P2.02', 'P2.02 is staff skill, O2.02 is product craftsmanship', 2), +('O2.03', 'O2', 'O', 'Presentation', 'Visual and aesthetic quality', 'Gorgeous plating', 'Looked thrown together', 'E3.05', 'E3.05 is space aesthetics, O2.03 is product presentation', 3), +('O2.04', 'O2', 'O', 'Attention to Detail', 'Finishing touches and refinement', 'Every corner perfect', 'Full of typos', 'O3.01', 'O3.01 is completeness, O2.04 is refinement', 4), +('O2.05', 'O2', 'O', 'Condition at Delivery', 'State when received', 'Still warm from oven', 'Arrived damaged', 'J3.02', 'J3.02 is process accuracy, O2.05 is delivery condition', 5), +-- O3: Completeness +('O3.01', 'O3', 'O', 'All Components Present', 'Nothing missing from what was promised', 'Everything in the box', 'Missing the charger', 'O4.01', 'O4.01 is spec match, O3.01 is completeness', 1), +('O3.02', 'O3', 'O', 'Feature Availability', 'Promised features actually work', 'All menu items available', 'Half the features disabled', 'A1.03', 'A1.03 is inventory, O3.02 is feature availability', 2), +('O3.03', 'O3', 'O', 'Scope Delivery', 'Full scope of work completed', 'Cleaned entire house', 'Left the bathrooms', 'J4.04', 'J4.04 is resolution quality, O3.03 is scope delivery', 3), +('O3.04', 'O3', 'O', 'Documentation', 'Supporting materials provided', 'Great user manual', 'No instructions at all', 'J2.01', 'J2.01 is process simplicity, O3.04 is documentation as product artifact', 4), +-- O4: Fit +('O4.01', 'O4', 'O', 'Specification Match', 'Matches what was ordered', 'Exactly what I ordered', 'Wrong size delivered', 'J3.02', 'J3.02 is execution accuracy, O4.01 is spec match', 1), +('O4.02', 'O4', 'O', 'Personalization', 'Adapted to individual preferences', 'Remembered my usual', 'No way to save prefs', 'P3.01', 'P3.01 is attentiveness, O4.02 is personalization', 2), +('O4.03', 'O4', 'O', 'Flexibility', 'Can be modified or adjusted', 'Happy to substitute', 'No modifications allowed', 'V2.04', 'V2.04 is policy fairness, O4.03 is flexibility', 3), +('O4.04', 'O4', 'O', 'Appropriateness', 'Right solution for the need', 'Perfect recommendation', 'Sold me wrong thing', 'P2.01', 'P2.01 is knowledge, O4.04 is appropriateness', 4); + +-- Note: Additional subcodes for P, J, E, A, V, R domains would be inserted similarly. +-- The full B1-urt-codes.yaml contains 138 subcodes total. +-- For production, generate INSERT statements from the YAML source. + +-- ============================================================================= +-- SECTION 9: PARTITIONING STRATEGY (for high-volume scenarios) +-- ============================================================================= +-- +-- For deployments expecting >1M spans/month, consider partitioning: +-- +-- 1. Spans table: Partition by created_at (monthly) +-- CREATE TABLE spans (...) PARTITION BY RANGE (created_at); +-- CREATE TABLE spans_2026_01 PARTITION OF spans +-- FOR VALUES FROM ('2026-01-01') TO ('2026-02-01'); +-- +-- 2. Reviews table: Same monthly partitioning +-- +-- 3. Annotation audit: Partition by annotated_at +-- +-- 4. Issue state history: Partition by transitioned_at +-- +-- Benefits: +-- - Faster queries on recent data (partition pruning) +-- - Easier data retention management (drop old partitions) +-- - Parallel query execution across partitions +-- +-- ============================================================================= + +-- ============================================================================= +-- SECTION 10: GRANTS AND SECURITY +-- ============================================================================= + +-- Create application roles +-- CREATE ROLE urt_reader; +-- CREATE ROLE urt_writer; +-- CREATE ROLE urt_admin; + +-- Reader permissions (dashboards, analytics) +-- GRANT SELECT ON ALL TABLES IN SCHEMA public TO urt_reader; +-- GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO urt_reader; + +-- Writer permissions (classification pipeline) +-- GRANT SELECT, INSERT, UPDATE ON reviews, spans, span_classifications, +-- causal_chains, issues, issue_spans, issue_state_history, +-- issue_resolutions, annotation_audit, classification_history TO urt_writer; +-- GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO urt_writer; + +-- Admin permissions (schema management) +-- GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO urt_admin; +-- GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO urt_admin; + +-- ============================================================================= +-- END OF SCHEMA +-- ============================================================================= +-- +-- Post-deployment checklist: +-- 1. Run: SELECT refresh_urt_materialized_views(); +-- 2. Set up pg_cron job for periodic MV refresh +-- 3. Configure connection pooling (PgBouncer recommended) +-- 4. Set up monitoring for table sizes and index usage +-- 5. Import full subcode data from B1-urt-codes.yaml +-- +-- ============================================================================= diff --git a/urt-taxonomy/track-b-engineering/B3-owner-routing.md b/urt-taxonomy/track-b-engineering/B3-owner-routing.md new file mode 100644 index 0000000..a7b16cc --- /dev/null +++ b/urt-taxonomy/track-b-engineering/B3-owner-routing.md @@ -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.* diff --git a/urt-taxonomy/track-b-engineering/B3-owner-routing.yaml b/urt-taxonomy/track-b-engineering/B3-owner-routing.yaml new file mode 100644 index 0000000..eae4449 --- /dev/null +++ b/urt-taxonomy/track-b-engineering/B3-owner-routing.yaml @@ -0,0 +1,692 @@ +# ============================================================================= +# B3: Owner Routing Matrix +# Universal Review Taxonomy v5.1 +# ============================================================================= +# +# Maps URT codes to responsible teams/individuals for ticket routing. +# Resolution order: subcode_overrides > category_overrides > domain_defaults +# +# Status: Production Ready +# Release Date: 2026-01-23 +# Prerequisite: B1-urt-codes.yaml (Code Registry) +# ============================================================================= + +version: "5.1" +status: "production" +release_date: "2026-01-23" + +# ============================================================================= +# ROUTING RULES +# ============================================================================= + +routing_rules: + + # --------------------------------------------------------------------------- + # DOMAIN DEFAULTS + # Baseline routing for each of the 7 experience domains + # --------------------------------------------------------------------------- + domain_defaults: + O: + team: "product" + escalation: "product_director" + description: "Core product/service delivery issues" + typical_response: "Product review, quality control audit" + + P: + team: "hr" + escalation: "hr_director" + description: "Personnel behavior and performance issues" + typical_response: "Staff coaching, training intervention" + + J: + team: "operations" + escalation: "operations_director" + description: "Process, timing, and operational flow issues" + typical_response: "Process improvement, workflow optimization" + + E: + team: "facilities" + escalation: "facilities_director" + description: "Physical and digital environment issues" + typical_response: "Maintenance dispatch, IT ticket" + + A: + team: "compliance" + escalation: "compliance_director" + description: "Availability, accessibility, and inclusivity issues" + typical_response: "Accessibility audit, policy review" + + V: + team: "finance" + escalation: "finance_director" + description: "Pricing, value, and cost-related issues" + typical_response: "Pricing review, refund authorization" + + R: + team: "leadership" + escalation: "ceo" + description: "Trust, relationship, and organizational integrity issues" + typical_response: "Executive review, strategic response" + + # --------------------------------------------------------------------------- + # CATEGORY-LEVEL OVERRIDES + # More specific routing for category-level patterns + # --------------------------------------------------------------------------- + category_overrides: + # Offering categories + O1: + team: "product_engineering" + escalation: "engineering_lead" + notes: "Function issues often require technical investigation" + O2: + team: "quality_control" + escalation: "qa_manager" + notes: "Quality issues route to QC team" + O3: + team: "fulfillment" + escalation: "fulfillment_manager" + notes: "Completeness issues often involve shipping/delivery" + O4: + team: "product" + escalation: "product_manager" + notes: "Fit issues inform product development" + + # People categories + P1: + team: "hr_training" + escalation: "hr_director" + notes: "Attitude issues require coaching/culture work" + P2: + team: "training" + escalation: "training_manager" + notes: "Competence issues indicate training gaps" + P3: + team: "operations" + escalation: "operations_manager" + notes: "Responsiveness often tied to operational capacity" + P4: + team: "training" + escalation: "training_manager" + notes: "Communication skills are trainable" + + # Journey categories + J1: + team: "operations" + escalation: "operations_manager" + notes: "Timing issues require process optimization" + J2: + team: "process_improvement" + escalation: "operations_director" + notes: "Ease/friction issues benefit from process redesign" + J3: + team: "operations" + escalation: "operations_manager" + notes: "Reliability issues need root cause analysis" + J4: + team: "customer_service" + escalation: "cx_director" + notes: "Resolution issues are CX team primary focus" + + # Environment categories + E1: + team: "facilities" + escalation: "facilities_manager" + notes: "Physical space issues" + E2: + team: "it" + escalation: "cto" + notes: "Digital space issues route to IT/Engineering" + E3: + team: "facilities" + escalation: "facilities_manager" + notes: "Ambiance is facility management concern" + E4: + team: "safety" + escalation: "safety_officer" + notes: "Safety issues require immediate attention" + + # Access categories + A1: + team: "operations" + escalation: "operations_director" + notes: "Availability is operational capacity" + A2: + team: "accessibility" + escalation: "compliance_director" + notes: "Accessibility requires specialized audit" + A3: + team: "dei" + escalation: "dei_director" + notes: "Inclusivity issues route to DEI team" + A4: + team: "operations" + escalation: "operations_manager" + notes: "Convenience is operational concern" + + # Value categories + V1: + team: "pricing" + escalation: "finance_director" + notes: "Price issues need pricing team review" + V2: + team: "legal" + escalation: "general_counsel" + notes: "Transparency issues may have legal implications" + V3: + team: "cx" + escalation: "cx_director" + notes: "Effort issues are customer experience concern" + V4: + team: "leadership" + escalation: "ceo" + notes: "Worth/satisfaction is strategic concern" + + # Relationship categories + R1: + team: "leadership" + escalation: "ceo" + notes: "Integrity issues are executive concern" + R2: + team: "operations" + escalation: "coo" + notes: "Dependability reflects operational excellence" + R3: + team: "cx" + escalation: "cx_director" + notes: "Recovery is core CX competency" + R4: + team: "marketing" + escalation: "cmo" + notes: "Loyalty is marketing/retention concern" + + # --------------------------------------------------------------------------- + # SUBCODE-LEVEL OVERRIDES + # Most specific routing for individual subcodes + # --------------------------------------------------------------------------- + subcode_overrides: + # Critical safety subcodes - always escalate + E4.01: + team: "safety" + escalation: "safety_officer" + auto_escalate: true + sla_override_hours: 1 + notes: "Physical safety is always critical" + E4.02: + team: "safety" + escalation: "safety_officer" + auto_escalate: true + sla_override_hours: 2 + notes: "Health/hygiene requires immediate attention" + E4.05: + team: "safety" + escalation: "safety_officer" + auto_escalate: true + sla_override_hours: 1 + notes: "Emergency readiness is critical" + + # Digital/IT specific subcodes + E2.01: + team: "ux_design" + escalation: "ux_lead" + notes: "Interface design issues route to UX" + E2.02: + team: "engineering" + escalation: "engineering_lead" + notes: "Digital functionality is engineering concern" + E2.03: + team: "devops" + escalation: "cto" + notes: "Performance issues may be infrastructure" + E2.04: + team: "ux_design" + escalation: "ux_lead" + notes: "Navigation is UX concern" + E2.05: + team: "mobile_engineering" + escalation: "mobile_lead" + notes: "Mobile experience routes to mobile team" + + # Discrimination - always escalate + A3.05: + team: "hr" + escalation: "hr_director" + auto_escalate: true + sla_override_hours: 4 + co_owner: "legal" + notes: "Equal treatment issues require HR and legal" + + # Accessibility compliance + A2.01: + team: "facilities" + escalation: "compliance_director" + co_owner: "accessibility" + notes: "Physical accessibility may require ADA compliance" + A2.02: + team: "accessibility" + escalation: "compliance_director" + notes: "Visual accessibility is WCAG concern" + A2.03: + team: "accessibility" + escalation: "compliance_director" + notes: "Hearing accessibility is compliance concern" + A2.04: + team: "ux_design" + escalation: "compliance_director" + notes: "Cognitive accessibility affects design" + A2.05: + team: "engineering" + escalation: "compliance_director" + notes: "Digital accessibility requires eng work" + + # Security breaches + E4.03: + team: "security" + escalation: "cso" + auto_escalate: true + sla_override_hours: 1 + notes: "Security incidents require immediate response" + + # Ethics/integrity - executive level + R1.04: + team: "leadership" + escalation: "ceo" + auto_escalate: true + sla_override_hours: 4 + co_owner: "legal" + notes: "Ethics issues are executive priority" + + # Billing/refund specific + V1.04: + team: "billing" + escalation: "finance_director" + notes: "Hidden costs need billing team review" + V2.02: + team: "billing" + escalation: "finance_director" + co_owner: "legal" + notes: "Fee disclosure may have compliance implications" + V2.04: + team: "legal" + escalation: "general_counsel" + notes: "Terms fairness is legal concern" + + # Staff-specific issues + P1.02: + team: "hr" + escalation: "hr_director" + notes: "Respect issues need HR intervention" + P2.04: + team: "hr" + escalation: "hr_director" + notes: "Professionalism is HR concern" + + # --------------------------------------------------------------------------- + # INTENSITY-BASED ESCALATION + # SLA and escalation rules by sentiment intensity + # --------------------------------------------------------------------------- + intensity_escalation: + I3: + auto_escalate: true + sla_hours: 4 + notification_level: "director" + priority: "critical" + description: "Strong negative - requires immediate attention" + I2: + auto_escalate: false + sla_hours: 24 + notification_level: "manager" + priority: "high" + description: "Moderate negative - standard priority" + I1: + auto_escalate: false + sla_hours: 72 + notification_level: "team" + priority: "normal" + description: "Mild negative - normal queue" + + # --------------------------------------------------------------------------- + # VALENCE-BASED ROUTING MODIFIERS + # Different handling for positive vs negative feedback + # --------------------------------------------------------------------------- + valence_routing: + "V+": + action: "acknowledge" + sla_hours: 48 + team_modifier: null + notes: "Positive feedback routes to recognition workflow" + "V-": + action: "resolve" + sla_hours: null # Uses intensity-based SLA + team_modifier: null + notes: "Negative feedback uses standard routing" + "V0": + action: "log" + sla_hours: null # No SLA for neutral + team_modifier: null + notes: "Neutral observations logged for analytics" + "V+-": + action: "resolve" + sla_hours: null + team_modifier: null + notes: "Mixed feedback prioritizes negative element" + + # --------------------------------------------------------------------------- + # CAUSAL CODE ROUTING + # Routes for root cause analysis codes + # --------------------------------------------------------------------------- + causal_routing: + # Conditions layer + "CD-S": + team: "hr" + escalation: "hr_director" + notes: "Staff state issues - HR/wellness concern" + "CD-T": + team: "operations" + escalation: "operations_manager" + notes: "Team dynamics - operational leadership" + "CD-E": + team: "facilities" + escalation: "facilities_manager" + notes: "Equipment issues - facilities/IT" + "CD-F": + team: "facilities" + escalation: "facilities_director" + notes: "Facility issues - maintenance" + "CD-O": + team: "operations" + escalation: "operations_director" + notes: "Operational conditions - ops leadership" + + # Management layer + "MG-P": + team: "operations" + escalation: "operations_director" + notes: "Planning failures - ops management" + "MG-T": + team: "training" + escalation: "hr_director" + notes: "Training gaps - L&D team" + "MG-O": + team: "operations" + escalation: "operations_director" + notes: "Oversight failures - management review" + "MG-R": + team: "procurement" + escalation: "finance_director" + notes: "Resource issues - procurement/finance" + "MG-C": + team: "leadership" + escalation: "coo" + notes: "Communication failures - leadership" + + # Systemic layer + "SY-R": + team: "leadership" + escalation: "cfo" + notes: "Resource decisions - executive finance" + "SY-P": + team: "leadership" + escalation: "coo" + notes: "Policy issues - executive operations" + "SY-C": + team: "leadership" + escalation: "ceo" + notes: "Culture issues - executive leadership" + "SY-S": + team: "leadership" + escalation: "coo" + notes: "Standards issues - executive ops" + "SY-H": + team: "hr" + escalation: "chro" + notes: "Human capital - HR leadership" + "SY-X": + team: "leadership" + escalation: "ceo" + notes: "External factors - executive strategy" + +# ============================================================================= +# SCHEDULING AND ON-CALL +# ============================================================================= + +scheduling: + business_hours: + start: "09:00" + end: "17:00" + timezone: "UTC" + days: ["monday", "tuesday", "wednesday", "thursday", "friday"] + + on_call_teams: + - team: "support" + coverage: "24/7" + handles: + - "I3" # Critical intensity + - "E4" # Safety issues + - "E4.03" # Security + - team: "operations" + coverage: "extended" + hours: "06:00-22:00" + handles: + - "J4" # Resolution issues + - "J1" # Timing issues + + holiday_coverage: + minimum_teams: ["support"] + escalation_delay_multiplier: 1.5 + +# ============================================================================= +# MULTI-CODE SPAN ROUTING +# ============================================================================= + +multi_code_rules: + # When a span has multiple codes, determine primary owner + priority_resolution: + method: "highest_priority_team" + tiebreaker: "primary_code_wins" + + # Domain priority order (for conflicts) + domain_priority: + 1: "E4" # Safety always first + 2: "R1" # Integrity/ethics + 3: "A3" # Discrimination/inclusivity + 4: "P" # People issues + 5: "V" # Value issues + 6: "J" # Journey issues + 7: "O" # Offering issues + 8: "E" # Environment (non-safety) + 9: "A" # Access (non-discrimination) + 10: "R" # Relationship (non-integrity) + + # Secondary code handling + secondary_code_behavior: + notify_co_owners: true + add_to_ticket_tags: true + require_sign_off: false + +# ============================================================================= +# CROSS-FUNCTIONAL ROUTING PATTERNS +# ============================================================================= + +cross_functional: + # Patterns that always involve multiple teams + patterns: + security_breach: + trigger_codes: ["E4.03", "R1.04"] + teams: ["security", "legal", "leadership"] + escalation: "ceo" + sla_hours: 1 + + discrimination_complaint: + trigger_codes: ["A3.05", "P1.02"] + teams: ["hr", "legal", "dei"] + escalation: "hr_director" + sla_hours: 4 + + billing_dispute: + trigger_codes: ["V1.04", "V2.02", "V2.04"] + teams: ["billing", "legal", "cx"] + escalation: "finance_director" + sla_hours: 24 + + product_failure: + trigger_codes: ["O1.01", "O1.04"] + conditions: + intensity: "I3" + teams: ["product_engineering", "qa", "cx"] + escalation: "product_director" + sla_hours: 4 + + systemic_issue: + trigger_codes: ["SY-C", "SY-P", "SY-R"] + teams: ["leadership", "operations"] + escalation: "ceo" + sla_hours: 24 + +# ============================================================================= +# TEAM DEFINITIONS +# ============================================================================= + +teams: + product: + name: "Product Team" + email: "product@example.com" + slack: "#product-team" + manager: "product_director" + + hr: + name: "Human Resources" + email: "hr@example.com" + slack: "#hr-team" + manager: "hr_director" + + operations: + name: "Operations" + email: "ops@example.com" + slack: "#operations" + manager: "operations_director" + + facilities: + name: "Facilities Management" + email: "facilities@example.com" + slack: "#facilities" + manager: "facilities_director" + + it: + name: "IT/Engineering" + email: "it@example.com" + slack: "#engineering" + manager: "cto" + + compliance: + name: "Compliance" + email: "compliance@example.com" + slack: "#compliance" + manager: "compliance_director" + + finance: + name: "Finance" + email: "finance@example.com" + slack: "#finance" + manager: "finance_director" + + leadership: + name: "Executive Leadership" + email: "leadership@example.com" + slack: "#leadership" + manager: "ceo" + + cx: + name: "Customer Experience" + email: "cx@example.com" + slack: "#customer-experience" + manager: "cx_director" + + safety: + name: "Safety & Security" + email: "safety@example.com" + slack: "#safety" + manager: "safety_officer" + + legal: + name: "Legal" + email: "legal@example.com" + slack: "#legal" + manager: "general_counsel" + + training: + name: "Learning & Development" + email: "training@example.com" + slack: "#training" + manager: "training_manager" + + accessibility: + name: "Accessibility" + email: "accessibility@example.com" + slack: "#accessibility" + manager: "accessibility_lead" + + dei: + name: "Diversity, Equity & Inclusion" + email: "dei@example.com" + slack: "#dei" + manager: "dei_director" + +# ============================================================================= +# ESCALATION HIERARCHY +# ============================================================================= + +escalation_hierarchy: + levels: + 1: "team_lead" + 2: "manager" + 3: "director" + 4: "vp" + 5: "c_suite" + + auto_escalation_rules: + sla_breach: + after_hours: 2 + escalate_to: "+1 level" + + repeated_issue: + threshold: 3 + window_days: 30 + escalate_to: "+1 level" + + vip_customer: + always_notify: "director" + sla_multiplier: 0.5 + +# ============================================================================= +# SLA DEFINITIONS +# ============================================================================= + +sla: + response_times: + critical: + initial_response_hours: 1 + resolution_hours: 4 + update_frequency_hours: 1 + high: + initial_response_hours: 4 + resolution_hours: 24 + update_frequency_hours: 4 + normal: + initial_response_hours: 24 + resolution_hours: 72 + update_frequency_hours: 24 + low: + initial_response_hours: 48 + resolution_hours: 168 # 1 week + update_frequency_hours: 48 + + breach_actions: + warning: + at_percent: 75 + action: "notify_manager" + critical: + at_percent: 100 + action: "escalate_and_notify_director" + overdue: + at_percent: 150 + action: "escalate_to_vp" diff --git a/urt-taxonomy/track-b-engineering/B4-api-contract.yaml b/urt-taxonomy/track-b-engineering/B4-api-contract.yaml new file mode 100644 index 0000000..d037355 --- /dev/null +++ b/urt-taxonomy/track-b-engineering/B4-api-contract.yaml @@ -0,0 +1,2895 @@ +# ============================================================================= +# B4: URT API Contract +# Universal Review Taxonomy v5.1 +# ============================================================================= +# +# Complete OpenAPI 3.0.3 specification for the URT classification and +# issue management API. +# +# Status: Production Ready +# Version: 1.0.0 +# Date: 2026-01-23 +# Depends On: B1-urt-codes.yaml, B2-database-schema.sql, B3-owner-routing.yaml +# ============================================================================= + +openapi: 3.0.3 +info: + title: Universal Review Taxonomy API + description: | + API for managing customer review classification using the Universal Review Taxonomy (URT) v5.1. + + ## Overview + + This API enables: + - **Review Management**: CRUD operations for customer reviews + - **Span Classification**: Classification of review text segments using URT codes + - **Issue Lifecycle**: Full issue tracking per the C1 framework + - **Code Registry**: Lookup and validation of URT taxonomy codes + - **Analytics**: Domain/category rollups and time-series metrics + - **Owner Routing**: Resolution of responsible teams per B3 routing matrix + + ## Implementation Profiles + + The API supports four implementation profiles with varying complexity: + - **URT-Lite**: 7 domains, minimal metadata + - **URT-Core**: 28 categories, basic metadata + - **URT-Standard**: 140 subcodes, full metadata + - **URT-Full**: 156 codes including causal analysis + + ## Rate Limiting + + All endpoints are rate limited. Check response headers for current limits: + - `X-RateLimit-Limit`: Requests allowed per window + - `X-RateLimit-Remaining`: Requests remaining in current window + - `X-RateLimit-Reset`: Unix timestamp when window resets + + version: 1.0.0 + contact: + name: URT API Support + email: api-support@example.com + url: https://docs.example.com/urt-api + license: + name: Proprietary + url: https://example.com/license + x-logo: + url: https://example.com/logo.png + +servers: + - url: https://api.example.com/urt/v1 + description: Production server + - url: https://api.staging.example.com/urt/v1 + description: Staging server + - url: http://localhost:8080/urt/v1 + description: Local development + +tags: + - name: Reviews + description: Customer review management + - name: Spans + description: Classified text segments + - name: Issues + description: Issue lifecycle management (C1 framework) + - name: Codes + description: URT code registry and validation + - name: Analytics + description: Aggregations and metrics + - name: Routing + description: Owner routing resolution + - name: Health + description: System health and status + +# ============================================================================= +# SECURITY SCHEMES +# ============================================================================= + +security: + - BearerAuth: [] + - ApiKeyAuth: [] + +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: | + JWT Bearer token authentication. Obtain tokens via OAuth 2.0 flow. + + Example: `Authorization: Bearer ` + + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + description: | + API key authentication for server-to-server communication. + + Example: `X-API-Key: your-api-key` + + # =========================================================================== + # SCHEMAS + # =========================================================================== + schemas: + + # ------------------------------------------------------------------------- + # Core Entity Schemas + # ------------------------------------------------------------------------- + + Review: + type: object + required: + - review_id + - source + - review_text + - created_at + properties: + review_id: + type: string + format: uuid + description: Unique review identifier + example: "550e8400-e29b-41d4-a716-446655440000" + external_id: + type: string + maxLength: 255 + description: ID from source system (e.g., Google place_id) + example: "ChIJN1t_tDeuEmsRUsoyG83frY4" + source: + type: string + maxLength: 50 + description: Review source platform + enum: [google, yelp, tripadvisor, facebook, trustpilot, custom] + example: "google" + business_id: + type: string + maxLength: 255 + description: Business identifier + example: "BUS-2026-0001" + author_name: + type: string + maxLength: 255 + description: Review author display name + example: "John D." + author_id: + type: string + maxLength: 255 + description: Author identifier from source + review_text: + type: string + description: Full review text content + example: "Great food but the service was slow. Would recommend the pasta." + star_rating: + type: number + format: float + minimum: 1.0 + maximum: 5.0 + description: Star rating (1.0-5.0) + example: 4.0 + review_date: + type: string + format: date + description: Date review was posted + example: "2026-01-15" + language_code: + type: string + maxLength: 5 + description: ISO 639-1 language code + example: "en" + raw_metadata: + type: object + additionalProperties: true + description: Source-specific metadata + span_count: + type: integer + minimum: 0 + description: Number of classified spans + readOnly: true + created_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + + ReviewCreate: + type: object + required: + - source + - review_text + properties: + external_id: + type: string + maxLength: 255 + source: + type: string + enum: [google, yelp, tripadvisor, facebook, trustpilot, custom] + business_id: + type: string + maxLength: 255 + author_name: + type: string + maxLength: 255 + author_id: + type: string + maxLength: 255 + review_text: + type: string + minLength: 1 + star_rating: + type: number + minimum: 1.0 + maximum: 5.0 + review_date: + type: string + format: date + language_code: + type: string + maxLength: 5 + raw_metadata: + type: object + + Span: + type: object + required: + - span_id + - review_id + - span_text + - profile + - primary_code + - valence + - intensity + properties: + span_id: + type: string + format: uuid + description: Unique span identifier + review_id: + type: string + format: uuid + description: Parent review ID + span_text: + type: string + description: Classified text segment + example: "the service was slow" + char_start: + type: integer + minimum: 0 + description: Start position in review text + char_end: + type: integer + minimum: 0 + description: End position in review text + span_order: + type: integer + minimum: 1 + description: Order within review + example: 2 + profile: + $ref: '#/components/schemas/ImplementationProfile' + primary_code: + type: string + description: Primary URT classification code + example: "J1.02" + primary_tier: + type: integer + enum: [1, 2, 3] + description: "Code tier: 1=domain, 2=category, 3=subcode" + secondary_codes: + type: array + maxItems: 2 + items: + type: string + description: Secondary URT codes (max 2) + example: ["A1.04"] + valence: + $ref: '#/components/schemas/Valence' + intensity: + $ref: '#/components/schemas/Intensity' + specificity: + $ref: '#/components/schemas/Specificity' + actionability: + $ref: '#/components/schemas/Actionability' + temporal: + $ref: '#/components/schemas/Temporal' + evidence: + $ref: '#/components/schemas/Evidence' + comparative: + $ref: '#/components/schemas/Comparative' + entity_reference: + type: string + maxLength: 255 + description: Referenced product, person, or feature + location_reference: + type: string + maxLength: 255 + description: Physical or logical location reference + causal_chain: + $ref: '#/components/schemas/CausalChain' + confidence_score: + type: number + format: float + minimum: 0.0 + maximum: 1.0 + description: Classification confidence (0.0-1.0) + example: 0.85 + annotator_notes: + type: string + description: Annotator comments + annotation_source: + type: string + enum: [human, llm, hybrid, rule] + description: Classification source + created_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + + SpanCreate: + type: object + required: + - review_id + - span_text + - primary_code + - valence + - intensity + properties: + review_id: + type: string + format: uuid + span_text: + type: string + minLength: 1 + char_start: + type: integer + minimum: 0 + char_end: + type: integer + minimum: 0 + span_order: + type: integer + minimum: 1 + default: 1 + profile: + $ref: '#/components/schemas/ImplementationProfile' + primary_code: + type: string + pattern: '^[OPJEAVR]([1-4](\.[0-9]{2})?)?$' + secondary_codes: + type: array + maxItems: 2 + items: + type: string + valence: + $ref: '#/components/schemas/Valence' + intensity: + $ref: '#/components/schemas/Intensity' + specificity: + $ref: '#/components/schemas/Specificity' + actionability: + $ref: '#/components/schemas/Actionability' + temporal: + $ref: '#/components/schemas/Temporal' + evidence: + $ref: '#/components/schemas/Evidence' + comparative: + $ref: '#/components/schemas/Comparative' + entity_reference: + type: string + maxLength: 255 + location_reference: + type: string + maxLength: 255 + causal_chain: + $ref: '#/components/schemas/CausalChainCreate' + confidence_score: + type: number + minimum: 0.0 + maximum: 1.0 + annotator_notes: + type: string + annotation_source: + type: string + enum: [human, llm, hybrid, rule] + + SpanClassification: + type: object + description: Individual code assignment within a span + properties: + classification_id: + type: string + format: uuid + span_id: + type: string + format: uuid + code: + type: string + example: "J1.02" + code_tier: + type: integer + enum: [1, 2, 3] + is_primary: + type: boolean + classification_order: + type: integer + minimum: 1 + maximum: 3 + + # ------------------------------------------------------------------------- + # Issue Schemas (C1 Lifecycle) + # ------------------------------------------------------------------------- + + Issue: + type: object + required: + - issue_id + - primary_subcode + - domain_code + - state + - span_count + - max_intensity + - priority_score + - confidence_score + properties: + issue_id: + type: string + pattern: '^ISSUE-[0-9]{4}-[0-9]{4}$' + description: Issue ID in format ISSUE-YYYY-NNNN + example: "ISSUE-2026-0042" + primary_subcode: + type: string + description: Primary URT subcode + example: "J1.02" + domain_code: + type: string + enum: [O, P, J, E, A, V, R] + description: Experience domain + entity_reference: + type: string + description: Aggregation entity + location_reference: + type: string + description: Aggregation location + state: + $ref: '#/components/schemas/IssueState' + state_changed_at: + type: string + format: date-time + span_count: + type: integer + minimum: 1 + description: Number of contributing spans + max_intensity: + $ref: '#/components/schemas/Intensity' + priority_score: + type: number + format: float + description: Calculated priority score + example: 8.75 + confidence_score: + type: number + format: float + minimum: 0.0 + maximum: 1.0 + description: Issue confidence score + example: 0.85 + owner_team: + type: string + description: Assigned team + example: "operations" + owner_individual: + type: string + description: Assigned individual + resolution_code: + type: string + description: Resolution code if resolved + resolution_notes: + type: string + decline_reason: + $ref: '#/components/schemas/DeclineReason' + causal_codes: + type: array + items: + type: string + description: Attributed causal codes + example: ["CD-O", "MG-P"] + reopen_count: + type: integer + minimum: 0 + description: Times issue was reopened + verification_window_days: + type: integer + enum: [30, 60, 90] + default: 60 + contributing_spans: + type: array + items: + $ref: '#/components/schemas/SpanSummary' + description: Spans contributing to this issue + created_at: + type: string + format: date-time + acknowledged_at: + type: string + format: date-time + work_started_at: + type: string + format: date-time + resolved_at: + type: string + format: date-time + verified_at: + type: string + format: date-time + declined_at: + type: string + format: date-time + + IssueCreate: + type: object + required: + - primary_subcode + - span_ids + properties: + primary_subcode: + type: string + pattern: '^[OPJEAVR][1-4]\.[0-9]{2}$' + entity_reference: + type: string + location_reference: + type: string + span_ids: + type: array + minItems: 1 + items: + type: string + format: uuid + description: Initial contributing span IDs + owner_team: + type: string + owner_individual: + type: string + verification_window_days: + type: integer + enum: [30, 60, 90] + default: 60 + + IssueState: + type: string + enum: + - DETECTED + - ACKNOWLEDGED + - IN_PROGRESS + - RESOLVED + - VERIFIED + - DECLINED + - REOPENED + - STALE + description: | + Issue lifecycle state per C1 framework: + - DETECTED: Initial detection from negative spans + - ACKNOWLEDGED: Team has acknowledged the issue + - IN_PROGRESS: Active work underway + - RESOLVED: Fix implemented, awaiting verification + - VERIFIED: Resolution confirmed via positive feedback + - DECLINED: Issue declined with reason code + - REOPENED: Issue recurred after resolution + - STALE: Issue aged out without resolution + + IssueTransition: + type: object + required: + - to_state + properties: + to_state: + $ref: '#/components/schemas/IssueState' + trigger_type: + type: string + enum: [manual, auto, span, sla] + default: manual + trigger_span_id: + type: string + format: uuid + description: Span that triggered transition (for span trigger) + notes: + type: string + description: Transition notes + resolution: + $ref: '#/components/schemas/IssueResolutionCreate' + + IssueResolution: + type: object + properties: + resolution_id: + type: string + format: uuid + issue_id: + type: string + resolution_code: + type: string + example: "FIX-2026-0015" + resolution_type: + type: string + enum: [fix, workaround, policy_change, training, process_improvement, equipment, other] + resolution_summary: + type: string + example: "Implemented queue management system to reduce wait times" + resolution_details: + type: string + prevention_notes: + type: string + process_changes: + type: string + verified_by_span_id: + type: string + format: uuid + verification_method: + type: string + enum: [cr_b, positive_span, time_based] + description: How resolution was verified + resolved_by: + type: string + resolved_at: + type: string + format: date-time + verified_at: + type: string + format: date-time + + IssueResolutionCreate: + type: object + required: + - resolution_type + - resolution_summary + properties: + resolution_type: + type: string + enum: [fix, workaround, policy_change, training, process_improvement, equipment, other] + resolution_summary: + type: string + minLength: 10 + resolution_details: + type: string + prevention_notes: + type: string + process_changes: + type: string + + DeclineReason: + type: string + enum: + - DEC-DUP + - DEC-OOS + - DEC-INS + - DEC-NAR + - DEC-EXT + - DEC-POL + - DEC-OLD + description: | + Issue decline reason codes: + - DEC-DUP: Duplicate of existing issue + - DEC-OOS: Out of scope + - DEC-INS: Insufficient information + - DEC-NAR: Not actionable/reproducible + - DEC-EXT: External factor (beyond control) + - DEC-POL: Policy decision (intentional) + - DEC-OLD: Stale/outdated feedback + + IssueStateHistory: + type: object + properties: + history_id: + type: string + format: uuid + issue_id: + type: string + from_state: + $ref: '#/components/schemas/IssueState' + to_state: + $ref: '#/components/schemas/IssueState' + trigger_type: + type: string + enum: [manual, auto, span, sla] + trigger_span_id: + type: string + format: uuid + actor_id: + type: string + actor_type: + type: string + enum: [user, system, rule] + notes: + type: string + transitioned_at: + type: string + format: date-time + + # ------------------------------------------------------------------------- + # URT Code Schemas + # ------------------------------------------------------------------------- + + URTDomain: + type: object + properties: + domain_code: + type: string + enum: [O, P, J, E, A, V, R] + name: + type: string + example: "Journey" + description: + type: string + core_question: + type: string + example: "Is the experience smooth, timely, and friction-free?" + default_owner: + type: string + example: "Operations / Process" + categories: + type: array + items: + $ref: '#/components/schemas/URTCategory' + + URTCategory: + type: object + properties: + category_code: + type: string + pattern: '^[OPJEAVR][1-4]$' + example: "J1" + domain_code: + type: string + name: + type: string + example: "Timing" + definition: + type: string + example: "Speed, punctuality, and time management" + subcodes: + type: array + items: + $ref: '#/components/schemas/URTSubcode' + + URTSubcode: + type: object + properties: + subcode: + type: string + pattern: '^[OPJEAVR][1-4]\.[0-9]{2}$' + example: "J1.02" + category_code: + type: string + domain_code: + type: string + name: + type: string + example: "Service Speed" + definition: + type: string + example: "Time for delivery/completion" + positive_example: + type: string + example: "Next day delivery" + negative_example: + type: string + example: "Took three weeks" + dont_confuse_with: + type: string + example: "J4.03" + dont_confuse_reason: + type: string + example: "J4.03 is resolution speed, J1.02 is service speed" + + URTCausalCode: + type: object + properties: + causal_code: + type: string + pattern: '^(CD|MG|SY)-[A-Z]$' + example: "CD-O" + layer: + type: string + enum: [conditions, management, systemic] + layer_prefix: + type: string + enum: ["CD-", "MG-", "SY-"] + name: + type: string + example: "Operational" + definition: + type: string + example: "Understaffing, demand surge, time pressure" + + CausalChain: + type: object + description: Root cause analysis chain (Full profile only) + properties: + chain_id: + type: string + format: uuid + span_id: + type: string + format: uuid + condition_code: + type: string + pattern: '^CD-[A-Z]$' + description: Conditions layer code + example: "CD-O" + management_code: + type: string + pattern: '^MG-[A-Z]$' + description: Management layer code + example: "MG-P" + systemic_code: + type: string + pattern: '^SY-[A-Z]$' + description: Systemic layer code + example: "SY-R" + chain_confidence: + type: number + format: float + minimum: 0.0 + maximum: 1.0 + analyst_notes: + type: string + + CausalChainCreate: + type: object + properties: + condition_code: + type: string + pattern: '^CD-[A-Z]$' + management_code: + type: string + pattern: '^MG-[A-Z]$' + systemic_code: + type: string + pattern: '^SY-[A-Z]$' + chain_confidence: + type: number + minimum: 0.0 + maximum: 1.0 + analyst_notes: + type: string + + CodeValidationRequest: + type: object + required: + - primary_code + properties: + primary_code: + type: string + secondary_codes: + type: array + items: + type: string + profile: + $ref: '#/components/schemas/ImplementationProfile' + causal_chain: + $ref: '#/components/schemas/CausalChainCreate' + + CodeValidationResult: + type: object + properties: + valid: + type: boolean + errors: + type: array + items: + type: object + properties: + code: + type: string + field: + type: string + message: + type: string + warnings: + type: array + items: + type: object + properties: + code: + type: string + field: + type: string + message: + type: string + normalized: + type: object + description: Normalized code values if valid + properties: + primary_code: + type: string + primary_tier: + type: integer + secondary_codes: + type: array + items: + type: string + + # ------------------------------------------------------------------------- + # Metadata Dimension Enums + # ------------------------------------------------------------------------- + + ImplementationProfile: + type: string + enum: [lite, core, standard, full] + default: standard + description: | + Implementation profile determining available fields: + - lite: 7 domains, valence only + - core: 28 categories, valence + intensity + - standard: 140 subcodes, all metadata + - full: 156 codes including causal analysis + + Valence: + type: string + enum: ["V+", "V-", "V0", "V+-"] + description: | + Sentiment direction: + - V+: Positive (praise, satisfaction) + - V-: Negative (complaint, dissatisfaction) + - V0: Neutral (observation) + - V+-: Mixed (both positive and negative) + example: "V-" + + Intensity: + type: string + enum: [I1, I2, I3] + description: | + Sentiment strength: + - I1: Mild + - I2: Moderate + - I3: Strong/emphatic + example: "I2" + + Specificity: + type: string + enum: [S1, S2, S3] + description: | + Level of detail: + - S1: Vague (general impression) + - S2: Moderate (some details) + - S3: Specific (concrete details) + + Actionability: + type: string + enum: [A1, A2, A3] + description: | + How actionable the feedback is: + - A1: Low (feeling only) + - A2: Medium (suggests area) + - A3: High (specific action) + + Temporal: + type: string + enum: [TC, TR, TH, TF] + default: TC + description: | + Time frame reference: + - TC: Current (this visit) + - TR: Recent (recent pattern) + - TH: Historical (long-standing) + - TF: Future (expectations) + + Evidence: + type: string + enum: [ES, EI, EC] + default: ES + description: | + Evidence type: + - ES: Stated (explicitly said) + - EI: Inferred (logically entailed) + - EC: Contextual (requires context) + + Comparative: + type: string + enum: [CR-N, CR-B, CR-W, CR-S] + default: CR-N + description: | + Comparison to previous state: + - CR-N: None (no comparison) + - CR-B: Better (improvement) + - CR-W: Worse (decline) + - CR-S: Same (unchanged) + + # ------------------------------------------------------------------------- + # Analytics Schemas + # ------------------------------------------------------------------------- + + DomainSummary: + type: object + properties: + domain_code: + type: string + domain_name: + type: string + default_owner: + type: string + total_spans: + type: integer + positive_spans: + type: integer + negative_spans: + type: integer + neutral_spans: + type: integer + mixed_spans: + type: integer + critical_spans: + type: integer + description: Spans with intensity I3 + avg_confidence: + type: number + format: float + open_issues: + type: integer + last_span_at: + type: string + format: date-time + + CategoryBreakdown: + type: object + properties: + category_code: + type: string + category_name: + type: string + domain_code: + type: string + domain_name: + type: string + total_spans: + type: integer + negative_count: + type: integer + positive_count: + type: integer + negative_pct: + type: number + format: float + total_issues: + type: integer + resolved_verified: + type: integer + avg_intensity: + type: number + format: float + + TrendDataPoint: + type: object + properties: + period_start: + type: string + format: date + period_end: + type: string + format: date + domain_code: + type: string + category_code: + type: string + valence: + type: string + span_count: + type: integer + review_count: + type: integer + avg_intensity: + type: number + format: float + cr_better_count: + type: integer + cr_worse_count: + type: integer + cr_same_count: + type: integer + + AnalyticsSummaryResponse: + type: object + properties: + generated_at: + type: string + format: date-time + period: + type: object + properties: + start: + type: string + format: date + end: + type: string + format: date + domains: + type: array + items: + $ref: '#/components/schemas/DomainSummary' + categories: + type: array + items: + $ref: '#/components/schemas/CategoryBreakdown' + totals: + type: object + properties: + total_reviews: + type: integer + total_spans: + type: integer + total_issues: + type: integer + open_issues: + type: integer + avg_resolution_hours: + type: number + format: float + + TrendsResponse: + type: object + properties: + generated_at: + type: string + format: date-time + granularity: + type: string + enum: [day, week, month] + data: + type: array + items: + $ref: '#/components/schemas/TrendDataPoint' + + # ------------------------------------------------------------------------- + # Routing Schemas + # ------------------------------------------------------------------------- + + RoutingRequest: + type: object + required: + - primary_code + - valence + - intensity + properties: + primary_code: + type: string + secondary_codes: + type: array + items: + type: string + valence: + $ref: '#/components/schemas/Valence' + intensity: + $ref: '#/components/schemas/Intensity' + causal_codes: + type: array + items: + type: string + + RoutingResponse: + type: object + properties: + primary_owner: + type: object + properties: + team: + type: string + example: "operations" + escalation: + type: string + example: "operations_director" + co_owners: + type: array + items: + type: object + properties: + team: + type: string + reason: + type: string + sla: + type: object + properties: + priority: + type: string + enum: [critical, high, normal, low] + initial_response_hours: + type: integer + resolution_hours: + type: integer + update_frequency_hours: + type: integer + auto_escalate: + type: boolean + notifications: + type: array + items: + type: object + properties: + channel: + type: string + enum: [email, slack] + target: + type: string + + # ------------------------------------------------------------------------- + # Classification Request/Response + # ------------------------------------------------------------------------- + + ClassifyReviewRequest: + type: object + required: + - profile + properties: + profile: + $ref: '#/components/schemas/ImplementationProfile' + options: + type: object + properties: + split_spans: + type: boolean + default: true + description: Automatically split review into spans + include_causal: + type: boolean + default: false + description: Include causal analysis (Full profile) + confidence_threshold: + type: number + minimum: 0.0 + maximum: 1.0 + default: 0.7 + description: Minimum confidence for auto-classification + + ClassifyReviewResponse: + type: object + properties: + review_id: + type: string + format: uuid + status: + type: string + enum: [completed, partial, pending_review] + spans: + type: array + items: + $ref: '#/components/schemas/Span' + issues_created: + type: array + items: + type: string + description: IDs of any issues created + processing_time_ms: + type: integer + + BatchClassifyRequest: + type: object + required: + - spans + properties: + profile: + $ref: '#/components/schemas/ImplementationProfile' + spans: + type: array + minItems: 1 + maxItems: 100 + items: + $ref: '#/components/schemas/SpanCreate' + + BatchClassifyResponse: + type: object + properties: + total: + type: integer + successful: + type: integer + failed: + type: integer + results: + type: array + items: + type: object + properties: + index: + type: integer + span: + $ref: '#/components/schemas/Span' + error: + $ref: '#/components/schemas/Error' + + # ------------------------------------------------------------------------- + # Common Schemas + # ------------------------------------------------------------------------- + + SpanSummary: + type: object + properties: + span_id: + type: string + format: uuid + span_text: + type: string + primary_code: + type: string + valence: + type: string + intensity: + type: string + created_at: + type: string + format: date-time + + Pagination: + type: object + properties: + cursor: + type: string + description: Cursor for next page + has_more: + type: boolean + total: + type: integer + description: Total count (when available) + limit: + type: integer + + PaginatedResponse: + type: object + properties: + data: + type: array + items: {} + pagination: + $ref: '#/components/schemas/Pagination' + + # ------------------------------------------------------------------------- + # Error Schemas + # ------------------------------------------------------------------------- + + Error: + type: object + required: + - code + - message + properties: + code: + type: string + description: Machine-readable error code + message: + type: string + description: Human-readable error message + details: + type: object + additionalProperties: true + description: Additional error context + request_id: + type: string + description: Request ID for debugging + + ErrorResponse: + type: object + required: + - error + properties: + error: + $ref: '#/components/schemas/Error' + + ValidationError: + type: object + properties: + code: + type: string + example: "VALIDATION_ERROR" + message: + type: string + example: "Request validation failed" + field_errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + code: + type: string + + HealthStatus: + type: object + properties: + status: + type: string + enum: [healthy, degraded, unhealthy] + version: + type: string + example: "1.0.0" + timestamp: + type: string + format: date-time + components: + type: object + properties: + database: + type: object + properties: + status: + type: string + latency_ms: + type: integer + cache: + type: object + properties: + status: + type: string + latency_ms: + type: integer + classifier: + type: object + properties: + status: + type: string + model_version: + type: string + + # =========================================================================== + # RESPONSE HEADERS + # =========================================================================== + headers: + X-RateLimit-Limit: + description: Maximum requests allowed per window + schema: + type: integer + example: 1000 + X-RateLimit-Remaining: + description: Requests remaining in current window + schema: + type: integer + example: 998 + X-RateLimit-Reset: + description: Unix timestamp when rate limit resets + schema: + type: integer + example: 1706054400 + X-Request-Id: + description: Unique request identifier for debugging + schema: + type: string + format: uuid + + # =========================================================================== + # COMMON PARAMETERS + # =========================================================================== + parameters: + ReviewId: + name: review_id + in: path + required: true + schema: + type: string + format: uuid + description: Review UUID + SpanId: + name: span_id + in: path + required: true + schema: + type: string + format: uuid + description: Span UUID + IssueId: + name: issue_id + in: path + required: true + schema: + type: string + pattern: '^ISSUE-[0-9]{4}-[0-9]{4}$' + description: Issue ID (format ISSUE-YYYY-NNNN) + Cursor: + name: cursor + in: query + schema: + type: string + description: Pagination cursor + Limit: + name: limit + in: query + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + description: Results per page + DomainFilter: + name: domain + in: query + schema: + type: string + enum: [O, P, J, E, A, V, R] + description: Filter by domain code + ValenceFilter: + name: valence + in: query + schema: + type: string + enum: ["V+", "V-", "V0", "V+-"] + description: Filter by valence + IntensityFilter: + name: intensity + in: query + schema: + type: string + enum: [I1, I2, I3] + description: Filter by intensity + DateFrom: + name: from + in: query + schema: + type: string + format: date + description: Start date (inclusive) + DateTo: + name: to + in: query + schema: + type: string + format: date + description: End date (inclusive) + + # =========================================================================== + # COMMON RESPONSES + # =========================================================================== + responses: + BadRequest: + description: Bad request - validation error + content: + application/json: + schema: + $ref: '#/components/schemas/ValidationError' + example: + code: "VALIDATION_ERROR" + message: "Request validation failed" + field_errors: + - field: "primary_code" + message: "Invalid URT code format" + code: "INVALID_CODE_FORMAT" + Unauthorized: + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: "UNAUTHORIZED" + message: "Authentication required" + Forbidden: + description: Insufficient permissions + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: "FORBIDDEN" + message: "Insufficient permissions for this operation" + NotFound: + description: Resource not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: "NOT_FOUND" + message: "Resource not found" + Conflict: + description: Conflict - invalid state transition + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: "INVALID_TRANSITION" + message: "Cannot transition from VERIFIED to IN_PROGRESS" + RateLimited: + description: Rate limit exceeded + headers: + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Reset: + $ref: '#/components/headers/X-RateLimit-Reset' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: "RATE_LIMITED" + message: "Rate limit exceeded. Retry after reset." + InternalError: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: "INTERNAL_ERROR" + message: "An unexpected error occurred" + request_id: "req_abc123" + +# ============================================================================= +# PATHS +# ============================================================================= + +paths: + + # --------------------------------------------------------------------------- + # REVIEWS + # --------------------------------------------------------------------------- + + /reviews: + get: + tags: [Reviews] + summary: List reviews + description: Retrieve paginated list of reviews with optional filters + operationId: listReviews + parameters: + - $ref: '#/components/parameters/Cursor' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/DateFrom' + - $ref: '#/components/parameters/DateTo' + - name: source + in: query + schema: + type: string + description: Filter by source platform + - name: business_id + in: query + schema: + type: string + description: Filter by business ID + - name: has_spans + in: query + schema: + type: boolean + description: Filter by classification status + responses: + '200': + description: List of reviews + headers: + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Reset: + $ref: '#/components/headers/X-RateLimit-Reset' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Review' + pagination: + $ref: '#/components/schemas/Pagination' + example: + data: + - review_id: "550e8400-e29b-41d4-a716-446655440000" + source: "google" + review_text: "Great food but slow service" + star_rating: 3.5 + review_date: "2026-01-15" + span_count: 2 + pagination: + cursor: "eyJpZCI6MTAwfQ" + has_more: true + limit: 20 + '401': + $ref: '#/components/responses/Unauthorized' + '429': + $ref: '#/components/responses/RateLimited' + + post: + tags: [Reviews] + summary: Create review + description: Create a new review record + operationId: createReview + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReviewCreate' + example: + source: "google" + business_id: "BUS-2026-0001" + author_name: "Jane D." + review_text: "Excellent service, very professional staff. The wait time could be improved." + star_rating: 4.0 + review_date: "2026-01-20" + language_code: "en" + responses: + '201': + description: Review created + content: + application/json: + schema: + $ref: '#/components/schemas/Review' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '429': + $ref: '#/components/responses/RateLimited' + + /reviews/{review_id}: + get: + tags: [Reviews] + summary: Get review + description: Retrieve a single review by ID + operationId: getReview + parameters: + - $ref: '#/components/parameters/ReviewId' + - name: include_spans + in: query + schema: + type: boolean + default: true + description: Include classified spans + responses: + '200': + description: Review details + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Review' + - type: object + properties: + spans: + type: array + items: + $ref: '#/components/schemas/Span' + '404': + $ref: '#/components/responses/NotFound' + + patch: + tags: [Reviews] + summary: Update review + description: Update review metadata + operationId: updateReview + parameters: + - $ref: '#/components/parameters/ReviewId' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + business_id: + type: string + star_rating: + type: number + review_date: + type: string + format: date + language_code: + type: string + raw_metadata: + type: object + responses: + '200': + description: Review updated + content: + application/json: + schema: + $ref: '#/components/schemas/Review' + '404': + $ref: '#/components/responses/NotFound' + + delete: + tags: [Reviews] + summary: Delete review + description: Soft delete a review and its spans + operationId: deleteReview + parameters: + - $ref: '#/components/parameters/ReviewId' + responses: + '204': + description: Review deleted + '404': + $ref: '#/components/responses/NotFound' + + /reviews/{review_id}/classify: + post: + tags: [Reviews] + summary: Classify review + description: | + Submit a review for automatic classification. The review will be split into + spans and classified according to the specified profile. + operationId: classifyReview + parameters: + - $ref: '#/components/parameters/ReviewId' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ClassifyReviewRequest' + example: + profile: "standard" + options: + split_spans: true + include_causal: false + confidence_threshold: 0.7 + responses: + '200': + description: Classification complete + content: + application/json: + schema: + $ref: '#/components/schemas/ClassifyReviewResponse' + example: + review_id: "550e8400-e29b-41d4-a716-446655440000" + status: "completed" + spans: + - span_id: "660e8400-e29b-41d4-a716-446655440001" + span_text: "Great food" + primary_code: "O2.01" + valence: "V+" + intensity: "I2" + - span_id: "660e8400-e29b-41d4-a716-446655440002" + span_text: "slow service" + primary_code: "J1.02" + valence: "V-" + intensity: "I2" + issues_created: [] + processing_time_ms: 342 + '404': + $ref: '#/components/responses/NotFound' + + # --------------------------------------------------------------------------- + # SPANS + # --------------------------------------------------------------------------- + + /spans: + get: + tags: [Spans] + summary: List spans + description: Retrieve paginated list of classified spans + operationId: listSpans + parameters: + - $ref: '#/components/parameters/Cursor' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/DomainFilter' + - $ref: '#/components/parameters/ValenceFilter' + - $ref: '#/components/parameters/IntensityFilter' + - $ref: '#/components/parameters/DateFrom' + - $ref: '#/components/parameters/DateTo' + - name: review_id + in: query + schema: + type: string + format: uuid + description: Filter by review ID + - name: primary_code + in: query + schema: + type: string + description: Filter by primary code (exact or prefix) + - name: comparative + in: query + schema: + type: string + enum: [CR-N, CR-B, CR-W, CR-S] + description: Filter by comparative reference + responses: + '200': + description: List of spans + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Span' + pagination: + $ref: '#/components/schemas/Pagination' + + post: + tags: [Spans] + summary: Create span + description: Create a new classified span + operationId: createSpan + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SpanCreate' + example: + review_id: "550e8400-e29b-41d4-a716-446655440000" + span_text: "the service was slow" + char_start: 15 + char_end: 35 + span_order: 2 + profile: "standard" + primary_code: "J1.02" + secondary_codes: ["A1.04"] + valence: "V-" + intensity: "I2" + specificity: "S2" + actionability: "A2" + temporal: "TC" + evidence: "ES" + comparative: "CR-N" + confidence_score: 0.85 + annotation_source: "llm" + responses: + '201': + description: Span created + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '400': + $ref: '#/components/responses/BadRequest' + + /spans/{span_id}: + get: + tags: [Spans] + summary: Get span + description: Retrieve a single span by ID + operationId: getSpan + parameters: + - $ref: '#/components/parameters/SpanId' + responses: + '200': + description: Span details + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '404': + $ref: '#/components/responses/NotFound' + + patch: + tags: [Spans] + summary: Update span + description: Update span classification + operationId: updateSpan + parameters: + - $ref: '#/components/parameters/SpanId' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + primary_code: + type: string + secondary_codes: + type: array + items: + type: string + valence: + $ref: '#/components/schemas/Valence' + intensity: + $ref: '#/components/schemas/Intensity' + specificity: + $ref: '#/components/schemas/Specificity' + actionability: + $ref: '#/components/schemas/Actionability' + temporal: + $ref: '#/components/schemas/Temporal' + evidence: + $ref: '#/components/schemas/Evidence' + comparative: + $ref: '#/components/schemas/Comparative' + annotator_notes: + type: string + responses: + '200': + description: Span updated + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '404': + $ref: '#/components/responses/NotFound' + + delete: + tags: [Spans] + summary: Delete span + description: Soft delete a span + operationId: deleteSpan + parameters: + - $ref: '#/components/parameters/SpanId' + responses: + '204': + description: Span deleted + '404': + $ref: '#/components/responses/NotFound' + + /spans/batch: + post: + tags: [Spans] + summary: Batch create spans + description: Create multiple spans in a single request (max 100) + operationId: batchCreateSpans + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BatchClassifyRequest' + responses: + '200': + description: Batch results + content: + application/json: + schema: + $ref: '#/components/schemas/BatchClassifyResponse' + example: + total: 5 + successful: 4 + failed: 1 + results: + - index: 0 + span: + span_id: "770e8400-e29b-41d4-a716-446655440001" + primary_code: "J1.02" + - index: 1 + error: + code: "INVALID_CODE" + message: "Invalid primary_code: X9.99" + '400': + $ref: '#/components/responses/BadRequest' + + # --------------------------------------------------------------------------- + # ISSUES + # --------------------------------------------------------------------------- + + /issues: + get: + tags: [Issues] + summary: List issues + description: Retrieve paginated list of issues + operationId: listIssues + parameters: + - $ref: '#/components/parameters/Cursor' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/DomainFilter' + - $ref: '#/components/parameters/DateFrom' + - $ref: '#/components/parameters/DateTo' + - name: state + in: query + schema: + type: array + items: + $ref: '#/components/schemas/IssueState' + style: form + explode: true + description: Filter by state(s) + - name: owner_team + in: query + schema: + type: string + description: Filter by owner team + - name: priority_min + in: query + schema: + type: number + description: Minimum priority score + - name: sort + in: query + schema: + type: string + enum: [priority_desc, created_desc, created_asc] + default: priority_desc + description: Sort order + responses: + '200': + description: List of issues + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Issue' + pagination: + $ref: '#/components/schemas/Pagination' + + post: + tags: [Issues] + summary: Create issue + description: Manually create an issue from spans + operationId: createIssue + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/IssueCreate' + example: + primary_subcode: "J1.02" + entity_reference: "Downtown location" + span_ids: + - "660e8400-e29b-41d4-a716-446655440001" + - "660e8400-e29b-41d4-a716-446655440002" + owner_team: "operations" + responses: + '201': + description: Issue created + content: + application/json: + schema: + $ref: '#/components/schemas/Issue' + '400': + $ref: '#/components/responses/BadRequest' + + /issues/{issue_id}: + get: + tags: [Issues] + summary: Get issue + description: Retrieve issue details including history + operationId: getIssue + parameters: + - $ref: '#/components/parameters/IssueId' + - name: include_history + in: query + schema: + type: boolean + default: false + description: Include state transition history + - name: include_spans + in: query + schema: + type: boolean + default: true + description: Include contributing spans + responses: + '200': + description: Issue details + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Issue' + - type: object + properties: + state_history: + type: array + items: + $ref: '#/components/schemas/IssueStateHistory' + resolution: + $ref: '#/components/schemas/IssueResolution' + '404': + $ref: '#/components/responses/NotFound' + + patch: + tags: [Issues] + summary: Update issue + description: Update issue metadata (not state - use transition endpoint) + operationId: updateIssue + parameters: + - $ref: '#/components/parameters/IssueId' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + owner_team: + type: string + owner_individual: + type: string + entity_reference: + type: string + location_reference: + type: string + causal_codes: + type: array + items: + type: string + verification_window_days: + type: integer + enum: [30, 60, 90] + responses: + '200': + description: Issue updated + content: + application/json: + schema: + $ref: '#/components/schemas/Issue' + '404': + $ref: '#/components/responses/NotFound' + + /issues/{issue_id}/transition: + post: + tags: [Issues] + summary: Transition issue state + description: | + Transition issue to a new state according to the C1 lifecycle state machine. + + Valid transitions: + - DETECTED -> ACKNOWLEDGED, DECLINED + - ACKNOWLEDGED -> IN_PROGRESS, DECLINED + - IN_PROGRESS -> RESOLVED, DECLINED + - RESOLVED -> VERIFIED, REOPENED + - DECLINED -> (terminal) + - VERIFIED -> REOPENED + - REOPENED -> IN_PROGRESS, DECLINED + - STALE -> ACKNOWLEDGED, DECLINED + operationId: transitionIssue + parameters: + - $ref: '#/components/parameters/IssueId' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/IssueTransition' + examples: + acknowledge: + summary: Acknowledge issue + value: + to_state: "ACKNOWLEDGED" + notes: "Assigned to operations team for investigation" + resolve: + summary: Resolve with details + value: + to_state: "RESOLVED" + notes: "Implemented queue management system" + resolution: + resolution_type: "process_improvement" + resolution_summary: "Added digital queue display and SMS notifications" + decline: + summary: Decline issue + value: + to_state: "DECLINED" + notes: "External factor - weather related" + responses: + '200': + description: Transition successful + content: + application/json: + schema: + $ref: '#/components/schemas/Issue' + '404': + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + + /issues/{issue_id}/spans: + get: + tags: [Issues] + summary: Get issue spans + description: List all spans contributing to an issue + operationId: getIssueSpans + parameters: + - $ref: '#/components/parameters/IssueId' + responses: + '200': + description: Contributing spans + content: + application/json: + schema: + type: object + properties: + issue_id: + type: string + spans: + type: array + items: + $ref: '#/components/schemas/Span' + + post: + tags: [Issues] + summary: Link span to issue + description: Add a span as a contributor to an existing issue + operationId: linkSpanToIssue + parameters: + - $ref: '#/components/parameters/IssueId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - span_id + properties: + span_id: + type: string + format: uuid + link_type: + type: string + enum: [contributor, verification, reopen_trigger] + default: contributor + responses: + '200': + description: Span linked + content: + application/json: + schema: + $ref: '#/components/schemas/Issue' + '404': + $ref: '#/components/responses/NotFound' + + # --------------------------------------------------------------------------- + # CODES + # --------------------------------------------------------------------------- + + /codes: + get: + tags: [Codes] + summary: List all codes + description: Retrieve the full URT code registry + operationId: listCodes + parameters: + - name: tier + in: query + schema: + type: integer + enum: [1, 2, 3] + description: Filter by tier (1=domain, 2=category, 3=subcode) + - name: domain + in: query + schema: + type: string + enum: [O, P, J, E, A, V, R] + description: Filter by domain + - name: include_causal + in: query + schema: + type: boolean + default: false + description: Include causal codes + responses: + '200': + description: Code registry + content: + application/json: + schema: + type: object + properties: + version: + type: string + example: "5.1" + domains: + type: array + items: + $ref: '#/components/schemas/URTDomain' + causal_codes: + type: array + items: + $ref: '#/components/schemas/URTCausalCode' + + /codes/domains: + get: + tags: [Codes] + summary: List domains + description: Retrieve all 7 experience domains + operationId: listDomains + responses: + '200': + description: Domain list + content: + application/json: + schema: + type: object + properties: + domains: + type: array + items: + $ref: '#/components/schemas/URTDomain' + + /codes/domains/{domain_code}: + get: + tags: [Codes] + summary: Get domain + description: Retrieve domain with its categories and subcodes + operationId: getDomain + parameters: + - name: domain_code + in: path + required: true + schema: + type: string + enum: [O, P, J, E, A, V, R] + responses: + '200': + description: Domain details + content: + application/json: + schema: + $ref: '#/components/schemas/URTDomain' + '404': + $ref: '#/components/responses/NotFound' + + /codes/categories/{category_code}: + get: + tags: [Codes] + summary: Get category + description: Retrieve category with its subcodes + operationId: getCategory + parameters: + - name: category_code + in: path + required: true + schema: + type: string + pattern: '^[OPJEAVR][1-4]$' + responses: + '200': + description: Category details + content: + application/json: + schema: + $ref: '#/components/schemas/URTCategory' + '404': + $ref: '#/components/responses/NotFound' + + /codes/subcodes/{subcode}: + get: + tags: [Codes] + summary: Get subcode + description: Retrieve subcode details with disambiguation guidance + operationId: getSubcode + parameters: + - name: subcode + in: path + required: true + schema: + type: string + pattern: '^[OPJEAVR][1-4]\.[0-9]{2}$' + responses: + '200': + description: Subcode details + content: + application/json: + schema: + $ref: '#/components/schemas/URTSubcode' + '404': + $ref: '#/components/responses/NotFound' + + /codes/causal: + get: + tags: [Codes] + summary: List causal codes + description: Retrieve all 16 causal codes across 3 layers + operationId: listCausalCodes + parameters: + - name: layer + in: query + schema: + type: string + enum: [conditions, management, systemic] + description: Filter by layer + responses: + '200': + description: Causal code list + content: + application/json: + schema: + type: object + properties: + causal_codes: + type: array + items: + $ref: '#/components/schemas/URTCausalCode' + + /codes/validate: + post: + tags: [Codes] + summary: Validate code combination + description: | + Validate that a code combination is valid for the specified profile. + Returns normalized codes and any warnings. + operationId: validateCodes + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CodeValidationRequest' + example: + primary_code: "J1.02" + secondary_codes: ["A1.04"] + profile: "standard" + responses: + '200': + description: Validation result + content: + application/json: + schema: + $ref: '#/components/schemas/CodeValidationResult' + examples: + valid: + summary: Valid combination + value: + valid: true + errors: [] + warnings: [] + normalized: + primary_code: "J1.02" + primary_tier: 3 + secondary_codes: ["A1.04"] + invalid: + summary: Invalid code + value: + valid: false + errors: + - code: "INVALID_CODE" + field: "primary_code" + message: "Code X9.99 does not exist" + warnings: [] + + # --------------------------------------------------------------------------- + # ANALYTICS + # --------------------------------------------------------------------------- + + /analytics/summary: + get: + tags: [Analytics] + summary: Get analytics summary + description: Retrieve aggregated metrics by domain and category + operationId: getAnalyticsSummary + parameters: + - $ref: '#/components/parameters/DateFrom' + - $ref: '#/components/parameters/DateTo' + - name: business_id + in: query + schema: + type: string + description: Filter by business + responses: + '200': + description: Analytics summary + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyticsSummaryResponse' + example: + generated_at: "2026-01-23T10:30:00Z" + period: + start: "2026-01-01" + end: "2026-01-23" + domains: + - domain_code: "J" + domain_name: "Journey" + total_spans: 145 + negative_spans: 98 + positive_spans: 42 + open_issues: 12 + totals: + total_reviews: 523 + total_spans: 847 + total_issues: 45 + open_issues: 28 + avg_resolution_hours: 36.5 + + /analytics/trends: + get: + tags: [Analytics] + summary: Get trend data + description: Retrieve time-series metrics for trend analysis + operationId: getAnalyticsTrends + parameters: + - $ref: '#/components/parameters/DateFrom' + - $ref: '#/components/parameters/DateTo' + - $ref: '#/components/parameters/DomainFilter' + - name: granularity + in: query + schema: + type: string + enum: [day, week, month] + default: week + description: Time period granularity + - name: metrics + in: query + schema: + type: array + items: + type: string + enum: [span_count, issue_count, avg_intensity, cr_signals] + style: form + explode: true + description: Metrics to include + responses: + '200': + description: Trend data + content: + application/json: + schema: + $ref: '#/components/schemas/TrendsResponse' + + # --------------------------------------------------------------------------- + # ROUTING + # --------------------------------------------------------------------------- + + /routing/resolve: + post: + tags: [Routing] + summary: Resolve owner routing + description: | + Determine the responsible team and SLA for a classification based on + the B3 owner routing matrix. + operationId: resolveRouting + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RoutingRequest' + example: + primary_code: "E4.01" + secondary_codes: [] + valence: "V-" + intensity: "I3" + responses: + '200': + description: Routing resolution + content: + application/json: + schema: + $ref: '#/components/schemas/RoutingResponse' + example: + primary_owner: + team: "safety" + escalation: "safety_officer" + co_owners: [] + sla: + priority: "critical" + initial_response_hours: 1 + resolution_hours: 4 + update_frequency_hours: 1 + auto_escalate: true + notifications: + - channel: "slack" + target: "#safety" + - channel: "email" + target: "safety@example.com" + + # --------------------------------------------------------------------------- + # HEALTH + # --------------------------------------------------------------------------- + + /health: + get: + tags: [Health] + summary: Health check + description: Check API and component health status + operationId: healthCheck + security: [] + responses: + '200': + description: System healthy + content: + application/json: + schema: + $ref: '#/components/schemas/HealthStatus' + example: + status: "healthy" + version: "1.0.0" + timestamp: "2026-01-23T10:30:00Z" + components: + database: + status: "healthy" + latency_ms: 5 + cache: + status: "healthy" + latency_ms: 1 + classifier: + status: "healthy" + model_version: "urt-classifier-v5.1" + '503': + description: System unhealthy + content: + application/json: + schema: + $ref: '#/components/schemas/HealthStatus' + example: + status: "unhealthy" + version: "1.0.0" + timestamp: "2026-01-23T10:30:00Z" + components: + database: + status: "unhealthy" + latency_ms: null + cache: + status: "healthy" + latency_ms: 1 + +# ============================================================================= +# WEBHOOKS +# ============================================================================= + +webhooks: + issueStateChanged: + post: + summary: Issue state changed + description: | + Triggered when an issue transitions to a new state. + + Subscribe via the webhook configuration endpoint (not shown). + operationId: onIssueStateChanged + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + event_type: + type: string + enum: [issue.state_changed] + event_id: + type: string + format: uuid + timestamp: + type: string + format: date-time + data: + type: object + properties: + issue_id: + type: string + from_state: + $ref: '#/components/schemas/IssueState' + to_state: + $ref: '#/components/schemas/IssueState' + trigger_type: + type: string + actor_id: + type: string + issue: + $ref: '#/components/schemas/Issue' + example: + event_type: "issue.state_changed" + event_id: "evt_abc123" + timestamp: "2026-01-23T10:30:00Z" + data: + issue_id: "ISSUE-2026-0042" + from_state: "IN_PROGRESS" + to_state: "RESOLVED" + trigger_type: "manual" + actor_id: "user_123" + issue: + issue_id: "ISSUE-2026-0042" + state: "RESOLVED" + primary_subcode: "J1.02" + responses: + '200': + description: Webhook received + + issueCreated: + post: + summary: Issue created + description: Triggered when a new issue is detected or created + operationId: onIssueCreated + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + event_type: + type: string + enum: [issue.created] + event_id: + type: string + format: uuid + timestamp: + type: string + format: date-time + data: + type: object + properties: + issue: + $ref: '#/components/schemas/Issue' + contributing_spans: + type: array + items: + $ref: '#/components/schemas/SpanSummary' + responses: + '200': + description: Webhook received + + spanClassified: + post: + summary: Span classified + description: Triggered when a new span is classified with negative valence + operationId: onSpanClassified + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + event_type: + type: string + enum: [span.classified] + event_id: + type: string + format: uuid + timestamp: + type: string + format: date-time + data: + type: object + properties: + span: + $ref: '#/components/schemas/Span' + review: + $ref: '#/components/schemas/Review' + routing: + $ref: '#/components/schemas/RoutingResponse' + responses: + '200': + description: Webhook received + + slaBreach: + post: + summary: SLA breach warning + description: Triggered when an issue approaches or exceeds SLA thresholds + operationId: onSlaBreach + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + event_type: + type: string + enum: [sla.warning, sla.breach, sla.critical] + event_id: + type: string + format: uuid + timestamp: + type: string + format: date-time + data: + type: object + properties: + issue_id: + type: string + issue: + $ref: '#/components/schemas/Issue' + sla_type: + type: string + enum: [initial_response, resolution, update] + threshold_percent: + type: integer + hours_elapsed: + type: number + hours_allowed: + type: number + responses: + '200': + description: Webhook received + +# ============================================================================= +# END OF SPECIFICATION +# ============================================================================= diff --git a/urt-taxonomy/track-c-analytics/C1-Issue-Lifecycle-Framework.md b/urt-taxonomy/track-c-analytics/C1-Issue-Lifecycle-Framework.md new file mode 100644 index 0000000..4ba0510 --- /dev/null +++ b/urt-taxonomy/track-c-analytics/C1-Issue-Lifecycle-Framework.md @@ -0,0 +1,1204 @@ +# C1: Issue Lifecycle Framework + +## Universal Review Taxonomy (URT) v5.1 - Analytics Track + +**Document**: C1 - Issue Lifecycle Framework +**Version**: 1.0 +**Status**: Production Ready +**Date**: 2026-01-23 +**Depends On**: URT Specification v5.1 + +--- + +## Purpose + +This framework defines how classified feedback spans (per URT v5.1) become trackable issues that move through resolution states. It bridges the gap between span-level classification and operational issue management, enabling businesses to: + +- Track issue detection through resolution +- Aggregate related spans into actionable issues +- Prioritize based on severity, recurrence, and age +- Verify resolution through subsequent feedback +- Measure operational performance with SLAs + +--- + +## 1. Issue State Machine + +### 1.1 State Definitions + +| State | Code | Definition | Entry Trigger | +|-------|------|------------|---------------| +| **DETECTED** | `DET` | New issue identified from V- span(s) | Span classified with negative valence | +| **ACKNOWLEDGED** | `ACK` | Business has seen and accepted the issue | Manual acknowledgment or auto-ack rule | +| **IN_PROGRESS** | `INP` | Resolution work has started | Work assignment or status update | +| **RESOLVED** | `RES` | Fix deployed or corrective action taken | Resolution logged with action code | +| **VERIFIED** | `VER` | Subsequent feedback confirms resolution | CR-B span or V+ span on same subcode | +| **DECLINED** | `DEC` | Closed without action (with reason) | Decline action with reason code | +| **REOPENED** | `REO` | Previously resolved issue recurred | CR-S or CR-W span after RESOLVED | + +### 1.2 State Transition Diagram + +``` + ┌─────────────────────────────────────────────────────────┐ + │ │ + │ DECLINE REASONS │ + │ ┌────────────────────────────────────┐ │ + ▼ │ │ │ +┌──────────┐ ack ┌──────────┐ │ ┌──────────┐ │ │ +│ │─────────▶│ │──────┴─────▶│ │ │ │ +│ DETECTED │ │ACKNOWLEDGED│ decline │ DECLINED │ │ │ +│ (DET) │ │ (ACK) │ │ (DEC) │ │ │ +│ │◀─────────│ │ │ │ │ │ +└──────────┘ reopen └──────────┘ └──────────┘ │ │ + │ │ │ │ + │ │ start_work │ │ + │ ▼ │ │ + │ ┌──────────┐ resolve ┌──────────┐ verify ┌──────────┐ │ + │ │ │───────────────▶│ │───────────▶│ │ │ + │ │IN_PROGRESS│ │ RESOLVED │ │ VERIFIED │ │ + │ │ (INP) │ │ (RES) │ │ (VER) │ │ + │ │ │◀───────────────│ │◀───────────│ │ │ + │ └──────────┘ reopen └──────────┘ reopen └──────────┘ │ + │ │ │ │ │ + │ │ │ │ │ + │ │ escalate │ │ │ + │ └──────────────────────────┼───────────────────────┘ │ + │ │ │ + │ │ expire (no verification) │ + │ ▼ │ + │ ┌──────────┐ │ + └───────────────────────────────────────▶│ STALE │◀────────────────────────────┘ + escalate │ (STL) │ (optional state) + └──────────┘ +``` + +### 1.3 Valid Transitions + +| From State | To State | Trigger | Conditions | +|------------|----------|---------|------------| +| `DET` | `ACK` | `ack` | Manual or auto-acknowledgment | +| `DET` | `DEC` | `decline` | With reason code (see 1.4) | +| `DET` | `STL` | `expire` | No action within SLA window | +| `ACK` | `INP` | `start_work` | Assignment to owner/team | +| `ACK` | `DEC` | `decline` | With reason code | +| `ACK` | `REO` | `reopen` | From merged/duplicate issue | +| `INP` | `RES` | `resolve` | Resolution action logged | +| `INP` | `ACK` | `pause` | Work paused, not abandoned | +| `INP` | `DEC` | `decline` | Late decline with reason | +| `RES` | `VER` | `verify` | CR-B or positive confirmation span | +| `RES` | `REO` | `reopen` | CR-S or CR-W on resolved issue | +| `RES` | `STL` | `expire` | Verification window elapsed | +| `VER` | `REO` | `reopen` | New complaint after verification | +| `DEC` | `REO` | `reopen` | New evidence or escalation | + +### 1.4 Decline Reason Codes + +| Code | Reason | Use Case | +|------|--------|----------| +| `DEC-DUP` | Duplicate | Merged with existing issue | +| `DEC-OOS` | Out of Scope | Not actionable by business | +| `DEC-INS` | Insufficient Info | Cannot act without more detail | +| `DEC-NAR` | Not As Reported | Investigation found no issue | +| `DEC-EXT` | External Factor | Outside business control | +| `DEC-POL` | Policy Decision | Intentional business choice | +| `DEC-OLD` | Too Old | Beyond remediation window | + +--- + +## 2. Issue Aggregation Rules + +### 2.1 Span-to-Issue Mapping + +Individual spans become issues through aggregation. A single issue may encompass multiple spans from multiple reviews when they describe the same underlying problem. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ISSUE AGGREGATION PIPELINE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Review A ──▶ Span 1 (O2.05, V-, I2) ──┐ │ +│ │ │ +│ Review B ──▶ Span 2 (O2.05, V-, I2) ──┼──▶ ISSUE-001: Food Temp Problem │ +│ │ Subcode: O2.05 │ +│ Review C ──▶ Span 3 (O2.05, V-, I3) ──┘ Location: Main Kitchen │ +│ Span Count: 3 │ +│ Max Intensity: I3 │ +│ Review D ──▶ Span 4 (P1.02, V-, I3) ──────▶ ISSUE-002: Staff Respect │ +│ Subcode: P1.02 │ +│ Staff: John D. │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### 2.2 Aggregation Criteria + +Two spans aggregate into the same issue when ALL of the following match: + +| Criterion | Match Rule | Example | +|-----------|------------|---------| +| **Subcode** | Same Tier 3 code | O2.05 = O2.05 | +| **Location** | Same physical/logical location | "Kitchen", "App checkout" | +| **Entity** | Same product/person/feature | "iPhone 15", "Server John" | +| **Time Window** | Within aggregation window | See 2.3 | +| **Valence** | Same polarity (V- with V-) | Both negative | + +**Note**: Location and Entity are extracted during classification as optional span attributes in extended schemas. + +### 2.3 Intensity-Based Aggregation Thresholds + +Different intensity levels trigger issue creation at different thresholds: + +| Intensity | Immediate Issue | Aggregation Threshold | Time Window | +|-----------|-----------------|----------------------|-------------| +| **I3** (Strong) | Yes | 1 span | N/A - Immediate | +| **I2** (Moderate) | No | 3+ spans | 30 days | +| **I1** (Mild) | No | 5+ spans | 30 days | + +**Decision Logic**: + +``` +IF span.intensity == I3: + CREATE_ISSUE(span) + +ELIF span.intensity == I2: + matching_spans = FIND_MATCHING(span, window=30d) + IF COUNT(matching_spans) >= 2: # This span + 2 others = 3 + CREATE_OR_UPDATE_ISSUE(matching_spans + span) + +ELIF span.intensity == I1: + matching_spans = FIND_MATCHING(span, window=30d) + IF COUNT(matching_spans) >= 4: # This span + 4 others = 5 + CREATE_OR_UPDATE_ISSUE(matching_spans + span) +``` + +### 2.4 Cross-Review Correlation + +Spans from different reviews correlate based on semantic similarity and entity matching: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CORRELATION MATRIX │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Span A: "The burger was cold" O2.05, V-, I2 │ +│ Span B: "Food arrived cold again" O2.05, V-, I2, CR-S │ +│ Span C: "Temperature of dishes is bad" O2.05, V-, I2 │ +│ │ +│ Correlation Signals: │ +│ ├── Same subcode: O2.05 (100% match) │ +│ ├── Lexical overlap: "cold", "temperature" (high similarity) │ +│ ├── Entity: Food/dishes (same category) │ +│ └── CR signal: Span B has CR-S (recurrence indicator) │ +│ │ +│ Result: HIGH CORRELATION → Aggregate into single issue │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**Correlation Score Calculation**: + +``` +correlation = ( + 0.40 * subcode_match + # Binary: 1.0 if same, 0.0 if different + 0.25 * entity_similarity + # 0.0-1.0 based on extracted entities + 0.20 * lexical_similarity + # 0.0-1.0 cosine similarity of text + 0.15 * temporal_proximity # 1.0 if same day, decays over window +) + +IF correlation >= 0.70: + AGGREGATE() +``` + +--- + +## 3. Time Decay Model + +### 3.1 Urgency Decay Formula + +Issue urgency decays over time but is refreshed by recurrence. The model balances immediate severity against persistent but lower-intensity patterns. + +**Base Formula**: + +``` +Urgency(t) = I_base * weight(I) * decay(t) * recurrence_boost(CR) +``` + +Where: +- `I_base` = Initial intensity value (1, 2, or 3) +- `weight(I)` = Intensity weight multiplier +- `decay(t)` = Time decay function +- `recurrence_boost(CR)` = Boost for recurring issues + +### 3.2 Component Definitions + +**Intensity Weights**: + +| Intensity | Weight | Rationale | +|-----------|--------|-----------| +| I1 | 1.0 | Baseline | +| I2 | 2.0 | Clear signal | +| I3 | 4.0 | Critical urgency | + +**Time Decay Function**: + +``` +decay(days) = exp(-lambda * days) + +Where lambda = 0.023 (half-life of ~30 days) +``` + +| Days | Decay Factor | Effective Urgency (I3) | +|------|--------------|------------------------| +| 0 | 1.000 | 4.00 | +| 7 | 0.851 | 3.40 | +| 14 | 0.724 | 2.90 | +| 30 | 0.500 | 2.00 | +| 60 | 0.250 | 1.00 | +| 90 | 0.125 | 0.50 | + +**Recurrence Boost**: + +``` +recurrence_boost(CR, count) = + IF CR == CR-S or CR == CR-W: + 1.0 + 0.5 * log2(recurrence_count + 1) + ELSE: + 1.0 +``` + +| Recurrence Count | Boost Factor | +|------------------|--------------| +| 1 | 1.00 | +| 2 | 1.50 | +| 3 | 1.79 | +| 4 | 2.00 | +| 5 | 2.16 | +| 10 | 2.66 | + +### 3.3 Priority Score Calculation + +The final priority score combines all factors: + +``` +P = I_weight * (1 + log(span_count)) * decay(days) * recurrence_boost * trend_modifier + +Where: +- I_weight = max intensity weight among aggregated spans +- span_count = number of spans in issue +- days = days since first detection +- trend_modifier = sentiment trend adjustment (see below) +``` + +**Trend Modifier** (based on recent sentiment trajectory): + +| Trend | Modifier | Detection | +|-------|----------|-----------| +| Worsening | 1.3 | Multiple CR-W in last 14 days | +| Stable | 1.0 | No CR signals or mixed | +| Improving | 0.7 | Multiple CR-B in last 14 days | + +### 3.4 Priority Score Examples + +**Example 1: Fresh Critical Issue** +``` +I3 issue, 1 span, 0 days old, no recurrence +P = 4.0 * (1 + log(1)) * 1.0 * 1.0 * 1.0 +P = 4.0 * 1.0 * 1.0 * 1.0 * 1.0 +P = 4.00 +``` + +**Example 2: Persistent Moderate Issue** +``` +I2 issue, 5 spans, 15 days old, CR-S markers (3 recurrences), worsening +P = 2.0 * (1 + log(5)) * 0.707 * 1.79 * 1.3 +P = 2.0 * 1.70 * 0.707 * 1.79 * 1.3 +P = 5.60 +``` + +**Example 3: Old Low-Priority Issue** +``` +I1 issue, 2 spans, 45 days old, no recurrence +P = 1.0 * (1 + log(2)) * 0.354 * 1.0 * 1.0 +P = 1.0 * 1.30 * 0.354 * 1.0 * 1.0 +P = 0.46 +``` + +--- + +## 4. Confidence Scoring + +### 4.1 Single vs. Multiple Span Confidence + +Issue confidence increases with corroborating evidence from independent sources. + +**Base Confidence by Span Count**: + +| Span Count | Base Confidence | Rationale | +|------------|-----------------|-----------| +| 1 | 0.50 | Single report, could be outlier | +| 2 | 0.70 | Corroborated once | +| 3 | 0.80 | Pattern emerging | +| 4-5 | 0.85 | Clear pattern | +| 6-10 | 0.90 | Strong pattern | +| 11+ | 0.95 | Systemic issue | + +### 4.2 Evidence Type Weighting + +Different evidence types (from URT metadata) contribute differently to confidence: + +| Evidence Type | Weight | Rationale | +|---------------|--------|-----------| +| **ES** (Stated) | 1.0 | Direct, explicit statement | +| **EI** (Inferred) | 0.7 | Logically entailed but not explicit | +| **EC** (Contextual) | 0.5 | Depends on surrounding context | + +### 4.3 Specificity Bonus + +More specific feedback provides higher confidence: + +| Specificity | Bonus | Example | +|-------------|-------|---------| +| **S1** (Vague) | +0.00 | "Service was bad" | +| **S2** (Moderate) | +0.05 | "Service was slow at dinner" | +| **S3** (Specific) | +0.10 | "Waiter John took 40 mins for appetizers" | + +### 4.4 Aggregate Confidence Calculation + +``` +confidence = min(0.95, base_confidence + specificity_bonus) * evidence_weight + +Where: +- base_confidence = from span count table +- specificity_bonus = max(specificity bonuses across spans) +- evidence_weight = weighted average of span evidence types +``` + +**Calculation Example**: + +``` +Issue with 4 spans: +- Span 1: ES, S3 → weight 1.0, bonus 0.10 +- Span 2: ES, S2 → weight 1.0, bonus 0.05 +- Span 3: EI, S2 → weight 0.7, bonus 0.05 +- Span 4: ES, S1 → weight 1.0, bonus 0.00 + +base_confidence = 0.85 (4 spans) +specificity_bonus = 0.10 (max across spans) +evidence_weight = (1.0 + 1.0 + 0.7 + 1.0) / 4 = 0.925 + +confidence = min(0.95, 0.85 + 0.10) * 0.925 +confidence = 0.95 * 0.925 +confidence = 0.879 +``` + +### 4.5 Confidence Thresholds for Action + +| Confidence | Classification | Recommended Action | +|------------|----------------|-------------------| +| < 0.50 | Low | Monitor only | +| 0.50-0.69 | Moderate | Investigate | +| 0.70-0.84 | High | Schedule action | +| 0.85-0.94 | Very High | Prioritize action | +| >= 0.95 | Confirmed | Immediate action | + +--- + +## 5. Resolution Verification + +### 5.1 CR-B as Resolution Confirmation + +The Comparative Reference (CR) dimension from URT v5.1 provides explicit signals for resolution verification: + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ RESOLUTION VERIFICATION FLOW │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ISSUE-001: O2.05 (Food Temperature) │ +│ Status: RESOLVED (2026-01-15) │ +│ │ +│ ─────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 0 (Resolved): "We've added warming stations" │ +│ │ +│ Day 7: Review X - "Food was hot and fresh!" │ +│ Span: O2.05, V+, CR-N │ +│ → Positive but no explicit comparison │ +│ → Status: RESOLVED (monitoring) │ +│ │ +│ Day 14: Review Y - "Much better temperature than last time!" │ +│ Span: O2.05, V+, CR-B │ +│ → Explicit improvement signal (CR-B) │ +│ → Status: VERIFIED │ +│ │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### 5.2 Verification Criteria + +An issue transitions from RESOLVED to VERIFIED when: + +| Criterion | Requirement | Strength | +|-----------|-------------|----------| +| **CR-B span** | Same subcode with CR-B marker | Strong (auto-verify) | +| **Positive span** | Same subcode with V+ | Moderate (needs 2+) | +| **Absence of negative** | No V- spans in window | Weak (time-based) | + +**Verification Strength Weights**: + +``` +verification_score = + (CR_B_count * 1.0) + # Each CR-B = full verification point + (positive_count * 0.5) + # Each V+ = half point + (absence_bonus * 0.3) # No negatives in window = 0.3 + +IF verification_score >= 1.0: + VERIFY() +``` + +### 5.3 Verification Time Windows + +Different window models balance verification speed against confidence: + +| Model | Window | Use Case | Auto-Close | +|-------|--------|----------|------------| +| **Fast** | 30 days | High-volume, quick feedback loops | Yes | +| **Standard** | 60 days | Typical businesses | Yes | +| **Extended** | 90 days | Low-volume, B2B, seasonal | Yes | +| **Manual** | Indefinite | Complex issues, no auto-close | No | + +**Window Selection Logic**: + +``` +IF issue.domain IN [O, J]: + window = 30 # Product/process issues get quick feedback +ELIF issue.domain IN [P, E]: + window = 60 # People/environment need more observations +ELIF issue.domain IN [R, V]: + window = 90 # Relationship/value issues take time to verify +ELSE: + window = 60 # Default +``` + +### 5.4 False Resolution Detection + +A resolved issue is falsely resolved when negative feedback continues: + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ FALSE RESOLUTION DETECTION │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ISSUE-002: J1.01 (Wait Times) │ +│ Status: RESOLVED (2026-01-10) │ +│ │ +│ ─────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 0: Marked RESOLVED - "Added more staff" │ +│ │ +│ Day 5: Review Z - "Still waiting forever, nothing changed" │ +│ Span: J1.01, V-, CR-S │ +│ → Explicit "unchanged" signal (CR-S) │ +│ → FALSE RESOLUTION DETECTED │ +│ → Status: REOPENED │ +│ │ +│ OR │ +│ │ +│ Day 12: Review W - "Wait times are even worse now" │ +│ Span: J1.01, V-, CR-W │ +│ → Explicit "worse" signal (CR-W) │ +│ → FALSE RESOLUTION + REGRESSION │ +│ → Status: REOPENED (escalated) │ +│ │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### 5.5 Auto-Reopen Triggers + +| Trigger | Condition | Action | +|---------|-----------|--------| +| **CR-S after RESOLVED** | Any CR-S span on resolved issue | Reopen | +| **CR-W after RESOLVED** | Any CR-W span on resolved issue | Reopen + Escalate | +| **V- after VERIFIED** | V- span on verified issue | Reopen | +| **Recurrence threshold** | 2+ V- spans after RESOLVED | Reopen | + +**Escalation on Reopen**: + +``` +IF reopen_count >= 2: + escalate_to_management() + +IF reopen_reason == CR-W: + escalate_immediately() + flag_as_regression() +``` + +--- + +## 6. Metrics and SLAs + +### 6.1 Time-to-Acknowledge (TTA) Targets + +TTA measures time from DETECTED to ACKNOWLEDGED. + +| Intensity | Target TTA | Max TTA | Escalation | +|-----------|------------|---------|------------| +| **I3** | 1 hour | 4 hours | Auto-escalate at max | +| **I2** | 8 hours | 24 hours | Auto-escalate at max | +| **I1** | 24 hours | 72 hours | Flag only | + +### 6.2 Time-to-Resolve (TTR) Targets by Domain + +TTR measures time from DETECTED to RESOLVED. + +| Domain | I3 Target | I2 Target | I1 Target | +|--------|-----------|-----------|-----------| +| **O** (Offering) | 24h | 72h | 7d | +| **P** (People) | 4h | 24h | 72h | +| **J** (Journey) | 8h | 48h | 7d | +| **E** (Environment) | 24h | 72h | 14d | +| **A** (Access) | 4h | 24h | 72h | +| **V** (Value) | 8h | 48h | 7d | +| **R** (Relationship) | 4h | 24h | 72h | + +### 6.3 Resolution Rate Calculation + +``` +Resolution Rate = (RESOLVED + VERIFIED) / (Total Issues - DECLINED) + +Monthly Rolling Resolution Rate: +- Include all issues detected in the month +- Exclude issues still in DETECTED or ACK (not yet in pipeline) +- Calculate at month end + 14 days (allow resolution time) +``` + +**Target Resolution Rates**: + +| Performance Level | Rate | +|-------------------|------| +| Excellent | >= 95% | +| Good | 85-94% | +| Acceptable | 70-84% | +| Poor | < 70% | + +### 6.4 Recurrence Rate Tracking + +``` +Recurrence Rate = REOPENED / RESOLVED + +Where: +- Count REOPENED transitions within verification window +- Exclude declines from denominator +``` + +**Recurrence Interpretation**: + +| Recurrence Rate | Interpretation | Action | +|-----------------|----------------|--------| +| < 5% | Excellent | Maintain process | +| 5-10% | Acceptable | Monitor closely | +| 10-20% | Concerning | Review resolution quality | +| > 20% | Critical | Resolution process audit | + +### 6.5 SLA Dashboard Metrics + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ SLA DASHBOARD │ +├────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Period: 2026-01 (January) │ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ TTA Compliance │ │ TTR Compliance │ │ Resolution Rate │ │ +│ │ 94.2% │ │ 87.5% │ │ 91.3% │ │ +│ │ ▲ +2.1% MoM │ │ ▼ -1.3% MoM │ │ ▲ +3.2% MoM │ │ +│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ Recurrence Rate │ │ Verification │ │ Open Issues │ │ +│ │ 7.8% │ │ Rate: 68.4% │ │ 23 │ │ +│ │ ▼ -1.2% MoM │ │ ▲ +5.1% MoM │ │ ▼ -8 from MoM │ │ +│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ +│ │ +│ By Domain (TTR Compliance): │ +│ ├── O (Offering): 89.2% ████████████████████░░░░ │ +│ ├── P (People): 95.1% ████████████████████████░ │ +│ ├── J (Journey): 82.4% ████████████████████░░░░░ │ +│ ├── E (Environment): 91.0% █████████████████████░░░ │ +│ ├── A (Access): 88.7% ████████████████████░░░░ │ +│ ├── V (Value): 86.3% ███████████████████░░░░░ │ +│ └── R (Relationship): 93.2% ███████████████████████░ │ +│ │ +└────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 7. Example Workflows + +### 7.1 Single Complaint to Resolution to Verification + +**Scenario**: A customer reports that their food arrived cold. + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ WORKFLOW 1: Standard Resolution Cycle │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ T+0h REVIEW RECEIVED │ +│ "My pasta was stone cold when it arrived. Very disappointing." │ +│ │ +│ SPAN CLASSIFIED: │ +│ ├── Primary: O2.05 (Condition at Delivery) │ +│ ├── Valence: V- │ +│ ├── Intensity: I2 │ +│ ├── Specificity: S2 │ +│ ├── Actionability: A2 │ +│ ├── Evidence: ES │ +│ └── Comparative: CR-N │ +│ │ +│ ISSUE CREATED: ISSUE-2026-0142 │ +│ State: DETECTED │ +│ Priority: 2.00 │ +│ Owner: Kitchen Manager │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ T+2h ISSUE ACKNOWLEDGED │ +│ Kitchen manager reviews issue, confirms pattern. │ +│ State: DETECTED → ACKNOWLEDGED │ +│ Notes: "Third cold food report this week. Investigating." │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ T+4h WORK STARTED │ +│ State: ACKNOWLEDGED → IN_PROGRESS │ +│ Action: "Checking heat lamp timers and delivery bags" │ +│ Assigned: Line cook supervisor │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ T+8h ISSUE RESOLVED │ +│ State: IN_PROGRESS → RESOLVED │ +│ Resolution: "Heat lamps recalibrated, new insulated bags │ +│ ordered for delivery. Staff briefed." │ +│ Resolution Code: FIX-EQUIPMENT │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ T+14d VERIFICATION RECEIVED │ +│ │ +│ NEW REVIEW: │ +│ "Great improvement! Food was piping hot this time, much │ +│ better than my last order." │ +│ │ +│ SPAN CLASSIFIED: │ +│ ├── Primary: O2.05 │ +│ ├── Valence: V+ │ +│ ├── Comparative: CR-B ← Explicit improvement signal │ +│ └── ... │ +│ │ +│ ISSUE VERIFIED: ISSUE-2026-0142 │ +│ State: RESOLVED → VERIFIED │ +│ Verification: "CR-B span confirms resolution" │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ METRICS: │ +│ ├── TTA: 2 hours (Target: 8h) ✓ │ +│ ├── TTR: 8 hours (Target: 72h) ✓ │ +│ ├── Time to Verify: 14 days │ +│ └── Recurrence: None │ +│ │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### 7.2 Recurring Issue Detection and Escalation + +**Scenario**: Multiple customers report the same issue that persists despite attempted fixes. + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ WORKFLOW 2: Recurring Issue with Escalation │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Week 1, Day 1 │ +│ │ +│ REVIEW A: "Waited 45 minutes for a table despite reservation" │ +│ SPAN: J1.01 (Wait Time), V-, I3, S3, CR-N │ +│ → ISSUE-2026-0201 CREATED (I3 = immediate) │ +│ → State: DETECTED, Priority: 4.00 │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Week 1, Day 2 │ +│ │ +│ ACKNOWLEDGED and RESOLVED │ +│ Resolution: "Added second host, adjusted OpenTable buffer time" │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Week 2, Day 3 │ +│ │ +│ REVIEW B: "Still waiting 30+ minutes with reservation. Nothing changed" │ +│ SPAN: J1.01, V-, I2, S3, CR-S ← Explicit "unchanged" signal │ +│ │ +│ → ISSUE-2026-0201 REOPENED │ +│ → reopen_count: 1 │ +│ → State: RESOLVED → REOPENED → IN_PROGRESS │ +│ → Priority recalculated: 2.0 * 1.30 * 0.9 * 1.50 = 3.51 │ +│ (I2 × log(2 spans) × decay × recurrence) │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Week 2, Day 5 │ +│ │ +│ RESOLVED AGAIN │ +│ Resolution: "Hired additional staff for Friday/Saturday rush" │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Week 3, Day 6 │ +│ │ +│ REVIEW C: "The wait is even worse than before. 50 minutes this time!" │ +│ SPAN: J1.01, V-, I3, S3, CR-W ← Explicit "worse" signal │ +│ │ +│ → ISSUE-2026-0201 REOPENED + ESCALATED │ +│ → reopen_count: 2 (threshold met) │ +│ → CR-W triggers immediate escalation │ +│ → State: RESOLVED → REOPENED │ +│ → Priority: 4.0 * 1.48 * 0.7 * 1.79 * 1.3 = 9.65 (CRITICAL) │ +│ │ +│ ESCALATION TRIGGERED: │ +│ ├── Reason: "2+ reopens + CR-W regression" │ +│ ├── Escalated To: Operations Director │ +│ ├── Flag: REGRESSION │ +│ └── Required: Root cause analysis within 24h │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ CAUSAL ANALYSIS ADDED (Full Profile): │ +│ ├── CD-O: Operational (demand exceeds capacity) │ +│ └── MG-P: Planning (reservation system not aligned with capacity) │ +│ │ +│ RESOLUTION (with systemic fix): │ +│ "Implemented capacity-based reservation limits. System now blocks │ +│ new reservations when approaching 80% capacity for time slot." │ +│ │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### 7.3 False Resolution and Reopen + +**Scenario**: An issue is marked resolved but customer feedback indicates it was not actually fixed. + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ WORKFLOW 3: False Resolution Detection │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Day 0 │ +│ │ +│ REVIEW: "The checkout button on the app doesn't work!" │ +│ SPAN: E2.02 (Digital Functionality), V-, I3, S2, A3, CR-N │ +│ → ISSUE-2026-0315 CREATED │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 1 │ +│ │ +│ RESOLVED (incorrectly) │ +│ Developer: "Cannot reproduce. Works on our test devices." │ +│ Resolution Code: NAR (Not As Reported) │ +│ State: RESOLVED │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 3 │ +│ │ +│ REVIEW B: "Checkout STILL broken. Same as last week. Unusable app." │ +│ SPAN: E2.02, V-, I3, S2, A3, CR-S ← "Still" = unchanged │ +│ │ +│ → FALSE RESOLUTION DETECTED │ +│ → ISSUE-2026-0315 REOPENED │ +│ → Original resolution invalidated │ +│ → Alert: "Issue marked NAR but customer reports persistence" │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 3 (continued) │ +│ │ +│ REVIEW C: "App checkout broken on Android. Can't complete purchase." │ +│ SPAN: E2.02, V-, I3, S3, A3, CR-N │ +│ │ +│ → AGGREGATED to ISSUE-2026-0315 │ +│ → span_count: 3 │ +│ → Note: S3 span reveals Android-specific issue │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 4 │ +│ │ +│ PROPER INVESTIGATION │ +│ ├── Root cause: Button click area too small on Android devices │ +│ ├── Missed in QA: Only tested on iOS │ +│ └── Fix: Increased tap target to 48dp minimum │ +│ │ +│ RESOLVED (properly) │ +│ ├── Resolution: "Fixed Android tap target size. Deployed v2.3.1" │ +│ ├── Causal (added): MG-T (Testing gaps) │ +│ └── Preventive: "Added Android device farm to CI/CD pipeline" │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 12 │ +│ │ +│ REVIEW D: "Finally! Checkout works perfectly now. Thank you!" │ +│ SPAN: E2.02, V+, I2, S2, A2, CR-B ← Explicit improvement │ +│ │ +│ → ISSUE-2026-0315 VERIFIED │ +│ → State: RESOLVED → VERIFIED │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ POST-MORTEM FLAGS: │ +│ ├── false_resolution_count: 1 │ +│ ├── false_resolution_reason: NAR without proper investigation │ +│ └── lesson_learned: "Require device-specific reproduction steps" │ +│ │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### 7.4 Aggregated Issue from Multiple Reviewers + +**Scenario**: Low-intensity feedback from multiple customers aggregates into a significant issue. + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ WORKFLOW 4: Aggregated Issue Detection │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ AGGREGATION TIMELINE (30-day window) │ +│ │ +│ Day 1 │ +│ REVIEW A: "Music was a bit loud" │ +│ SPAN: E3.02 (Noise Level), V-, I1, S1, A2, CR-N │ +│ → No issue created (I1 requires 5+ spans) │ +│ → Span stored in aggregation buffer │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 5 │ +│ REVIEW B: "Could be quieter in here" │ +│ SPAN: E3.02, V-, I1, S1, A2, CR-N │ +│ → Aggregation check: 2 spans (threshold: 5) │ +│ → No issue yet │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 12 │ +│ REVIEW C: "Background music drowns out conversation" │ +│ SPAN: E3.02, V-, I2, S2, A2, CR-N ← Intensity I2 (threshold: 3) │ +│ → I2 requires only 3 spans! │ +│ → Aggregation check: 3 spans including this I2 │ +│ → ISSUE CREATED: ISSUE-2026-0422 │ +│ │ +│ AGGREGATED ISSUE: │ +│ ├── Subcode: E3.02 (Noise Level) │ +│ ├── Span count: 3 │ +│ ├── Max intensity: I2 │ +│ ├── Avg intensity: I1.33 │ +│ ├── Confidence: 0.80 (3 spans) * 0.98 (evidence) = 0.78 │ +│ └── Priority: 2.0 * 1.48 * 0.87 * 1.0 = 2.57 │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 15 │ +│ REVIEW D: "Music is way too loud. Can barely hear my date." │ +│ SPAN: E3.02, V-, I3, S2, A3, CR-N │ +│ → AGGREGATED to ISSUE-2026-0422 │ +│ → span_count: 4 │ +│ → Max intensity upgraded to I3 │ +│ → Priority recalculated: 4.0 * 1.60 * 0.80 * 1.0 = 5.12 │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Day 18 │ +│ REVIEW E: "Same issue as others - music overwhelming" │ +│ SPAN: E3.02, V-, I2, S1, A2, CR-S ← Explicit "same" = awareness │ +│ → AGGREGATED │ +│ → span_count: 5 │ +│ → recurrence_boost: 1.50 (CR-S signals ongoing) │ +│ → Priority: 4.0 * 1.70 * 0.73 * 1.50 = 7.45 │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ ISSUE SUMMARY AT DAY 18: │ +│ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ ISSUE-2026-0422: Noise Level - Background Music │ │ +│ ├────────────────────────────────────────────────────────────────┤ │ +│ │ State: DETECTED │ │ +│ │ Priority: 7.45 (HIGH) │ │ +│ │ Confidence: 0.88 │ │ +│ │ Owner: Facilities Manager │ │ +│ │ │ │ +│ │ Contributing Spans: │ │ +│ │ ├── Review A (Day 1): I1, S1 - "bit loud" │ │ +│ │ ├── Review B (Day 5): I1, S1 - "could be quieter" │ │ +│ │ ├── Review C (Day 12): I2, S2 - "drowns out conversation" │ │ +│ │ ├── Review D (Day 15): I3, S2 - "way too loud" │ │ +│ │ └── Review E (Day 18): I2, S1 - "same issue" (CR-S) │ │ +│ │ │ │ +│ │ Signals: │ │ +│ │ ├── Consistent pattern across 5 independent reviewers │ │ +│ │ ├── Intensity escalation (I1 → I2 → I3) │ │ +│ │ └── Customer awareness of issue (CR-S in Review E) │ │ +│ │ │ │ +│ │ Recommended Action: │ │ +│ │ "Audit background music volume levels. Consider time-based │ │ +│ │ or occupancy-based volume adjustment." │ │ +│ │ │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 8. Implementation Reference + +### 8.1 Issue Record Schema + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://urt.schema/v5.1/issue", + "title": "URT Issue Record", + "type": "object", + + "properties": { + "issue_id": { + "type": "string", + "pattern": "^ISSUE-[0-9]{4}-[0-9]{4,}$" + }, + "state": { + "enum": ["DETECTED", "ACKNOWLEDGED", "IN_PROGRESS", "RESOLVED", "VERIFIED", "DECLINED", "REOPENED", "STALE"] + }, + "primary_subcode": { + "type": "string", + "pattern": "^[OPJEAVR][1-4]\\.[0-9]{2}$" + }, + "domain": { + "type": "string", + "pattern": "^[OPJEAVR]$" + }, + "span_ids": { + "type": "array", + "items": { "type": "string" }, + "minItems": 1 + }, + "span_count": { + "type": "integer", + "minimum": 1 + }, + "max_intensity": { + "enum": ["I1", "I2", "I3"] + }, + "priority_score": { + "type": "number", + "minimum": 0 + }, + "confidence_score": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "owner_team": { + "type": "string" + }, + "owner_individual": { + "type": "string" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "acknowledged_at": { + "type": "string", + "format": "date-time" + }, + "resolved_at": { + "type": "string", + "format": "date-time" + }, + "verified_at": { + "type": "string", + "format": "date-time" + }, + "reopen_count": { + "type": "integer", + "minimum": 0 + }, + "decline_reason": { + "enum": ["DEC-DUP", "DEC-OOS", "DEC-INS", "DEC-NAR", "DEC-EXT", "DEC-POL", "DEC-OLD"] + }, + "resolution_code": { + "type": "string" + }, + "resolution_notes": { + "type": "string" + }, + "causal_codes": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(CD|MG|SY)-[A-Z]$" + } + }, + "entity": { + "type": "string", + "description": "Product, person, or feature this issue relates to" + }, + "location": { + "type": "string", + "description": "Physical or logical location" + }, + "verification_window_days": { + "type": "integer", + "enum": [30, 60, 90] + }, + "state_history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "state": { "type": "string" }, + "timestamp": { "type": "string", "format": "date-time" }, + "actor": { "type": "string" }, + "notes": { "type": "string" } + } + } + } + }, + + "required": [ + "issue_id", "state", "primary_subcode", "domain", "span_ids", + "span_count", "max_intensity", "priority_score", "confidence_score", + "created_at" + ] +} +``` + +### 8.2 State Transition Event Schema + +```json +{ + "event_type": "state_transition", + "issue_id": "ISSUE-2026-0142", + "from_state": "IN_PROGRESS", + "to_state": "RESOLVED", + "timestamp": "2026-01-15T14:32:00Z", + "actor": "kitchen_manager", + "trigger": "manual", + "resolution_code": "FIX-EQUIPMENT", + "notes": "Heat lamps recalibrated, new insulated bags ordered." +} +``` + +### 8.3 Priority Recalculation Triggers + +Recalculate priority score when: + +1. New span aggregated to issue +2. Daily decay recalculation (batch) +3. CR marker detected (CR-S, CR-W, CR-B) +4. Issue reopened +5. State changed to IN_PROGRESS (freeze priority for SLA) + +--- + +## 9. Integration Points + +### 9.1 From URT Classification + +``` +URT Span Classification + │ + ▼ +┌─────────────────────┐ +│ Span Filter │ +│ (V- only for issues)│ +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Aggregation Engine │ +│ (match/create) │ +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Issue Lifecycle │ +│ (this framework) │ +└─────────────────────┘ +``` + +### 9.2 To Operational Systems + +| Integration | Data Flow | Purpose | +|-------------|-----------|---------| +| **Ticketing** | Issue → Ticket | Route to appropriate team | +| **CRM** | Issue → Customer Record | Track customer issues | +| **Dashboard** | Issue → Metrics | Real-time monitoring | +| **Alerts** | State Change → Notification | SLA warnings | +| **BI/Analytics** | Issue → Data Warehouse | Historical analysis | + +### 9.3 CR Marker Processing + +``` +On new span classified: + IF span.comparative == CR-B: + matching_issues = FIND_RESOLVED_ISSUES(span.subcode) + FOR issue IN matching_issues: + IF within_verification_window(issue): + VERIFY(issue, span) + + ELIF span.comparative IN [CR-S, CR-W]: + matching_issues = FIND_RESOLVED_ISSUES(span.subcode) + FOR issue IN matching_issues: + IF issue.state IN [RESOLVED, VERIFIED]: + REOPEN(issue, span) + IF span.comparative == CR-W: + ESCALATE(issue, reason="REGRESSION") +``` + +--- + +## Document Control + +| Field | Value | +|-------|-------| +| **Document** | C1 - Issue Lifecycle Framework | +| **Version** | 1.0 | +| **Status** | Production Ready | +| **Date** | 2026-01-23 | +| **Author** | URT Working Group | +| **Depends On** | URT Specification v5.1 | +| **Part Of** | Track C: Analytics Layer | + +--- + +## Related Documents + +| Document | Purpose | Status | +|----------|---------|--------| +| **URT Specification v5.1** | Core taxonomy and classification rules | Frozen | +| **C2 - Trend Analysis Framework** | Pattern detection over time | Planned | +| **C3 - Benchmark Framework** | Cross-business comparison | Planned | +| **C4 - Alert & Escalation Rules** | Automated notification logic | Planned | + +--- + +*End of C1: Issue Lifecycle Framework* diff --git a/urt-taxonomy/track-c-analytics/C2-KPI-Mapping-Guide.md b/urt-taxonomy/track-c-analytics/C2-KPI-Mapping-Guide.md new file mode 100644 index 0000000..541adc3 --- /dev/null +++ b/urt-taxonomy/track-c-analytics/C2-KPI-Mapping-Guide.md @@ -0,0 +1,1148 @@ +# C2: KPI Mapping Guide + +## Universal Review Taxonomy (URT) v5.1 - Analytics Track + +**Document**: C2 - KPI Mapping Guide +**Version**: 1.0 +**Status**: Production Ready +**Date**: 2026-01-23 +**Depends On**: URT Specification v5.1, C1-Issue-Lifecycle-Framework + +--- + +## Purpose + +This guide translates URT classifications into actionable business metrics. It provides: + +- Domain and category-level KPIs with calculation formulas +- Composite indices for executive-level monitoring +- Intensity-weighted scoring methodologies +- Trend detection and anomaly identification rules +- Dashboard specifications and alert configurations +- Integration with the Issue Lifecycle Framework (C1) + +--- + +## 1. Domain-Level KPIs + +### 1.1 Overview Matrix + +| Domain | Primary KPI | Unit | Target (Green) | Warning (Yellow) | Critical (Red) | +|--------|------------|------|----------------|------------------|----------------| +| **O** (Offering) | Product Quality Score | 0-100 | >= 80 | 60-79 | < 60 | +| **P** (People) | Personnel Excellence Index | 0-100 | >= 85 | 70-84 | < 70 | +| **J** (Journey) | Process Efficiency Score | 0-100 | >= 75 | 55-74 | < 55 | +| **E** (Environment) | Environment Satisfaction Index | 0-100 | >= 80 | 65-79 | < 65 | +| **A** (Access) | Accessibility Score | 0-100 | >= 85 | 70-84 | < 70 | +| **V** (Value) | Value Perception Index | 0-100 | >= 70 | 50-69 | < 50 | +| **R** (Relationship) | Trust & Loyalty Score | 0-100 | >= 80 | 60-79 | < 60 | + +--- + +### 1.2 O - Offering Domain + +**Primary KPI**: Product Quality Score (PQS) + +**Definition**: Measures customer perception of core product/service quality. + +**Formula**: +``` +PQS = 100 * (V+ spans - V- spans * Intensity_Weight) / Total_O_spans + +Where: + Intensity_Weight = {I1: 1.0, I2: 2.0, I3: 4.0} +``` + +**Secondary KPIs**: +| KPI | Formula | Target | +|-----|---------|--------| +| **Function Reliability Rate** | V+ spans in O1 / Total O1 spans | >= 90% | +| **Quality Consistency Index** | 1 - (StdDev of weekly O2 scores / Mean) | >= 0.85 | +| **Completeness Score** | V+ spans in O3 / Total O3 spans | >= 95% | + +**Benchmark References**: +- Industry Average: 72 +- Top Quartile: 85+ +- Best-in-Class: 92+ + +--- + +### 1.3 P - People Domain + +**Primary KPI**: Personnel Excellence Index (PEI) + +**Definition**: Measures customer perception of staff behavior, competence, and communication. + +**Formula**: +``` +PEI = 100 * weighted_sum(category_scores) / 4 + +Where: + P1_score (Attitude) = weight 0.30 + P2_score (Competence) = weight 0.25 + P3_score (Responsiveness) = weight 0.25 + P4_score (Communication) = weight 0.20 +``` + +**Secondary KPIs**: +| KPI | Formula | Target | +|-----|---------|--------| +| **Staff Attitude Score** | Sentiment ratio of P1 spans | >= 85% positive | +| **Competence Rating** | Weighted average of P2 spans by intensity | >= 80 | +| **Response Quality Index** | (P3 positive + P4 positive) / Total P3+P4 | >= 80% | + +**Benchmark References**: +- Industry Average: 78 +- Top Quartile: 88+ +- Best-in-Class: 94+ + +--- + +### 1.4 J - Journey Domain + +**Primary KPI**: Process Efficiency Score (PES) + +**Definition**: Measures smoothness, timeliness, and reliability of customer journey. + +**Formula**: +``` +PES = 100 * (1 - friction_index) + +friction_index = ( + 0.35 * timing_friction + # J1 negative ratio + 0.30 * ease_friction + # J2 negative ratio + 0.20 * reliability_friction + # J3 negative ratio + 0.15 * resolution_friction # J4 negative ratio +) +``` + +**Secondary KPIs**: +| KPI | Formula | Target | +|-----|---------|--------| +| **Wait Time Satisfaction** | V+ spans in J1.01 / Total J1.01 spans | >= 75% | +| **Process Simplicity Score** | Inverse of J2 negative intensity-weighted count | >= 70 | +| **Reliability Index** | V+ in J3 / Total J3 | >= 85% | + +**Benchmark References**: +- Industry Average: 68 +- Top Quartile: 80+ +- Best-in-Class: 88+ + +--- + +### 1.5 E - Environment Domain + +**Primary KPI**: Environment Satisfaction Index (ESI) + +**Definition**: Measures perception of physical, digital, and ambient environments. + +**Formula**: +``` +ESI = 100 * weighted_sum(category_scores) / 4 + +Where: + E1_score (Physical) = weight 0.30 + E2_score (Digital) = weight 0.30 + E3_score (Ambiance) = weight 0.20 + E4_score (Safety) = weight 0.20 +``` + +**Secondary KPIs**: +| KPI | Formula | Target | +|-----|---------|--------| +| **Cleanliness Score** | V+ in E1.01 / Total E1.01 spans | >= 90% | +| **Digital Experience Score** | Average sentiment of E2 spans | >= 75 | +| **Safety Perception Index** | V+ in E4 / Total E4 (I3 weighted 3x) | >= 95% | + +**Benchmark References**: +- Industry Average: 74 +- Top Quartile: 84+ +- Best-in-Class: 91+ + +--- + +### 1.6 A - Access Domain + +**Primary KPI**: Accessibility Score (AS) + +**Definition**: Measures ease of access, inclusivity, and convenience. + +**Formula**: +``` +AS = 100 * (1 - barrier_index) + +barrier_index = ( + 0.25 * availability_barriers + # A1 negative ratio + 0.35 * accessibility_barriers + # A2 negative ratio (weighted higher) + 0.25 * inclusivity_barriers + # A3 negative ratio + 0.15 * convenience_barriers # A4 negative ratio +) +``` + +**Secondary KPIs**: +| KPI | Formula | Target | +|-----|---------|--------| +| **Availability Rate** | V+ in A1 / Total A1 spans | >= 85% | +| **ADA Compliance Indicator** | 100 - (A2 negative spans * 10) | >= 90 | +| **Inclusivity Score** | V+ in A3 / Total A3 spans | >= 90% | + +**Benchmark References**: +- Industry Average: 76 +- Top Quartile: 87+ +- Best-in-Class: 94+ + +--- + +### 1.7 V - Value Domain + +**Primary KPI**: Value Perception Index (VPI) + +**Definition**: Measures customer assessment of fairness, transparency, and overall worth. + +**Formula**: +``` +VPI = 100 * ( + 0.25 * price_sentiment + # V1 normalized score + 0.30 * transparency_score + # V2 normalized score + 0.15 * effort_perception + # V3 normalized score + 0.30 * worth_assessment # V4 normalized score +) +``` + +**Secondary KPIs**: +| KPI | Formula | Target | +|-----|---------|--------| +| **Price Satisfaction** | V+ in V1 / Total V1 spans | >= 60% | +| **Transparency Score** | V+ in V2 / Total V2 spans | >= 80% | +| **Worth Ratio** | V4.01 positive mentions / Total V4.01 | >= 65% | + +**Benchmark References**: +- Industry Average: 62 +- Top Quartile: 75+ +- Best-in-Class: 85+ + +--- + +### 1.8 R - Relationship Domain + +**Primary KPI**: Trust & Loyalty Score (TLS) + +**Definition**: Measures trust, dependability, recovery, and loyalty perceptions. + +**Formula**: +``` +TLS = 100 * weighted_sum(category_scores) / 4 + +Where: + R1_score (Integrity) = weight 0.35 + R2_score (Dependability) = weight 0.25 + R3_score (Recovery) = weight 0.20 + R4_score (Loyalty) = weight 0.20 +``` + +**Secondary KPIs**: +| KPI | Formula | Target | +|-----|---------|--------| +| **Trust Index** | V+ in R1 / Total R1 (I3 negative weighted 3x) | >= 80% | +| **Recovery Effectiveness** | V+ in R3 / Total R3 spans | >= 75% | +| **Loyalty Indicator** | V+ in R4 / Total R4 spans | >= 70% | + +**Benchmark References**: +- Industry Average: 70 +- Top Quartile: 82+ +- Best-in-Class: 90+ + +--- + +## 2. Category-Level Metrics + +### 2.1 Offering Categories (O1-O4) + +| Category | Metric Name | Data Sources | Aggregation | Comparison Periods | +|----------|-------------|--------------|-------------|-------------------| +| **O1 Function** | Functional Success Rate | O1.01-O1.05 | Positive ratio | WoW, MoM | +| **O2 Quality** | Quality Perception Score | O2.01-O2.05 | Intensity-weighted avg | WoW, MoM, YoY | +| **O3 Completeness** | Completeness Index | O3.01-O3.04 | Binary success rate | MoM | +| **O4 Fit** | Customer Fit Score | O4.01-O4.04 | Weighted average | MoM, QoQ | + +**Calculation Details**: + +``` +Functional_Success_Rate = + (Count(V+, O1.*) + 0.5 * Count(V0, O1.*)) / Total(O1.*) + +Quality_Perception_Score = + SUM(sentiment * intensity_weight) / SUM(intensity_weight) + Where: V+ = +1, V- = -1, V0 = 0, V± = sentiment_ratio +``` + +--- + +### 2.2 People Categories (P1-P4) + +| Category | Metric Name | Data Sources | Aggregation | Comparison Periods | +|----------|-------------|--------------|-------------|-------------------| +| **P1 Attitude** | Attitude Score | P1.01-P1.05 | Sentiment ratio | WoW, MoM | +| **P2 Competence** | Competence Rating | P2.01-P2.05 | Intensity-weighted avg | MoM, QoQ | +| **P3 Responsiveness** | Responsiveness Index | P3.01-P3.05 | Weighted average | WoW, MoM | +| **P4 Communication** | Communication Quality | P4.01-P4.05 | Sentiment ratio | WoW, MoM | + +--- + +### 2.3 Journey Categories (J1-J4) + +| Category | Metric Name | Data Sources | Aggregation | Comparison Periods | +|----------|-------------|--------------|-------------|-------------------| +| **J1 Timing** | Timing Satisfaction | J1.01-J1.05 | Inverse negative ratio | Daily, WoW | +| **J2 Ease** | Effort Score | J2.01-J2.05 | Friction index | WoW, MoM | +| **J3 Reliability** | Process Reliability | J3.01-J3.05 | Consistency measure | MoM, QoQ | +| **J4 Resolution** | Resolution Effectiveness | J4.01-J4.05 | Success rate | WoW, MoM | + +--- + +### 2.4 Environment Categories (E1-E4) + +| Category | Metric Name | Data Sources | Aggregation | Comparison Periods | +|----------|-------------|--------------|-------------|-------------------| +| **E1 Physical** | Physical Space Score | E1.01-E1.05 | Weighted average | WoW, MoM | +| **E2 Digital** | Digital Experience | E2.01-E2.05 | UX score formula | WoW, MoM | +| **E3 Ambiance** | Ambiance Rating | E3.01-E3.05 | Sentiment ratio | MoM, Seasonal | +| **E4 Safety** | Safety Index | E4.01-E4.05 | Critical-weighted avg | Daily, WoW | + +--- + +### 2.5 Access Categories (A1-A4) + +| Category | Metric Name | Data Sources | Aggregation | Comparison Periods | +|----------|-------------|--------------|-------------|-------------------| +| **A1 Availability** | Service Availability | A1.01-A1.05 | Availability ratio | Daily, WoW | +| **A2 Accessibility** | ADA Compliance Score | A2.01-A2.05 | Barrier-weighted | MoM, QoQ | +| **A3 Inclusivity** | Inclusivity Index | A3.01-A3.05 | Sensitivity-weighted | MoM, QoQ | +| **A4 Convenience** | Convenience Score | A4.01-A4.05 | Friction measure | WoW, MoM | + +--- + +### 2.6 Value Categories (V1-V4) + +| Category | Metric Name | Data Sources | Aggregation | Comparison Periods | +|----------|-------------|--------------|-------------|-------------------| +| **V1 Price** | Price Perception | V1.01-V1.05 | Sentiment ratio | MoM, YoY | +| **V2 Transparency** | Transparency Score | V2.01-V2.05 | Trust-weighted avg | MoM, QoQ | +| **V3 Effort** | Effort Perception | V3.01-V3.05 | Inverse effort index | WoW, MoM | +| **V4 Worth** | Worth Assessment | V4.01-V4.05 | Value ratio | MoM, QoQ, YoY | + +--- + +### 2.7 Relationship Categories (R1-R4) + +| Category | Metric Name | Data Sources | Aggregation | Comparison Periods | +|----------|-------------|--------------|-------------|-------------------| +| **R1 Integrity** | Integrity Score | R1.01-R1.05 | Trust-weighted avg | MoM, QoQ | +| **R2 Dependability** | Dependability Index | R2.01-R2.05 | Consistency measure | MoM, QoQ, YoY | +| **R3 Recovery** | Recovery Score | R3.01-R3.05 | Success rate | WoW, MoM | +| **R4 Loyalty** | Loyalty Index | R4.01-R4.05 | Retention signals | MoM, QoQ, YoY | + +--- + +## 3. Composite Indices + +### 3.1 Overall Experience Index (OEI) + +**Definition**: Master index combining all domains into a single experience score. + +**Formula**: +``` +OEI = SUM(Domain_Score * Weight) / SUM(Weights) + +Domain Weights: + O (Offering): 0.20 + P (People): 0.18 + J (Journey): 0.15 + E (Environment): 0.12 + A (Access): 0.10 + V (Value): 0.12 + R (Relationship): 0.13 + ------ + 1.00 +``` + +**Example Calculation**: +``` +Given: + O = 82, P = 88, J = 75, E = 80, A = 85, V = 68, R = 78 + +OEI = (82*0.20 + 88*0.18 + 75*0.15 + 80*0.12 + 85*0.10 + 68*0.12 + 78*0.13) + = (16.4 + 15.84 + 11.25 + 9.6 + 8.5 + 8.16 + 10.14) + = 79.89 + +OEI = 79.9 (rounded) +``` + +**Thresholds**: +| Level | Score | Interpretation | +|-------|-------|----------------| +| Excellent | >= 85 | Top-tier experience | +| Good | 75-84 | Above average | +| Acceptable | 65-74 | Room for improvement | +| Poor | 50-64 | Significant issues | +| Critical | < 50 | Immediate intervention required | + +--- + +### 3.2 Service Excellence Index (SEI) + +**Definition**: Combined measure of people and process quality. + +**Formula**: +``` +SEI = (P_domain * 0.55) + (J_domain * 0.45) + +Where: + P_domain = Personnel Excellence Index + J_domain = Process Efficiency Score +``` + +**Use Case**: Service-oriented businesses (hospitality, healthcare, support). + +**Example Calculation**: +``` +Given: P = 88, J = 75 + +SEI = (88 * 0.55) + (75 * 0.45) + = 48.4 + 33.75 + = 82.15 + +SEI = 82.2 (rounded) +``` + +--- + +### 3.3 Value Perception Index (VPI-C) + +**Definition**: Value perception weighted by product quality reality. + +**Formula**: +``` +VPI-C = V_domain * quality_modifier + +quality_modifier = 0.5 + (O_domain / 200) + +Range: [0.5 * V, 1.0 * V] based on O score +``` + +**Use Case**: Prevents value scores from being inflated when quality is low. + +**Example Calculation**: +``` +Given: V = 68, O = 82 + +quality_modifier = 0.5 + (82 / 200) = 0.5 + 0.41 = 0.91 + +VPI-C = 68 * 0.91 = 61.88 + +VPI-C = 61.9 (rounded) +``` + +--- + +### 3.4 Trust & Loyalty Index (TLI) + +**Definition**: Relationship quality with historical weighting for repeat customers. + +**Formula**: +``` +TLI = R_domain * historical_weight + +historical_weight = 1.0 + (0.1 * log2(1 + repeat_reviews)) + +Where: + repeat_reviews = count of reviews from returning customers +``` + +**Example Calculation**: +``` +Given: R = 78, repeat_reviews = 15 + +historical_weight = 1.0 + (0.1 * log2(16)) = 1.0 + 0.4 = 1.4 + +TLI = min(100, 78 * 1.4) = min(100, 109.2) = 100 + +TLI = 100 (capped) +``` + +**Note**: TLI caps at 100 but the historical weight can push borderline scores into higher brackets. + +--- + +## 4. Intensity-Weighted Scoring + +### 4.1 Intensity Weights + +| Intensity | Weight | Impact Multiplier | Rationale | +|-----------|--------|-------------------|-----------| +| **I1** (Mild) | 1.0 | 1x | Baseline feedback | +| **I2** (Moderate) | 2.0 | 2x | Clear signal requiring attention | +| **I3** (Strong) | 4.0 | 4x | Critical feedback requiring immediate response | + +### 4.2 Weighted Score Calculation + +**Formula**: +``` +Weighted_Score = SUM(sentiment_value * intensity_weight) / SUM(intensity_weight) + +Where: + sentiment_value: V+ = +1, V- = -1, V0 = 0, V± = 0 + intensity_weight: I1 = 1.0, I2 = 2.0, I3 = 4.0 +``` + +### 4.3 Worked Examples + +**Example 1: Balanced Feedback** +``` +Spans: + - V+, I2 (sentiment: +1, weight: 2.0) + - V-, I1 (sentiment: -1, weight: 1.0) + - V+, I1 (sentiment: +1, weight: 1.0) + - V-, I2 (sentiment: -1, weight: 2.0) + +Weighted_Score = ((+1*2) + (-1*1) + (+1*1) + (-1*2)) / (2+1+1+2) + = (2 - 1 + 1 - 2) / 6 + = 0 / 6 + = 0.00 (neutral) +``` + +**Example 2: Severe Negative Impact** +``` +Spans: + - V+, I1 (sentiment: +1, weight: 1.0) + - V+, I1 (sentiment: +1, weight: 1.0) + - V+, I2 (sentiment: +1, weight: 2.0) + - V-, I3 (sentiment: -1, weight: 4.0) <- Critical negative + +Weighted_Score = ((+1*1) + (+1*1) + (+1*2) + (-1*4)) / (1+1+2+4) + = (1 + 1 + 2 - 4) / 8 + = 0 / 8 + = 0.00 (one I3 negative cancels three positives) +``` + +**Example 3: Strong Positive Momentum** +``` +Spans: + - V+, I3 (sentiment: +1, weight: 4.0) + - V+, I2 (sentiment: +1, weight: 2.0) + - V-, I1 (sentiment: -1, weight: 1.0) + +Weighted_Score = ((+1*4) + (+1*2) + (-1*1)) / (4+2+1) + = (4 + 2 - 1) / 7 + = 5 / 7 + = 0.71 (strong positive) +``` + +### 4.4 Converting to 0-100 Scale + +``` +Normalized_Score = 50 + (Weighted_Score * 50) + +Where: + Weighted_Score ranges from -1.0 to +1.0 + Normalized_Score ranges from 0 to 100 +``` + +--- + +## 5. Trend Detection Rules + +### 5.1 Statistical Significance Thresholds + +| Metric Change | Minimum Sample | Significance Level | Detection Method | +|---------------|----------------|-------------------|------------------| +| Domain Score | 30 spans | 95% CI | Z-test | +| Category Score | 20 spans | 90% CI | T-test | +| Subcode Count | 10 spans | 85% CI | Poisson test | +| CR-B/W Shifts | 15 instances | 90% CI | Chi-square | + +### 5.2 Minimum Sample Sizes + +| Analysis Level | Minimum Sample | Confidence Window | +|----------------|----------------|-------------------| +| Daily trending | 50 reviews | +/- 10% | +| Weekly trending | 150 reviews | +/- 5% | +| Monthly trending | 400 reviews | +/- 2.5% | +| Quarterly trending | 1000 reviews | +/- 1.5% | + +**Reliability Formula**: +``` +margin_of_error = z * sqrt(p*(1-p) / n) + +Where: + z = 1.96 for 95% confidence + p = proportion (e.g., positive ratio) + n = sample size +``` + +### 5.3 Seasonality Adjustment + +**Method**: Multiplicative seasonal decomposition + +``` +Adjusted_Score = Observed_Score / Seasonal_Index + +Seasonal_Index = Historical_Period_Average / Annual_Average +``` + +**Common Seasonal Patterns**: + +| Industry | High Seasons | Low Seasons | Adjustment Range | +|----------|--------------|-------------|------------------| +| Retail | Nov-Dec, Mar-Apr | Jan-Feb | 0.85 - 1.20 | +| Hospitality | Jun-Aug, Dec | Jan, Sep | 0.80 - 1.25 | +| Healthcare | Jan-Mar (flu), Oct | Jun-Jul | 0.90 - 1.15 | +| B2B Services | Q4, Q1 | Summer | 0.88 - 1.12 | + +### 5.4 Anomaly Detection Parameters + +**Z-Score Method**: +``` +anomaly IF |z_score| > threshold + +z_score = (observed - mean) / std_dev + +Thresholds: + Warning: |z| > 2.0 + Alert: |z| > 2.5 + Critical: |z| > 3.0 +``` + +**Moving Average Deviation**: +``` +anomaly IF |deviation| > threshold * MA_std + +deviation = current_value - moving_average +threshold = 2.5 (default) +MA_window = 7 days (daily), 4 weeks (weekly) +``` + +--- + +## 6. Comparative Reference (CR) Analytics + +### 6.1 CR-B (Better) - Improvement Tracking + +**Definition**: Signals explicit customer recognition of improvement. + +**Metrics**: +| Metric | Formula | Interpretation | +|--------|---------|----------------| +| **Improvement Rate** | CR-B spans / Total CR spans | % of comparisons showing improvement | +| **Improvement Velocity** | CR-B count this period / CR-B count last period | Acceleration of improvement | +| **Domain Improvement Map** | CR-B distribution by domain | Where improvements are noticed | + +**Impact on Issue Resolution**: +``` +CR-B on resolved issue subcode → VERIFIED state (per C1 framework) +CR-B count >= 2 on open issue → Consider issue improving +``` + +### 6.2 CR-W (Worse) - Regression Indicator + +**Definition**: Signals explicit customer recognition of decline. + +**Metrics**: +| Metric | Formula | Interpretation | +|--------|---------|----------------| +| **Regression Rate** | CR-W spans / Total CR spans | % of comparisons showing decline | +| **Regression Severity** | Avg intensity of CR-W spans | How severe the decline is | +| **Regression Hotspots** | Top subcodes with CR-W | Where quality is declining | + +**Alert Triggers**: +``` +IF CR-W_count > threshold OR CR-W_rate > 15%: + ALERT("Quality Regression Detected") + +IF CR-W on RESOLVED issue: + REOPEN(issue) + ESCALATE(reason="regression") +``` + +### 6.3 CR-S (Same) - Stagnation Detection + +**Definition**: Signals persistent issues that haven't improved. + +**Metrics**: +| Metric | Formula | Interpretation | +|--------|---------|----------------| +| **Stagnation Rate** | CR-S spans / Total CR spans | % of comparisons showing no change | +| **Persistent Issue Index** | CR-S count by subcode | Issues that won't go away | +| **Resolution Failure Rate** | CR-S on RESOLVED issues / Total RESOLVED | % of false resolutions | + +**Stagnation Alerts**: +``` +IF CR-S_count >= 3 on same subcode in 30 days: + FLAG("Persistent Issue - Investigation Required") + +IF CR-S on RESOLVED issue: + REOPEN(issue) + INCREMENT(false_resolution_count) +``` + +### 6.4 Customer Perception Change Tracking + +**Composite CR Score**: +``` +Perception_Trend = (CR-B_weight * CR-B_count - CR-W_weight * CR-W_count) / Total_CR + +Where: + CR-B_weight = +1.0 + CR-W_weight = -1.5 (asymmetric - declines weighted more) + Total_CR = CR-B + CR-W + CR-S (excludes CR-N) +``` + +**Interpretation**: +| Perception_Trend | Status | Action | +|------------------|--------|--------| +| > 0.3 | Improving | Continue current initiatives | +| 0 to 0.3 | Stable | Maintain and monitor | +| -0.3 to 0 | Concerning | Investigate declining areas | +| < -0.3 | Critical | Immediate intervention required | + +--- + +## 7. Dashboard Specifications + +### 7.1 Executive Summary View (Domain-Level) + +**Display Elements**: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ CUSTOMER EXPERIENCE DASHBOARD │ +│ Period: 2026-01 | Reviews: 2,847 │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────┐ ┌────────────────────────────┐ │ +│ │ OVERALL (OEI) │ │ TREND INDICATORS │ │ +│ │ 79.9 │ │ ▲ Improving: O, P, E │ │ +│ │ ▲ +2.3 MoM │ │ ▼ Declining: V │ │ +│ └─────────────────┘ │ → Stable: J, A, R │ │ +│ └────────────────────────────┘ │ +│ │ +│ DOMAIN SCORES │ +│ ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┐ │ +│ │ O │ P │ J │ E │ A │ V │ R │ │ +│ │ 82 │ 88 │ 75 │ 80 │ 85 │ 68 │ 78 │ │ +│ │ +3.2 │ +1.8 │ -0.5 │ +2.1 │ +0.3 │ -2.4 │ +0.8 │ │ +│ └───────┴───────┴───────┴───────┴───────┴───────┴───────┘ │ +│ │ +│ COMPOSITE INDICES │ +│ ├── Service Excellence (SEI): 82.2 ▲ │ +│ ├── Value Perception (VPI-C): 61.9 ▼ │ +│ └── Trust & Loyalty (TLI): 84.5 → │ +│ │ +│ ALERTS (3 Active) │ +│ ├── [!] V domain below target (68 < 70) │ +│ ├── [!] CR-W spike in J1.01 (Wait Time) │ +│ └── [!] 5 open I3 issues > 24h old │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Visualizations**: +- Gauge charts for each domain score +- Trend arrows with MoM delta +- Alert badges for threshold breaches +- Mini sparklines for 12-week trends + +--- + +### 7.2 Operational View (Category + Issues) + +**Display Elements**: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ OPERATIONAL DASHBOARD │ +│ Domain: O (Offering) | Categories: O1-O4 │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ CATEGORY BREAKDOWN │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ O1 Function ████████████████████████░░░░░░ 85% ▲ +3.1% │ │ +│ │ O2 Quality ██████████████████████░░░░░░░░ 78% ▲ +2.5% │ │ +│ │ O3 Completeness████████████████████████████░░ 92% → +0.2% │ │ +│ │ O4 Fit █████████████████████░░░░░░░░░ 73% ▼ -1.8% │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ACTIVE ISSUES (O Domain) │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ ID │ Subcode │ State │ Priority │ Age │ Spans │ Owner │ │ +│ ├─────────────┼─────────┼───────┼──────────┼──────┼───────┼───────┤ │ +│ │ ISSUE-0142 │ O2.05 │ INP │ 5.60 │ 3d │ 5 │ Ops │ │ +│ │ ISSUE-0156 │ O4.01 │ ACK │ 4.20 │ 1d │ 3 │ Ops │ │ +│ │ ISSUE-0161 │ O1.04 │ DET │ 3.85 │ 4h │ 2 │ Prod │ │ +│ └─────────────┴─────────┴───────┴──────────┴──────┴───────┴───────┘ │ +│ │ +│ ISSUE METRICS │ +│ ├── Open Issues: 12 │ +│ ├── Avg Resolution Time: 2.3 days │ +│ ├── Recurrence Rate: 8.2% │ +│ └── SLA Compliance: 91.5% │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Visualizations**: +- Horizontal bar charts for category scores +- Issue list with sortable columns +- Pie chart for issue state distribution +- Timeline for issue age distribution + +--- + +### 7.3 Deep-Dive View (Subcodes + Trends) + +**Display Elements**: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ DEEP-DIVE: O2 Quality │ +│ Period: 2026-01 | 347 spans │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ SUBCODE DISTRIBUTION │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ O2.01 Materials │████████████░░░░│ 89 spans │ 72% V+ │ +5% │ │ +│ │ O2.02 Craftsmanship│█████████░░░░░░░│ 67 spans │ 81% V+ │ +2% │ │ +│ │ O2.03 Presentation │████████████████│ 98 spans │ 85% V+ │ +8% │ │ +│ │ O2.04 Detail │██████░░░░░░░░░░│ 45 spans │ 68% V+ │ -3% │ │ +│ │ O2.05 Condition │████████░░░░░░░░│ 48 spans │ 52% V+ │ -12% │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ 12-WEEK TREND: O2.05 (Condition at Delivery) │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ 80% ┤ │ │ +│ │ 70% ┤ *───* │ │ +│ │ 60% ┤ * *───* │ │ +│ │ 50% ┤* *───*───* │ │ +│ │ 40% ┤ *───*───* │ │ +│ │ └──W1──W2──W3──W4──W5──W6──W7──W8──W9─W10─W11─W12────── │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ COMPARATIVE REFERENCE SIGNALS │ +│ ├── CR-B (Better): 3 spans (6%) │ +│ ├── CR-W (Worse): 8 spans (17%) ← ALERT: Above 15% threshold │ +│ ├── CR-S (Same): 5 spans (10%) │ +│ └── CR-N (None): 32 spans (67%) │ +│ │ +│ INTENSITY DISTRIBUTION │ +│ ├── I1 (Mild): 12 spans (25%) │ +│ ├── I2 (Moderate): 28 spans (58%) │ +│ └── I3 (Strong): 8 spans (17%) ← 4 negative I3 spans │ +│ │ +│ SAMPLE SPANS (Most Recent) │ +│ ├── "Food arrived cold again" - V-, I2, CR-S (Jan 22) │ +│ ├── "Temperature was perfect this time!" - V+, I2, CR-B (Jan 21) │ +│ └── "Stone cold pizza, unacceptable" - V-, I3, CR-N (Jan 20) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Visualizations**: +- Stacked bar charts for subcode distribution +- Line charts for trend analysis +- Heatmaps for intensity by subcode +- Word clouds for span text analysis + +--- + +### 7.4 Visualization Recommendations by KPI Type + +| KPI Type | Primary Viz | Secondary Viz | Interaction | +|----------|-------------|---------------|-------------| +| Domain Score | Gauge/Dial | Trend sparkline | Drill to categories | +| Category Score | Horizontal bar | Comparison to benchmark | Drill to subcodes | +| Trend | Line chart | Moving average overlay | Zoom/pan time range | +| Distribution | Pie/Donut | Treemap for hierarchy | Filter by segment | +| Comparison | Grouped bar | Bullet chart | Toggle comparison periods | +| Volume | Area chart | Stacked area for breakdown | Highlight anomalies | +| Correlation | Scatter plot | Heatmap matrix | Identify clusters | + +--- + +## 8. Alert Rules + +### 8.1 Threshold-Based Alerts + +| Alert Level | Condition | Response Time | Notification | +|-------------|-----------|---------------|--------------| +| **Critical** | Any domain < Red threshold | Immediate | SMS + Email + Dashboard | +| **Warning** | Any domain < Yellow threshold | 4 hours | Email + Dashboard | +| **Info** | Any domain < target but in green | 24 hours | Dashboard only | + +**Domain-Specific Thresholds**: + +```yaml +alerts: + O_offering: + critical: < 60 + warning: < 80 + target: >= 80 + P_people: + critical: < 70 + warning: < 85 + target: >= 85 + J_journey: + critical: < 55 + warning: < 75 + target: >= 75 + E_environment: + critical: < 65 + warning: < 80 + target: >= 80 + A_access: + critical: < 70 + warning: < 85 + target: >= 85 + V_value: + critical: < 50 + warning: < 70 + target: >= 70 + R_relationship: + critical: < 60 + warning: < 80 + target: >= 80 +``` + +--- + +### 8.2 Trend-Based Alerts + +| Alert | Condition | Lookback | Action | +|-------|-----------|----------|--------| +| **Declining Domain** | Score drops > 5 points for 2+ consecutive periods | 3 periods | Investigate root cause | +| **Accelerating Decline** | Rate of decline increasing | 4 periods | Escalate to leadership | +| **Stalled Recovery** | No improvement after intervention | 6 periods | Re-evaluate strategy | +| **Regression After Fix** | Score drops after improvement | 2 periods | Review resolution quality | + +**Configuration**: +```yaml +trend_alerts: + declining_domain: + threshold: -5 + consecutive_periods: 2 + severity: warning + accelerating_decline: + acceleration_threshold: -2 # decline rate increasing by 2+ + periods: 4 + severity: critical + stalled_recovery: + improvement_threshold: 3 # expecting +3 after fix + periods: 6 + severity: warning +``` + +--- + +### 8.3 Volume-Based Alerts + +| Alert | Condition | Window | Action | +|-------|-----------|--------|--------| +| **I3 Spike** | I3 negative count > 2x rolling average | 7 days | Immediate triage | +| **Review Surge** | Total reviews > 3x typical volume | 24 hours | Check for viral event | +| **Complaint Cluster** | Same subcode appears 5+ times in window | 48 hours | Create/prioritize issue | +| **Domain Overload** | Single domain > 50% of all feedback | 7 days | Investigate systemic cause | + +**Configuration**: +```yaml +volume_alerts: + i3_spike: + multiplier: 2.0 + window_days: 7 + min_count: 3 # at least 3 I3s to trigger + severity: critical + review_surge: + multiplier: 3.0 + window_hours: 24 + severity: info + complaint_cluster: + count_threshold: 5 + window_hours: 48 + severity: warning + domain_overload: + percentage_threshold: 50 + window_days: 7 + severity: info +``` + +--- + +### 8.4 Comparative (CR) Alerts + +| Alert | Condition | Action | +|-------|-----------|--------| +| **CR-W Surge** | CR-W rate > 15% of all CR spans | Flag potential regression | +| **CR-S Persistence** | CR-S count >= 3 on same subcode in 30 days | Flag unresolved issue | +| **CR-B Absence** | No CR-B on resolved issue within verification window | Question resolution | +| **Perception Decline** | Perception_Trend < -0.3 | Escalate to leadership | + +**Configuration**: +```yaml +cr_alerts: + cr_w_surge: + threshold_rate: 0.15 + window_days: 30 + severity: critical + cr_s_persistence: + count_threshold: 3 + window_days: 30 + severity: warning + cr_b_absence: + resolved_issue_window_days: 60 + severity: info + perception_decline: + trend_threshold: -0.3 + severity: critical +``` + +--- + +## 9. Integration with Issue Lifecycle (C1) + +### 9.1 Linking KPI Movements to Open Issues + +**Correlation Analysis**: +``` +FOR each domain D: + IF D_score decreased this period: + open_issues = GET_ISSUES(domain=D, state IN [DET, ACK, INP]) + FOR issue IN open_issues: + IF issue.span_count increased this period: + FLAG(issue, "Contributing to domain decline") + IF issue.priority_score > threshold: + RECOMMEND("Prioritize " + issue.id) +``` + +**Issue Impact Scoring**: +``` +Issue_Impact = (span_count / total_domain_spans) * intensity_weight * age_factor + +Where: + age_factor = 1.0 + (days_open / 30) # older issues have higher impact +``` + +--- + +### 9.2 Resolution Impact on Metrics + +**Verification Impact Model**: +``` +Expected_Improvement = ( + resolved_issue_span_count / total_domain_spans +) * resolution_effectiveness + +resolution_effectiveness = { + VERIFIED: 1.0, # Full impact expected + RESOLVED: 0.7, # Partial impact (not yet verified) + REOPENED: -0.5 # Negative impact (false resolution) +} +``` + +**Tracking Resolution Effectiveness**: + +| Metric | Formula | Target | +|--------|---------|--------| +| **Resolution Impact Rate** | Domain improvement post-resolution / Expected improvement | >= 80% | +| **Verification Rate** | VERIFIED issues / RESOLVED issues (within window) | >= 70% | +| **False Resolution Rate** | REOPENED issues / RESOLVED issues | < 10% | + +--- + +### 9.3 Leading vs Lagging Indicators + +**Leading Indicators** (Predictive): + +| Indicator | Predicts | Lead Time | +|-----------|----------|-----------| +| CR-W spike in subcode | Domain score decline | 2-4 weeks | +| I3 negative surge | Issue escalation | 1-2 weeks | +| New issue detection rate | Operational challenges | 1-3 weeks | +| Repeat customer CR-S | Loyalty decline | 4-8 weeks | + +**Lagging Indicators** (Confirmatory): + +| Indicator | Confirms | Lag Time | +|-----------|----------|----------| +| Domain score change | Impact of initiatives | 4-6 weeks | +| CR-B rate increase | Resolution effectiveness | 2-4 weeks | +| Issue verification rate | Process quality | 4-8 weeks | +| Overall Experience Index | Business health | 6-12 weeks | + +--- + +### 9.4 Predictive Signals from URT Data + +**Issue Emergence Prediction**: +``` +P(new_issue) = f( + i1_clustering, # Mild complaints clustering + intensity_escalation, # I1 -> I2 -> I3 pattern + cr_s_accumulation, # "Still" comments building up + specificity_trend # S1 -> S2 -> S3 (getting more specific) +) + +Trigger early warning when: + P(new_issue) > 0.6 AND affected_reviews > 5 +``` + +**Churn Risk Signal**: +``` +Churn_Risk = ( + 0.30 * (R4.05 negative rate) + # "Never again" signals + 0.25 * (V4.04 negative rate) + # "Would not recommend" + 0.20 * (CR-W rate) + # Perceived decline + 0.15 * (issue_recurrence_rate) + # Repeated problems + 0.10 * (TH temporal_pattern) # "Always been like this" +) + +Alert when Churn_Risk > 0.5 +``` + +**Recovery Prediction**: +``` +P(successful_recovery) = f( + issue_age, # Younger = better + resolution_speed, # Faster = better + r3_score, # Better recovery actions = better + cr_b_early_signals # Early CR-B = better +) + +Adjust TTR targets based on P(successful_recovery) +``` + +--- + +## Document Control + +| Field | Value | +|-------|-------| +| **Document** | C2 - KPI Mapping Guide | +| **Version** | 1.0 | +| **Status** | Production Ready | +| **Date** | 2026-01-23 | +| **Author** | URT Working Group | +| **Depends On** | URT Specification v5.1, C1-Issue-Lifecycle-Framework | +| **Part Of** | Track C: Analytics Layer | + +--- + +## Related Documents + +| Document | Purpose | Status | +|----------|---------|--------| +| **URT Specification v5.1** | Core taxonomy and classification rules | Frozen | +| **C1 - Issue Lifecycle Framework** | Issue tracking and resolution states | Complete | +| **C3 - Benchmark Framework** | Cross-business comparison | Planned | +| **C4 - Alert & Escalation Rules** | Automated notification logic | Planned | + +--- + +*End of C2: KPI Mapping Guide* diff --git a/urt-taxonomy/track-d-integration/D1-Dashboard-Specification.md b/urt-taxonomy/track-d-integration/D1-Dashboard-Specification.md new file mode 100644 index 0000000..85c8db9 --- /dev/null +++ b/urt-taxonomy/track-d-integration/D1-Dashboard-Specification.md @@ -0,0 +1,1905 @@ +# D1: Dashboard Specification + +## Universal Review Taxonomy (URT) v5.1 - Integration Track + +**Document**: D1 - Dashboard Specification +**Version**: 1.0 +**Status**: Production Ready +**Date**: 2026-01-23 +**Depends On**: B2-database-schema.sql, B3-owner-routing.md, C1-Issue-Lifecycle-Framework.md, C2-KPI-Mapping-Guide.md + +--- + +## Purpose + +This specification defines the complete UI/visualization requirements for URT v5.1 dashboards. It provides: + +- Dashboard layouts for different user personas (Executive, Operations, Analyst) +- Widget specifications with data sources and refresh rates +- Color schemes aligned with URT taxonomy +- Filter components and interaction patterns +- ASCII wireframes for each view +- API endpoint requirements and caching strategies +- Role-based access control specifications + +--- + +## Table of Contents + +1. [Dashboard Architecture](#1-dashboard-architecture) +2. [Executive Dashboard](#2-executive-dashboard) +3. [Operations Dashboard](#3-operations-dashboard) +4. [Analytics Dashboard](#4-analytics-dashboard) +5. [Deep-Dive Views](#5-deep-dive-views) +6. [Widget Specifications](#6-widget-specifications) +7. [Color Schemes](#7-color-schemes) +8. [Filter Components](#8-filter-components) +9. [Data Requirements](#9-data-requirements) +10. [User Roles & Permissions](#10-user-roles--permissions) +11. [Responsive Design](#11-responsive-design) +12. [Implementation Notes](#12-implementation-notes) + +--- + +## 1. Dashboard Architecture + +### 1.1 System Overview + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ URT DASHBOARD ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ PRESENTATION LAYER │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ +│ │ │Executive │ │Operations│ │Analytics │ │Deep-Dive │ │ │ +│ │ │Dashboard │ │Dashboard │ │Dashboard │ │ Views │ │ │ +│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ +│ └───────┼─────────────┼─────────────┼─────────────┼────────────────────┘ │ +│ │ │ │ │ │ +│ ┌───────┴─────────────┴─────────────┴─────────────┴────────────────────┐ │ +│ │ STATE MANAGEMENT │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │Filter State│ │ User Prefs │ │Cache Layer │ │Real-time │ │ │ +│ │ │ Manager │ │ Storage │ │ (Redis) │ │WebSockets │ │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ +│ └─────────────────────────────────┬────────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────────────────────┴────────────────────────────────────┐ │ +│ │ API LAYER │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ +│ │ │ KPI │ │ Issue │ │ Span │ │ Alert │ │ │ +│ │ │ Endpoints│ │ Endpoints│ │ Endpoints│ │ Endpoints│ │ │ +│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ +│ └───────┴─────────────┴─────────────┴─────────────┴────────────────────┘ │ +│ │ │ +│ ┌─────────────────────────────────┴────────────────────────────────────┐ │ +│ │ DATA LAYER (B2) │ │ +│ │ ┌────────────────────┐ ┌────────────────────┐ │ │ +│ │ │ Materialized Views │ │ Base Tables │ │ │ +│ │ │ mv_domain_summary │ │ reviews, spans │ │ │ +│ │ │ mv_category_break │ │ issues, causal │ │ │ +│ │ │ mv_issue_pipeline │ │ state_history │ │ │ +│ │ │ mv_cr_trends │ │ annotation_audit │ │ │ +│ │ │ mv_daily_volume │ │ │ │ │ +│ │ └────────────────────┘ └────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### 1.2 Dashboard Personas + +| Dashboard | Primary User | Focus | Refresh Rate | +|-----------|--------------|-------|--------------| +| **Executive** | C-Suite, Directors | OEI, trends, alerts | 15 minutes | +| **Operations** | Managers, Team Leads | Issues, SLAs, workload | 5 minutes | +| **Analytics** | Analysts, Data Scientists | Time-series, anomalies | 15 minutes | +| **Deep-Dive** | All users | Individual review/span detail | On-demand | + +### 1.3 Technology Recommendations + +| Component | Recommended Library | Alternatives | +|-----------|---------------------|--------------| +| **Charting** | Recharts | D3.js, Chart.js, ECharts | +| **Data Grid** | AG Grid | React Table, TanStack Table | +| **Gauges** | Custom SVG / D3 | Recharts custom, ApexCharts | +| **Radar Charts** | Recharts | Chart.js, Nivo | +| **Sankey Diagrams** | D3-Sankey | Plotly, ECharts | +| **State Management** | Zustand / Redux Toolkit | Jotai, Recoil | +| **Real-time** | Socket.io | Pusher, Ably | + +--- + +## 2. Executive Dashboard + +### 2.1 Purpose & Key Metrics + +The Executive Dashboard provides at-a-glance visibility into overall customer experience health. It answers: "How are we doing, and where should I focus?" + +**Primary Metrics**: +- Overall Experience Index (OEI) +- 7-Domain Performance Radar +- Critical Issue Alerts +- Week-over-Week and Month-over-Month Trends + +### 2.2 Wireframe + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ URT Dashboard [Executive v] Period: [Last 30 days v] [Filters] [Export] │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────┐ ┌─────────────────────────────────┐ │ +│ │ OVERALL EXPERIENCE INDEX │ │ DOMAIN RADAR CHART │ │ +│ │ │ │ │ │ +│ │ ┌─────────────┐ │ │ O │ │ +│ │ / \ │ │ /|\ │ │ +│ │ / \ │ │ R / \ P │ │ +│ │ │ 79.9 │ │ │ / . \ │ │ +│ │ \ / │ │ V ───.───. J │ │ +│ │ \ ▲ +2.3% / │ │ \ . / │ │ +│ │ └─────────────┘ │ │ A \ / E │ │ +│ │ │ │ \|/ │ │ +│ │ Good [████████████░░] │ │ │ │ +│ │ │ │ ── Current -- Prev Month │ │ +│ └─────────────────────────────────────┘ └─────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ DOMAIN SCORE CARDS (7 CARDS) │ │ +│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ +│ │ │ O │ │ P │ │ J │ │ E │ │ A │ │ V │ │ R │ │ │ +│ │ │ 82 │ │ 88 │ │ 75 │ │ 80 │ │ 85 │ │ 68 │ │ 78 │ │ │ +│ │ │▲+3.2 │ │▲+1.8 │ │▼-0.5 │ │▲+2.1 │ │→+0.3 │ │▼-2.4 │ │→+0.8 │ │ │ +│ │ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │ │ +│ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────┐ ┌───────────────────────────────────┐ │ +│ │ CRITICAL ISSUES ALERT PANEL │ │ TREND INDICATORS │ │ +│ │ │ │ │ │ +│ │ [!] 5 Open I3 Issues > 24h │ │ IMPROVING ▲ │ │ +│ │ └─ ISSUE-2026-0142 (O2.05) │ │ • O: Product Quality (+3.2) │ │ +│ │ └─ ISSUE-2026-0156 (P1.02) │ │ • P: Personnel Index (+1.8) │ │ +│ │ └─ ... │ │ • E: Environment (+2.1) │ │ +│ │ │ │ │ │ +│ │ [!] V Domain Below Target │ │ STABLE → │ │ +│ │ └─ Score: 68 (Target: 70) │ │ • A: Accessibility (+0.3) │ │ +│ │ │ │ • R: Relationship (+0.8) │ │ +│ │ [!] CR-W Spike Detected │ │ │ │ +│ │ └─ J1.01: Wait Time │ │ DECLINING ▼ │ │ +│ │ │ │ • J: Process Efficiency (-0.5) │ │ +│ │ [View All Alerts →] │ │ • V: Value Perception (-2.4) │ │ +│ └───────────────────────────────────┘ └───────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ 12-WEEK OEI TREND LINE │ │ +│ │ 85 ┤ │ │ +│ │ 80 ┤ ___*───* │ │ +│ │ 75 ┤ ___*───*───*───*─── │ │ +│ │ 70 ┤ *───* │ │ +│ │ 65 ┤ │ │ +│ │ └────W1───W2───W3───W4───W5───W6───W7───W8───W9──W10──W11──W12── │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────┐ ┌───────────────────────────────────┐ │ +│ │ COMPOSITE INDICES │ │ QUICK STATS │ │ +│ │ │ │ │ │ +│ │ Service Excellence (SEI) │ │ Reviews This Period: 2,847 │ │ +│ │ [████████████████████░░░] 82.2 ▲ │ │ Spans Classified: 4,215 │ │ +│ │ │ │ Open Issues: 23 │ │ +│ │ Value Perception (VPI-C) │ │ SLA Compliance: 91.5% │ │ +│ │ [████████████░░░░░░░░░░░] 61.9 ▼ │ │ Avg Resolution Time: 2.3 days │ │ +│ │ │ │ Verification Rate: 68.4% │ │ +│ │ Trust & Loyalty (TLI) │ │ │ │ +│ │ [████████████████████░░░] 84.5 → │ │ Last Updated: 2 min ago │ │ +│ └───────────────────────────────────┘ └───────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 2.3 Widget Specifications + +#### 2.3.1 OEI Gauge + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Radial gauge / semi-circular dial | +| **Data Source** | Computed from `mv_domain_summary` | +| **Calculation** | Per C2: weighted sum of domain scores | +| **Ranges** | 0-50 (Red), 50-65 (Yellow), 65-85 (Green), 85-100 (Blue) | +| **Refresh** | 15 minutes | +| **Interactions** | Click to drill into domain breakdown | +| **Library** | Custom SVG or Recharts RadialBarChart | + +**SQL Query**: +```sql +SELECT + SUM(CASE domain_code + WHEN 'O' THEN avg_score * 0.20 + WHEN 'P' THEN avg_score * 0.18 + WHEN 'J' THEN avg_score * 0.15 + WHEN 'E' THEN avg_score * 0.12 + WHEN 'A' THEN avg_score * 0.10 + WHEN 'V' THEN avg_score * 0.12 + WHEN 'R' THEN avg_score * 0.13 + END) AS oei +FROM mv_domain_summary; +``` + +#### 2.3.2 Domain Radar Chart + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Radar / Spider chart | +| **Data Source** | `mv_domain_summary` | +| **Axes** | 7 axes (O, P, J, E, A, V, R) | +| **Scale** | 0-100 per axis | +| **Overlays** | Current period (solid), Previous period (dashed) | +| **Colors** | Current: domain-specific, Previous: gray | +| **Refresh** | 15 minutes | +| **Interactions** | Hover for values, click axis to drill into domain | + +#### 2.3.3 Domain Score Cards + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Metric card with sparkline | +| **Count** | 7 cards (one per domain) | +| **Layout** | Horizontal row, responsive wrap | +| **Elements** | Domain code, score, delta, 12-week sparkline | +| **Colors** | Header bar in domain color | +| **Refresh** | 15 minutes | +| **Interactions** | Click to navigate to Operations view filtered by domain | + +#### 2.3.4 Critical Issues Alert Panel + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Alert list with severity icons | +| **Data Source** | `issues` table filtered by state and priority | +| **Max Items** | 5 (with "View All" link) | +| **Alert Types** | I3 issues, threshold breaches, CR-W spikes, SLA violations | +| **Refresh** | 5 minutes (more frequent than page) | +| **Interactions** | Click issue ID to open Deep-Dive view | + +**Alert Query**: +```sql +SELECT issue_id, primary_subcode, state, priority_score, + EXTRACT(EPOCH FROM (NOW() - created_at)) / 3600 AS age_hours +FROM issues +WHERE state NOT IN ('VERIFIED', 'DECLINED') + AND max_intensity = 'I3' + AND deleted_at IS NULL +ORDER BY priority_score DESC +LIMIT 5; +``` + +#### 2.3.5 Trend Indicators Panel + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Categorized list with arrows | +| **Categories** | Improving (>+2%), Stable (-2% to +2%), Declining (<-2%) | +| **Data Source** | Compare `mv_domain_summary` with previous period | +| **Visual** | Green arrows up, gray arrows right, red arrows down | +| **Refresh** | 15 minutes | + +--- + +## 3. Operations Dashboard + +### 3.1 Purpose & Key Metrics + +The Operations Dashboard provides real-time visibility into issue management and team workload. It answers: "What needs attention now, and who is handling it?" + +**Primary Metrics**: +- Issue Pipeline by State +- SLA Compliance Gauges +- Owner Workload Distribution +- Category Heatmap +- Active Issue Table + +### 3.2 Wireframe + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ URT Dashboard [Operations v] Domain: [All v] Team: [All v] [Filters] │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ISSUE PIPELINE (STATE FLOW) │ │ +│ │ │ │ +│ │ DETECTED → ACKNOWLEDGED → IN_PROGRESS → RESOLVED → VERIFIED │ │ +│ │ │ │ +│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ +│ │ │ 12 │───│ 8 │───│ 15 │───│ 7 │───│ 23 │ │ │ +│ │ │ issues │ │ issues │ │ issues │ │ issues │ │ issues │ │ │ +│ │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ │ +│ │ Avg: 4h Avg: 2h Avg: 3d Pending Complete │ │ +│ │ Verification │ │ +│ │ │ │ +│ │ Side tracks: [DECLINED: 5] [REOPENED: 3] [STALE: 2] │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────┐ ┌─────────────────────────────────────┐ │ +│ │ SLA COMPLIANCE GAUGES │ │ OWNER WORKLOAD DISTRIBUTION │ │ +│ │ │ │ │ │ +│ │ TTA (Time to Acknowledge) │ │ Team │ Open │ Load │Cap │ │ +│ │ ┌────────────────────────┐ │ │ ───────────────────────────────── │ │ +│ │ │████████████████░░░░│94.2%│ │ │ Operations │ 12 │████░│ 80%│ │ +│ │ └────────────────────────┘ │ │ HR/Training │ 8 │███░░│ 60%│ │ +│ │ Target: 95% ▼ -0.8% WoW │ │ Product │ 6 │██░░░│ 45%│ │ +│ │ │ │ Engineering │ 5 │██░░░│ 40%│ │ +│ │ TTR (Time to Resolve) │ │ Facilities │ 4 │█░░░░│ 30%│ │ +│ │ ┌────────────────────────┐ │ │ Finance │ 3 │█░░░░│ 25%│ │ +│ │ │██████████████░░░░░│87.5%│ │ │ CX Leadership │ 2 │░░░░░│ 15%│ │ +│ │ └────────────────────────┘ │ │ │ │ +│ │ Target: 90% ▼ -1.3% WoW │ │ [!] Operations at 80% capacity │ │ +│ │ │ │ │ │ +│ │ Recurrence Rate │ │ │ │ +│ │ ┌────────────────────────┐ │ │ │ │ +│ │ │███░░░░░░░░░░░░░░░│7.8% │ │ │ │ │ +│ │ └────────────────────────┘ │ │ │ │ +│ │ Target: <10% ▼ -1.2% WoW │ │ │ │ +│ └─────────────────────────────────┘ └─────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ CATEGORY BREAKDOWN HEATMAP │ │ +│ │ │ │ +│ │ │ O │ P │ J │ E │ A │ V │ R │ │ │ +│ │ ─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤ │ │ +│ │ 1 │ ██ │ ███ │ ████│ █ │ █ │ ██ │ █░ │ ← Function/Attitude │ │ +│ │ 2 │ ███ │ ██ │ ██ │ ██ │ █ │ ███ │ █░ │ ← Quality/Competence │ │ +│ │ 3 │ █░ │ █░ │ ███ │ █ │ █ │ █░ │ ██ │ ← Complete/Response │ │ +│ │ 4 │ ██ │ ██ │ ████│ ███ │ ██ │ ██ │ █░ │ ← Fit/Communication │ │ +│ │ │ │ +│ │ Legend: ░ Low (0-5) █ Medium (5-15) ██ High (15-30) ███ Critical │ │ +│ │ Intensity indicates negative span count in period │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ACTIVE ISSUES TABLE │ │ +│ │ │ │ +│ │ [Search...________________________] [State: All v] [Priority: All v] │ │ +│ │ │ │ +│ │ ┌────────────┬─────────┬───────┬──────────┬───────┬───────┬──────────┐ │ │ +│ │ │ Issue ID │ Subcode │ State │ Priority │ Age │ Spans │ Owner │ │ │ +│ │ ├────────────┼─────────┼───────┼──────────┼───────┼───────┼──────────┤ │ │ +│ │ │ISSUE-0142 │ O2.05 │ INP │ ████ 5.60│ 3d 4h │ 5 │ Kitchen │ │ │ +│ │ │ISSUE-0156 │ P1.02 │ ACK │ ████ 4.20│ 1d 2h │ 3 │ HR │ │ │ +│ │ │ISSUE-0161 │ J1.01 │ DET │ ███░ 3.85│ 4h │ 2 │ Ops │ │ │ +│ │ │ISSUE-0167 │ E4.01 │ INP │ ███░ 3.50│ 8h │ 1 │ Safety │ │ │ +│ │ │ISSUE-0172 │ V1.04 │ ACK │ ██░░ 2.90│ 12h │ 2 │ Finance │ │ │ +│ │ └────────────┴─────────┴───────┴──────────┴───────┴───────┴──────────┘ │ │ +│ │ │ │ +│ │ Showing 1-5 of 40 issues [< 1 2 3 4 5 ... 8 >] │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 3.3 Widget Specifications + +#### 3.3.1 Issue Pipeline + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Horizontal funnel / flow diagram | +| **Data Source** | `mv_issue_pipeline` materialized view | +| **States** | DETECTED, ACKNOWLEDGED, IN_PROGRESS, RESOLVED, VERIFIED | +| **Side States** | DECLINED, REOPENED, STALE (shown separately) | +| **Metrics Per State** | Issue count, average time in state | +| **Colors** | State-specific (see color scheme) | +| **Refresh** | 5 minutes | +| **Interactions** | Click state box to filter issue table | + +**SQL Query**: +```sql +SELECT + state, + COUNT(*) AS issue_count, + AVG(EXTRACT(EPOCH FROM (NOW() - state_changed_at)) / 3600) AS avg_hours_in_state +FROM issues +WHERE deleted_at IS NULL + AND state NOT IN ('VERIFIED', 'DECLINED') +GROUP BY state +ORDER BY + CASE state + WHEN 'DETECTED' THEN 1 + WHEN 'ACKNOWLEDGED' THEN 2 + WHEN 'IN_PROGRESS' THEN 3 + WHEN 'RESOLVED' THEN 4 + ELSE 5 + END; +``` + +#### 3.3.2 SLA Compliance Gauges + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Horizontal progress bar with target line | +| **Metrics** | TTA Compliance, TTR Compliance, Recurrence Rate | +| **Data Source** | Computed from `issues` and `issue_state_history` | +| **Target Lines** | Configurable per organization | +| **Colors** | Green (>= target), Yellow (within 5%), Red (< target - 5%) | +| **Refresh** | 5 minutes | +| **Interactions** | Click to see breakdown by domain/team | + +**TTA Compliance Query**: +```sql +WITH tta_data AS ( + SELECT + i.issue_id, + i.max_intensity, + EXTRACT(EPOCH FROM (COALESCE(i.acknowledged_at, NOW()) - i.created_at)) / 3600 AS tta_hours, + CASE i.max_intensity + WHEN 'I3' THEN 4 + WHEN 'I2' THEN 24 + ELSE 72 + END AS target_hours + FROM issues i + WHERE i.created_at >= NOW() - INTERVAL '30 days' + AND i.deleted_at IS NULL +) +SELECT + COUNT(*) FILTER (WHERE tta_hours <= target_hours) * 100.0 / COUNT(*) AS tta_compliance +FROM tta_data; +``` + +#### 3.3.3 Owner Workload Distribution + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Horizontal stacked bar chart | +| **Data Source** | `issues` joined with B3 routing config | +| **Metrics** | Open issue count, capacity percentage | +| **Capacity Config** | Defined per team in configuration | +| **Threshold Alerts** | Warning at 70%, Critical at 90% | +| **Refresh** | 5 minutes | +| **Interactions** | Click row to filter issues by team | + +#### 3.3.4 Category Breakdown Heatmap + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Matrix heatmap | +| **Dimensions** | Columns: 7 domains, Rows: 4 category numbers | +| **Cell Value** | Count of negative spans in period | +| **Color Scale** | White (0) → Light Red → Dark Red (high count) | +| **Data Source** | `mv_category_breakdown` | +| **Refresh** | 15 minutes | +| **Interactions** | Click cell to drill into category Deep-Dive | + +#### 3.3.5 Active Issues Table + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Data grid with sorting, filtering, pagination | +| **Library** | AG Grid or React Table | +| **Columns** | Issue ID, Subcode, State, Priority, Age, Span Count, Owner | +| **Default Sort** | Priority (descending) | +| **Filters** | State, Priority range, Domain, Owner, Age range | +| **Page Size** | 10, 25, 50, 100 | +| **Refresh** | 5 minutes | +| **Interactions** | Row click opens issue Deep-Dive, column headers sort | + +**Table Query**: +```sql +SELECT + i.issue_id, + i.primary_subcode, + i.state, + i.priority_score, + NOW() - i.created_at AS age, + i.span_count, + i.owner_team, + d.name AS domain_name +FROM issues i +JOIN urt_domains d ON i.domain_code = d.domain_code +WHERE i.deleted_at IS NULL + AND i.state NOT IN ('VERIFIED', 'DECLINED') +ORDER BY i.priority_score DESC; +``` + +--- + +## 4. Analytics Dashboard + +### 4.1 Purpose & Key Metrics + +The Analytics Dashboard provides deep analytical capabilities for trend analysis and anomaly detection. It answers: "What patterns are emerging, and are things getting better or worse?" + +**Primary Metrics**: +- Time-series KPI charts +- Comparative Reference (CR) trends +- Intensity distribution +- Sentiment flow (Sankey) +- Anomaly detection alerts + +### 4.2 Wireframe + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ URT Dashboard [Analytics v] Period: [Custom v] From:[____] To:[____] │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ TIME-SERIES KPI CHARTS │ │ +│ │ │ │ +│ │ KPI: [OEI v] Granularity: [Weekly v] Compare: [Previous Period v] │ │ +│ │ │ │ +│ │ 100 ┤ │ │ +│ │ 90 ┤ │ │ +│ │ 80 ┤ ___*───*───*───* ___*───*───* │ │ +│ │ 70 ┤ *───* *───* │ │ +│ │ 60 ┤ *─── │ │ +│ │ 50 ┤ │ │ +│ │ └──Jan──Feb──Mar──Apr──May──Jun──Jul──Aug──Sep──Oct──Nov──Dec── │ │ +│ │ │ │ +│ │ ── Current Year -- Previous Year ▓ Target Zone (75-85) │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────┐ ┌─────────────────────────────────────┐ │ +│ │ COMPARATIVE REFERENCE TRENDS │ │ INTENSITY DISTRIBUTION │ │ +│ │ │ │ │ │ +│ │ Weekly CR Signal Distribution │ │ This Period vs Previous │ │ +│ │ │ │ │ │ +│ │ CR-B ████████████ 28% │ │ I1 I2 I3 │ │ +│ │ CR-S █████████ 18% │ │ Curr ████ ██████ ██ │ │ +│ │ CR-W ████ 8% │ │ 42% 45% 13% │ │ +│ │ CR-N ████████████████ 46% │ │ │ │ +│ │ │ │ Prev █████ █████ ███ │ │ +│ │ ▲ CR-B/CR-W Ratio: 3.5 │ │ 38% 42% 20% │ │ +│ │ (Improving from 2.8) │ │ │ │ +│ │ │ │ [!] I3 down 7% - good trend │ │ +│ │ 12-Week Trend: │ │ │ │ +│ │ ───*───*───*───*───*───* │ │ │ │ +│ └─────────────────────────────────┘ └─────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ SENTIMENT FLOW (SANKEY DIAGRAM) │ │ +│ │ │ │ +│ │ Source Domain Valence Outcome │ │ +│ │ │ │ +│ │ ┌──────┐ │ │ +│ │ ┌──────┐ ════╡ O ╞═══╗ ┌──────┐ ┌──────────┐ │ │ +│ │ │Google│══════╡ P ╞═══╬════╡ V+ ╞═════╡ Resolved │ │ │ +│ │ │ 65% │ ╡ J ╞═══╬════╡ ╞ └──────────┘ │ │ +│ │ └──────┘ ════╡ E ╞═══╝ └──────┘ │ │ +│ │ ┌──────┐ │ A │ ┌──────┐ ┌──────────┐ │ │ +│ │ │ Yelp │══════╡ V ╞════════╡ V- ╞═════╡Open Issue│ │ │ +│ │ │ 25% │ ════╡ R ╞═══╗ │ │ └──────────┘ │ │ +│ │ └──────┘ └──────┘ ╚════╡ ╞ │ │ +│ │ ┌──────┐ └──────┘ ┌──────────┐ │ │ +│ │ │Other │══════════════════════════════════╡ Neutral │ │ │ +│ │ │ 10% │ └──────────┘ │ │ +│ │ └──────┘ │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ANOMALY DETECTION ALERTS │ │ +│ │ │ │ +│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ [!] CRITICAL: J1.01 (Wait Time) volume +180% vs 7-day avg │ │ │ +│ │ │ Detected: 2026-01-23 14:30 | Affected reviews: 23 │ │ │ +│ │ │ [View Details] [Acknowledge] [Create Issue] │ │ │ +│ │ └───────────────────────────────────────────────────────────────────┘ │ │ +│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ [!] WARNING: V domain score dropped 5.2 points in 2 weeks │ │ │ +│ │ │ Trend: 73.2 → 68.0 | Significance: 95% CI │ │ │ +│ │ │ [View Details] [Investigate] │ │ │ +│ │ └───────────────────────────────────────────────────────────────────┘ │ │ +│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ [i] INFO: CR-B surge in O2.05 suggests successful intervention │ │ │ +│ │ │ Previous issue: ISSUE-2026-0098 (Resolved 2026-01-15) │ │ │ +│ │ │ [View Issue History] │ │ │ +│ │ └───────────────────────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 4.3 Widget Specifications + +#### 4.3.1 Time-Series KPI Charts + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Line chart with area fill option | +| **KPI Options** | OEI, all domain scores, category scores, issue counts | +| **Granularity** | Daily, Weekly, Monthly, Quarterly | +| **Overlays** | Previous period, target zone, trend line | +| **Data Source** | `mv_daily_volume` aggregated to selected granularity | +| **Refresh** | 15 minutes | +| **Interactions** | Hover for values, zoom, pan, export | + +#### 4.3.2 Comparative Reference Trends + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Stacked bar + ratio line | +| **Data Source** | `mv_cr_trends` | +| **Metrics** | CR-B, CR-W, CR-S, CR-N percentages; CR-B/CR-W ratio | +| **Time Range** | Configurable (default: 12 weeks) | +| **Key Insight** | Ratio > 2.0 indicates net improvement | +| **Refresh** | 15 minutes | +| **Interactions** | Click bar segment to see affected subcodes | + +**SQL Query**: +```sql +SELECT + week_start, + comparative, + SUM(span_count) AS span_count, + SUM(span_count) * 100.0 / SUM(SUM(span_count)) OVER (PARTITION BY week_start) AS pct +FROM mv_cr_trends +WHERE week_start >= NOW() - INTERVAL '12 weeks' +GROUP BY week_start, comparative +ORDER BY week_start; +``` + +#### 4.3.3 Intensity Distribution Histogram + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Grouped bar chart (current vs previous) | +| **Data Source** | `spans` aggregated by intensity | +| **Categories** | I1 (Mild), I2 (Moderate), I3 (Strong) | +| **Key Insight** | Decreasing I3 percentage indicates improvement | +| **Refresh** | 15 minutes | +| **Interactions** | Click bar to filter Deep-Dive by intensity | + +#### 4.3.4 Sentiment Flow Sankey Diagram + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Sankey diagram | +| **Library** | D3-Sankey or Recharts Sankey | +| **Nodes** | Source → Domain → Valence → Outcome | +| **Link Width** | Proportional to span count | +| **Colors** | Domain colors, valence colors | +| **Data Source** | `spans` joined with `issues` and `reviews` | +| **Refresh** | 15 minutes | +| **Interactions** | Hover links for counts, click to filter | + +#### 4.3.5 Anomaly Detection Alerts + +| Attribute | Specification | +|-----------|---------------| +| **Type** | Alert card list | +| **Detection Methods** | Z-score (>2.5), Moving average deviation, Trend break | +| **Alert Levels** | Critical (immediate), Warning (24h), Info (monitoring) | +| **Data Source** | Real-time anomaly detection service | +| **Refresh** | 5 minutes | +| **Actions** | View Details, Acknowledge, Create Issue, Dismiss | + +**Anomaly Detection Logic** (per C2 Section 5.4): +```sql +WITH daily_stats AS ( + SELECT + DATE(created_at) AS span_date, + primary_code, + COUNT(*) AS daily_count, + AVG(COUNT(*)) OVER ( + PARTITION BY primary_code + ORDER BY DATE(created_at) + ROWS BETWEEN 7 PRECEDING AND 1 PRECEDING + ) AS moving_avg, + STDDEV(COUNT(*)) OVER ( + PARTITION BY primary_code + ORDER BY DATE(created_at) + ROWS BETWEEN 7 PRECEDING AND 1 PRECEDING + ) AS moving_stddev + FROM spans + WHERE valence = 'V-' + AND created_at >= NOW() - INTERVAL '30 days' + GROUP BY DATE(created_at), primary_code +) +SELECT * +FROM daily_stats +WHERE ABS(daily_count - moving_avg) > 2.5 * NULLIF(moving_stddev, 0); +``` + +--- + +## 5. Deep-Dive Views + +### 5.1 Individual Review Annotation Viewer + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ Review Deep-Dive [Print] [Export JSON] [Close X] │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ REVIEW METADATA │ │ +│ │ │ │ +│ │ Review ID: RVW-2026-04521 Source: Google │ │ +│ │ Author: John D. Rating: ★★☆☆☆ (2/5) │ │ +│ │ Date: 2026-01-20 Business: Main Street Cafe │ │ +│ │ Language: en External ID: CgxKCQ1... │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ANNOTATED REVIEW TEXT │ │ +│ │ │ │ +│ │ "[The food was cold when it arrived]₁ but [the waiter was very │ │ +│ │ apologetic and helpful]₂. [We had to wait 45 minutes for a table │ │ +│ │ despite having a reservation]₃." │ │ +│ │ │ │ +│ │ Legend: [Span 1]₁ = O2.05 [Span 2]₂ = P1.01+R3.02 [Span 3]₃ = J1.01 │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ SPAN DETAILS │ │ +│ │ │ │ +│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ SPAN 1: "The food was cold when it arrived" │ │ │ +│ │ │ │ │ │ +│ │ │ Primary Code: O2.05 (Condition at Delivery) │ │ │ +│ │ │ Secondary: None │ │ │ +│ │ │ │ │ │ +│ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ +│ │ │ │ Valence │ V- Negative │ Temporal │ TC Current │ │ │ │ +│ │ │ │ Intensity │ I2 Moderate │ Evidence │ ES Stated │ │ │ │ +│ │ │ │ Specificity │ S2 Moderate │ Comparative │ CR-N None │ │ │ │ +│ │ │ │ Actionability│ A2 Medium │ │ │ │ │ │ +│ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Linked Issue: ISSUE-2026-0142 [View Issue →] │ │ │ +│ │ │ Confidence: 0.92 │ │ │ +│ │ │ Annotated By: LLM (claude-3-opus) at 2026-01-20 14:32:00 │ │ │ +│ │ └───────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ SPAN 2: "the waiter was very apologetic and helpful" │ │ │ +│ │ │ │ │ │ +│ │ │ Primary Code: P1.01 (Warmth/Friendliness) │ │ │ +│ │ │ Secondary: R3.02 (Apology) │ │ │ +│ │ │ │ │ │ +│ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ +│ │ │ │ Valence │ V+ Positive │ Temporal │ TC Current │ │ │ │ +│ │ │ │ Intensity │ I2 Moderate │ Evidence │ ES Stated │ │ │ │ +│ │ │ │ Specificity │ S2 Moderate │ Comparative │ CR-N None │ │ │ │ +│ │ │ │ Actionability│ A1 Low │ │ │ │ │ │ +│ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Linked Issue: None (positive feedback) │ │ │ +│ │ │ Confidence: 0.88 │ │ │ +│ │ └───────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [+ Show Span 3] │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 5.2 Issue History Timeline + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ Issue Deep-Dive: ISSUE-2026-0142 [Export] [Print] [Close X] │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ISSUE SUMMARY │ │ +│ │ │ │ +│ │ Issue ID: ISSUE-2026-0142 State: IN_PROGRESS │ │ +│ │ Primary Code: O2.05 (Condition) Priority: ████ 5.60 │ │ +│ │ Domain: O (Offering) Confidence: 0.88 │ │ +│ │ Owner: Kitchen Operations Reopened: 1 time │ │ +│ │ │ │ +│ │ Entity: Food delivery Location: Main Kitchen │ │ +│ │ Created: 2026-01-18 09:15 Last Update: 2 hours ago │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ STATE TIMELINE │ │ +│ │ │ │ +│ │ ●──────●──────●──────●──────●──────● │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ DET ACK INP RES REO INP │ │ +│ │ 1/18 1/18 1/18 1/19 1/21 1/21 │ │ +│ │ │ │ +│ │ [+] Jan 18, 09:15 - DETECTED │ │ +│ │ Trigger: New V- span (I2) on O2.05 │ │ +│ │ Initial spans: 1 │ │ +│ │ │ │ +│ │ [+] Jan 18, 09:45 - ACKNOWLEDGED │ │ +│ │ Actor: kitchen_manager (manual) │ │ +│ │ Note: "Third cold food report this week" │ │ +│ │ │ │ +│ │ [+] Jan 18, 11:00 - IN_PROGRESS │ │ +│ │ Actor: kitchen_supervisor │ │ +│ │ Note: "Checking heat lamp timers" │ │ +│ │ │ │ +│ │ [+] Jan 19, 14:30 - RESOLVED │ │ +│ │ Actor: kitchen_supervisor │ │ +│ │ Resolution: FIX-EQUIPMENT │ │ +│ │ Note: "Heat lamps recalibrated, new bags ordered" │ │ +│ │ │ │ +│ │ [!] Jan 21, 10:15 - REOPENED │ │ +│ │ Trigger: CR-S span detected ("Food still cold") │ │ +│ │ Span ID: SPN-2026-08742 │ │ +│ │ │ │ +│ │ [+] Jan 21, 10:30 - IN_PROGRESS │ │ +│ │ Actor: kitchen_manager │ │ +│ │ Note: "Escalating to delivery process review" │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ CONTRIBUTING SPANS (5) │ │ +│ │ │ │ +│ │ ┌─────────┬──────────────────────────────────────┬────┬────┬────────┐ │ │ +│ │ │ Date │ Span Text (truncated) │ V │ I │ CR │ │ │ +│ │ ├─────────┼──────────────────────────────────────┼────┼────┼────────┤ │ │ +│ │ │ Jan 18 │ "The food was cold when it arrived" │ V- │ I2 │ CR-N │ │ │ +│ │ │ Jan 19 │ "My burger came out cold" │ V- │ I2 │ CR-N │ │ │ +│ │ │ Jan 20 │ "Food arrived cold again" │ V- │ I2 │ CR-S │ │ │ +│ │ │ Jan 21 │ "Food still arrives cold" │ V- │ I2 │ CR-S │ │ │ +│ │ │ Jan 22 │ "Temperature is always bad" │ V- │ I2 │ CR-S │ │ │ +│ │ └─────────┴──────────────────────────────────────┴────┴────┴────────┘ │ │ +│ │ │ │ +│ │ [View All Spans →] │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ CAUSAL CHAIN (if assigned) │ │ +│ │ │ │ +│ │ Experience → Conditions → Management → Systemic │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ +│ │ │ O2.05 │ ───► │ CD-E │ ───► │ MG-R │ ───► │ SY-R │ │ │ +│ │ │Condition │ │Equipment │ │Resources │ │ Budget │ │ │ +│ │ │at Deliv. │ │ │ │ │ │ │ │ │ +│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ +│ │ │ │ +│ │ Chain Confidence: 0.75 │ │ +│ │ Analyst Note: "Heat lamps outdated, replacement budget pending" │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ACTIONS │ │ +│ │ │ │ +│ │ [Acknowledge] [Start Work] [Resolve] [Decline] [Add Note] [Reassign] │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 5.3 Causal Chain Visualization + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ Causal Chain Analysis [Close X] │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ CAUSAL CHAIN DIAGRAM │ │ +│ │ │ │ +│ │ LAYER 1 LAYER 2 LAYER 3 LAYER 4│ +│ │ EXPERIENCE CONDITIONS MANAGEMENT SYSTEMIC│ +│ │ │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐│ │ +│ │ │ O2.05 │ ┌───▶│ CD-E │ ┌───▶│ MG-R │ ┌───▶│ SY-R ││ │ +│ │ │Condition │────┤ │Equipment │────┤ │Resources │────┤ │Budget││ │ +│ │ │at Deliv. │ │ │Malfunction│ │ │Maintenance│ │ │ ││ │ +│ │ └──────────┘ │ └──────────┘ │ └──────────┘ │ └──────┘│ │ +│ │ │ │ │ │ │ │ +│ │ │ │ ┌──────────┐ │ ┌──────────┐ │ ┌──────┐│ │ +│ │ └──────────┼───▶│ CD-O │────┼───▶│ MG-P │────┴───▶│ SY-H ││ │ +│ │ │ │Operational│ │ │Planning │ │Human ││ │ +│ │ │ │Understaffed│ │ │Scheduling│ │Capital│ │ +│ │ │ └──────────┘ │ └──────────┘ └──────┘│ │ +│ │ │ │ │ │ +│ │ │ ┌──────────┐ │ │ │ +│ │ └───▶│ CD-S │────┘ │ │ +│ │ │Staff State│ │ │ +│ │ │Fatigue │ │ │ +│ │ └──────────┘ │ │ +│ │ │ │ +│ │ ─────────────────────────────────────────────────────────────────── │ │ +│ │ │ │ +│ │ CHAIN STATISTICS: │ │ +│ │ │ │ +│ │ Most Common Paths: │ │ +│ │ 1. O2.05 → CD-E → MG-R → SY-R (45% of similar issues) │ │ +│ │ 2. O2.05 → CD-O → MG-P → SY-H (30% of similar issues) │ │ +│ │ 3. O2.05 → CD-S → MG-T → SY-C (15% of similar issues) │ │ +│ │ │ │ +│ │ Recommended Intervention Level: MANAGEMENT (MG-R) │ │ +│ │ Reason: 70% of paths converge at resource management │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 6. Widget Specifications + +### 6.1 Gauge Widget + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ GAUGE WIDGET SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual: │ +│ ╭─────────────────────────────╮ │ +│ ╱ ░░░░░░░░ ╲ │ +│ ╱ ░░░░░░░ ░░░░░░░ ╲ │ +│ │ ░░░ ▲ ░░░ │ │ +│ │ ░░ ╱▔▔▔▔▔▔▔▔▔╲ ░░ │ │ +│ │░ ╱ 79.9 ╲ ░│ │ +│ │ ╱ ╲ │ │ +│ ╲╱ ╲╱ │ +│ ████████████████████░░░░░░░░░ │ +│ Red Yellow Green Blue │ +│ 0 50 65 85 100 │ +│ │ +│ Components: │ +│ ├── Arc: SVG path with gradient │ +│ ├── Needle: SVG line with rotation transform │ +│ ├── Value: Centered text │ +│ ├── Delta: Below value with arrow │ +│ ├── Labels: Min/Max/Target markers │ +│ └── Background: Semi-transparent fill │ +│ │ +│ Props: │ +│ ├── value: number (0-100) │ +│ ├── previousValue?: number (for delta) │ +│ ├── ranges: Array<{min, max, color}> │ +│ ├── targetValue?: number (optional target line) │ +│ ├── size: 'sm' | 'md' | 'lg' │ +│ └── onDrillDown?: () => void │ +│ │ +│ Responsive: │ +│ ├── lg (>1200px): 200x120 │ +│ ├── md (768-1199px): 160x100 │ +│ └── sm (<768px): 120x80 │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 6.2 Radar Chart Widget + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ RADAR CHART WIDGET SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Library: Recharts RadarChart │ +│ │ +│ Configuration: │ +│ { │ +│ data: [ │ +│ { domain: 'O', current: 82, previous: 79, target: 80 }, │ +│ { domain: 'P', current: 88, previous: 86, target: 85 }, │ +│ { domain: 'J', current: 75, previous: 76, target: 75 }, │ +│ { domain: 'E', current: 80, previous: 78, target: 80 }, │ +│ { domain: 'A', current: 85, previous: 85, target: 85 }, │ +│ { domain: 'V', current: 68, previous: 70, target: 70 }, │ +│ { domain: 'R', current: 78, previous: 77, target: 80 } │ +│ ], │ +│ angleKey: 'domain', │ +│ series: [ │ +│ { key: 'current', stroke: '#3B82F6', fill: '#3B82F680' }, │ +│ { key: 'previous', stroke: '#9CA3AF', strokeDash: '5,5' },│ +│ { key: 'target', stroke: '#10B981', strokeDash: '2,2' } │ +│ ] │ +│ } │ +│ │ +│ Interactions: │ +│ ├── Hover axis: Show domain tooltip with score details │ +│ ├── Click axis: Navigate to domain-filtered Operations │ +│ └── Legend toggle: Show/hide series │ +│ │ +│ Responsive: │ +│ ├── lg: 400x400 │ +│ ├── md: 300x300 │ +│ └── sm: 250x250 (stacked with score cards) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 6.3 Data Grid Widget + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ DATA GRID WIDGET SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Library: AG Grid Community │ +│ │ +│ Column Definitions (Issues Table): │ +│ [ │ +│ { field: 'issue_id', headerName: 'Issue ID', width: 130, │ +│ cellRenderer: 'issueLinkRenderer' }, │ +│ { field: 'primary_subcode', headerName: 'Subcode', width: 90,│ +│ cellRenderer: 'subcodeChipRenderer' }, │ +│ { field: 'state', headerName: 'State', width: 100, │ +│ cellRenderer: 'stateBadgeRenderer' }, │ +│ { field: 'priority_score', headerName: 'Priority', width: 120│ +│ cellRenderer: 'priorityBarRenderer', sort: 'desc' }, │ +│ { field: 'age', headerName: 'Age', width: 80, │ +│ valueFormatter: formatDuration }, │ +│ { field: 'span_count', headerName: 'Spans', width: 70 }, │ +│ { field: 'owner_team', headerName: 'Owner', width: 120 } │ +│ ] │ +│ │ +│ Grid Options: │ +│ { │ +│ pagination: true, │ +│ paginationPageSize: 10, │ +│ paginationPageSizeSelector: [10, 25, 50, 100], │ +│ rowSelection: 'single', │ +│ onRowClicked: (event) => openIssueDeepDive(event.data), │ +│ defaultColDef: { sortable: true, filter: true, resizable: true│ +│ } │ +│ │ +│ Custom Renderers: │ +│ ├── issueLinkRenderer: Clickable link to Deep-Dive │ +│ ├── subcodeChipRenderer: Colored chip with domain color │ +│ ├── stateBadgeRenderer: State-colored badge │ +│ └── priorityBarRenderer: Mini horizontal bar chart │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 6.4 Sparkline Widget + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SPARKLINE WIDGET SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual: ~~~~~~* │ +│ │ +│ Library: Recharts LineChart (minimal config) │ +│ │ +│ Configuration: │ +│ { │ +│ data: Array<{ date: string, value: number }>, │ +│ width: 80, │ +│ height: 24, │ +│ margin: { top: 2, bottom: 2, left: 0, right: 0 }, │ +│ stroke: determineStrokeColor(trend), │ +│ strokeWidth: 1.5, │ +│ dot: { r: 2 } // Only on last point │ +│ } │ +│ │ +│ Color Logic: │ +│ ├── Positive trend (last > first): Green (#10B981) │ +│ ├── Negative trend (last < first): Red (#EF4444) │ +│ └── Stable (|delta| < 2%): Gray (#6B7280) │ +│ │ +│ Props: │ +│ ├── data: Array<{date, value}> │ +│ ├── color?: 'auto' | string │ +│ └── showEndpoint?: boolean (default: true) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 6.5 Alert Card Widget + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ALERT CARD WIDGET SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual: │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ [!] CRITICAL: J1.01 (Wait Time) volume +180% │ │ +│ │ Detected: 2026-01-23 14:30 | Affected: 23 reviews │ │ +│ │ [View Details] [Acknowledge] [Create Issue] │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ Severity Styles: │ +│ ├── CRITICAL: Red border left, red icon, red highlight │ +│ ├── WARNING: Yellow border left, yellow icon │ +│ ├── INFO: Blue border left, blue icon │ +│ └── SUCCESS: Green border left, green icon │ +│ │ +│ Props: │ +│ { │ +│ severity: 'critical' | 'warning' | 'info' | 'success', │ +│ title: string, │ +│ description: string, │ +│ timestamp: Date, │ +│ metadata?: Record, │ +│ actions: Array<{label: string, onClick: () => void}> │ +│ } │ +│ │ +│ Accessibility: │ +│ ├── role="alert" for critical/warning │ +│ ├── aria-live="polite" for new alerts │ +│ └── Focus management for action buttons │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 7. Color Schemes + +### 7.1 Domain Color Palette + +Each domain has a primary, secondary, and light variant for consistent visual identity. + +| Domain | Code | Primary (Dark) | Secondary (Medium) | Light (Background) | Meaning | +|--------|------|----------------|--------------------|--------------------|---------| +| **Offering** | O | `#2563EB` | `#3B82F6` | `#DBEAFE` | Blue (Product) | +| **People** | P | `#7C3AED` | `#8B5CF6` | `#EDE9FE` | Purple (Human) | +| **Journey** | J | `#0891B2` | `#06B6D4` | `#CFFAFE` | Cyan (Process) | +| **Environment** | E | `#059669` | `#10B981` | `#D1FAE5` | Green (Space) | +| **Access** | A | `#D97706` | `#F59E0B` | `#FEF3C7` | Amber (Reach) | +| **Value** | V | `#DC2626` | `#EF4444` | `#FEE2E2` | Red (Cost) | +| **Relationship** | R | `#DB2777` | `#EC4899` | `#FCE7F3` | Pink (Trust) | + +### 7.2 Valence Colors + +| Valence | Code | Color | Hex | Use Case | +|---------|------|-------|-----|----------| +| **Positive** | V+ | Green | `#10B981` | Praise, satisfaction | +| **Negative** | V- | Red | `#EF4444` | Complaints, issues | +| **Neutral** | V0 | Gray | `#6B7280` | Observations | +| **Mixed** | V+/- | Yellow | `#F59E0B` | Ambiguous feedback | + +### 7.3 Intensity Gradients + +| Intensity | Code | Color | Opacity | Visual | +|-----------|------|-------|---------|--------| +| **Mild** | I1 | Base | 40% | Light shade | +| **Moderate** | I2 | Base | 70% | Medium shade | +| **Strong** | I3 | Base | 100% | Full saturation | + +**CSS Variables**: +```css +:root { + /* Intensity modifiers */ + --intensity-i1-opacity: 0.4; + --intensity-i2-opacity: 0.7; + --intensity-i3-opacity: 1.0; + + /* Combined with valence */ + --positive-i1: rgba(16, 185, 129, 0.4); + --positive-i2: rgba(16, 185, 129, 0.7); + --positive-i3: rgba(16, 185, 129, 1.0); + --negative-i1: rgba(239, 68, 68, 0.4); + --negative-i2: rgba(239, 68, 68, 0.7); + --negative-i3: rgba(239, 68, 68, 1.0); +} +``` + +### 7.4 Alert State Colors + +| Alert Level | Background | Border | Icon | Text | +|-------------|------------|--------|------|------| +| **Critical** | `#FEF2F2` | `#EF4444` | `#DC2626` | `#991B1B` | +| **Warning** | `#FFFBEB` | `#F59E0B` | `#D97706` | `#92400E` | +| **Info** | `#EFF6FF` | `#3B82F6` | `#2563EB` | `#1E40AF` | +| **Success** | `#F0FDF4` | `#10B981` | `#059669` | `#166534` | + +### 7.5 Issue State Colors + +| State | Color | Hex | Icon | +|-------|-------|-----|------| +| **DETECTED** | Orange | `#F97316` | Circle outline | +| **ACKNOWLEDGED** | Blue | `#3B82F6` | Eye icon | +| **IN_PROGRESS** | Yellow | `#EAB308` | Spinning loader | +| **RESOLVED** | Green | `#22C55E` | Check circle | +| **VERIFIED** | Green (dark) | `#15803D` | Double check | +| **DECLINED** | Gray | `#6B7280` | X circle | +| **REOPENED** | Red | `#EF4444` | Refresh icon | +| **STALE** | Gray (light) | `#9CA3AF` | Clock icon | + +### 7.6 Score Range Colors + +| Range | Level | Background | Text | +|-------|-------|------------|------| +| 85-100 | Excellent | `#DCFCE7` | `#166534` | +| 75-84 | Good | `#D1FAE5` | `#065F46` | +| 65-74 | Acceptable | `#FEF3C7` | `#92400E` | +| 50-64 | Poor | `#FEE2E2` | `#991B1B` | +| 0-49 | Critical | `#FEE2E2` | `#7F1D1D` | + +--- + +## 8. Filter Components + +### 8.1 Date Range Picker + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ DATE RANGE PICKER SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual: │ +│ ┌────────────────────────────────────────────────────────────┐│ +│ │ Period: [Last 30 days ▼] From: [01/01/2026] To: [01/23/26]││ +│ └────────────────────────────────────────────────────────────┘│ +│ │ +│ Preset Options: │ +│ ├── Today │ +│ ├── Yesterday │ +│ ├── Last 7 days │ +│ ├── Last 30 days (default) │ +│ ├── Last 90 days │ +│ ├── This month │ +│ ├── Last month │ +│ ├── This quarter │ +│ ├── Last quarter │ +│ ├── This year │ +│ ├── Last year │ +│ └── Custom range │ +│ │ +│ Comparison Options: │ +│ ├── Previous period (same length) │ +│ ├── Same period last year │ +│ └── None │ +│ │ +│ Props: │ +│ { │ +│ value: { from: Date, to: Date }, │ +│ onChange: (range) => void, │ +│ presets: PresetOption[], │ +│ comparison?: 'previous' | 'year_ago' | 'none', │ +│ maxRange?: number (days), │ +│ minDate?: Date, │ +│ maxDate?: Date │ +│ } │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 8.2 Domain/Category/Subcode Selector + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ HIERARCHICAL CODE SELECTOR SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual: │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Domain: [All ▼] Category: [All ▼] Subcode: [All ▼] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Cascading Behavior: │ +│ 1. Domain selection filters available categories │ +│ 2. Category selection filters available subcodes │ +│ 3. Subcode selection auto-sets domain and category │ +│ │ +│ Domain Dropdown: │ +│ ┌─────────────────────┐ │ +│ │ ☐ All Domains │ │ +│ │ ☑ O - Offering │ ← Colored chip │ +│ │ ☐ P - People │ │ +│ │ ☑ J - Journey │ │ +│ │ ... │ │ +│ └─────────────────────┘ │ +│ │ +│ Props: │ +│ { │ +│ value: { │ +│ domains: string[], │ +│ categories: string[], │ +│ subcodes: string[] │ +│ }, │ +│ onChange: (selection) => void, │ +│ allowMultiple: boolean, │ +│ showCounts: boolean (show span/issue counts per option) │ +│ } │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 8.3 Valence and Intensity Filters + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ VALENCE/INTENSITY FILTER SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual (Toggle Buttons): │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Valence: [V+] [V-] [V0] [V±] Intensity: [I1] [I2] [I3]│ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ Active states shown with filled background and border │ +│ │ +│ Default: All selected (no filter) │ +│ │ +│ Props: │ +│ { │ +│ valence: ('V+' | 'V-' | 'V0' | 'V±')[], │ +│ intensity: ('I1' | 'I2' | 'I3')[], │ +│ onChange: (filters) => void │ +│ } │ +│ │ +│ Quick Actions: │ +│ ├── "Negative Only" → V- selected │ +│ ├── "Critical Only" → V- + I3 selected │ +│ └── "Clear All" → All selected │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 8.4 Owner/Team Filter + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ OWNER/TEAM FILTER SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual: │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Owner: [All Teams ▼] Individual: [All ▼] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Data Source: B3-owner-routing.yaml teams configuration │ +│ │ +│ Team Options: │ +│ ├── Operations │ +│ ├── HR/Training │ +│ ├── Product │ +│ ├── Engineering │ +│ ├── Facilities │ +│ ├── Finance │ +│ ├── CX Leadership │ +│ └── (custom teams from config) │ +│ │ +│ Individual: Populated based on team selection │ +│ │ +│ Props: │ +│ { │ +│ teams: string[], │ +│ individuals: string[], │ +│ onChange: (filters) => void │ +│ } │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 8.5 Issue State Filter + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ISSUE STATE FILTER SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual (Pill Toggle): │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ [All] [Open] [DET] [ACK] [INP] [RES] [VER] [DEC] [REO] │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ Presets: │ +│ ├── "All": No filter │ +│ ├── "Open": DETECTED, ACKNOWLEDGED, IN_PROGRESS, REOPENED │ +│ ├── "Pending": RESOLVED (awaiting verification) │ +│ └── "Closed": VERIFIED, DECLINED │ +│ │ +│ State pills show count badges │ +│ │ +│ Props: │ +│ { │ +│ selectedStates: IssueState[], │ +│ onChange: (states) => void, │ +│ showCounts: boolean │ +│ } │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 8.6 Comparative Reference Filter + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ COMPARATIVE REFERENCE FILTER SPECIFICATION │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Visual: │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ CR Signal: [All ▼] │ │ +│ │ ├── All (no filter) │ │ +│ │ ├── Has Comparison (CR-B, CR-W, CR-S) │ │ +│ │ ├── Improving (CR-B only) │ │ +│ │ ├── Worsening (CR-W only) │ │ +│ │ ├── Persistent (CR-S only) │ │ +│ │ └── No Comparison (CR-N only) │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ Use Case: Identify improvement opportunities and regressions │ +│ │ +│ Props: │ +│ { │ +│ selected: ('CR-N' | 'CR-B' | 'CR-W' | 'CR-S')[], │ +│ onChange: (cr) => void │ +│ } │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 8.7 Global Filter Bar + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ GLOBAL FILTER BAR LAYOUT │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Desktop (≥1200px): │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ [Date Range ▼] [Domain ▼] [State ▼] [Valence ▼] [Owner ▼] [⚙ More] │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Tablet (768-1199px): │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ [Date Range ▼] [Domain ▼] [State ▼] [+ 3 more filters] │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Mobile (<768px): │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ [Filters (5 active) ▼] ← Opens filter drawer │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Active Filter Pills: │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ Last 30 days × | Domain: O, J × | State: Open × | Valence: V- × | Clear│ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ State Management: │ +│ ├── URL params sync for shareable views │ +│ ├── Local storage for user preferences │ +│ └── Reset to defaults button │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 9. Data Requirements + +### 9.1 API Endpoints + +| Endpoint | Method | Purpose | Dashboard | Refresh | +|----------|--------|---------|-----------|---------| +| `/api/v1/kpi/oei` | GET | Overall Experience Index | Executive | 15 min | +| `/api/v1/kpi/domains` | GET | All domain scores | Executive, Ops | 15 min | +| `/api/v1/kpi/categories/{domain}` | GET | Category breakdown | Operations | 15 min | +| `/api/v1/kpi/trends` | GET | Time-series data | Analytics | 15 min | +| `/api/v1/issues` | GET | Issue list with filters | Operations | 5 min | +| `/api/v1/issues/{id}` | GET | Issue detail | Deep-Dive | On-demand | +| `/api/v1/issues/{id}/history` | GET | State history | Deep-Dive | On-demand | +| `/api/v1/spans` | GET | Span list with filters | Analytics | 15 min | +| `/api/v1/spans/{id}` | GET | Span detail | Deep-Dive | On-demand | +| `/api/v1/reviews/{id}` | GET | Review with spans | Deep-Dive | On-demand | +| `/api/v1/alerts` | GET | Active alerts | All | 5 min | +| `/api/v1/alerts/{id}/acknowledge` | POST | Acknowledge alert | All | — | +| `/api/v1/cr/trends` | GET | CR signal trends | Analytics | 15 min | +| `/api/v1/anomalies` | GET | Detected anomalies | Analytics | 5 min | +| `/api/v1/workload` | GET | Team workload | Operations | 5 min | + +### 9.2 Query Parameters (Common) + +| Parameter | Type | Description | Example | +|-----------|------|-------------|---------| +| `from` | ISO Date | Start date | `2026-01-01` | +| `to` | ISO Date | End date | `2026-01-23` | +| `domains` | String[] | Domain filter | `O,P,J` | +| `categories` | String[] | Category filter | `O1,O2` | +| `subcodes` | String[] | Subcode filter | `O1.01,O1.02` | +| `valence` | String[] | Valence filter | `V-,V±` | +| `intensity` | String[] | Intensity filter | `I2,I3` | +| `state` | String[] | Issue state filter | `DETECTED,IN_PROGRESS` | +| `owner` | String | Team/owner filter | `operations` | +| `limit` | Integer | Page size | `25` | +| `offset` | Integer | Page offset | `0` | +| `sort` | String | Sort field | `priority_score` | +| `order` | String | Sort direction | `desc` | + +### 9.3 WebSocket Events (Real-time) + +| Event | Payload | Trigger | Dashboard | +|-------|---------|---------|-----------| +| `issue.created` | Issue summary | New issue detected | Operations | +| `issue.state_changed` | Issue ID, old/new state | State transition | Operations | +| `alert.triggered` | Alert details | Anomaly detected | All | +| `kpi.updated` | Domain, new value | MV refresh complete | Executive | +| `span.classified` | Span summary | New span processed | Analytics | + +### 9.4 Polling Intervals + +| Dashboard | Data Type | Interval | Method | +|-----------|-----------|----------|--------| +| Executive | KPIs, OEI | 15 min | Polling | +| Executive | Alerts | 5 min | Polling + WebSocket | +| Operations | Issue list | 5 min | Polling | +| Operations | Pipeline | 5 min | Polling | +| Operations | Workload | 5 min | Polling | +| Analytics | Time-series | 15 min | Polling | +| Analytics | Anomalies | 5 min | WebSocket | +| Deep-Dive | All data | On-demand | Request | + +### 9.5 Caching Strategy + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ CACHING ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ LAYER 1: Client-Side (Browser) │ +│ ├── React Query / SWR for request deduplication │ +│ ├── staleTime: 5 minutes (for most queries) │ +│ ├── cacheTime: 30 minutes │ +│ └── refetchOnWindowFocus: true │ +│ │ +│ LAYER 2: API Gateway (Redis) │ +│ ├── KPI aggregations: 5 minute TTL │ +│ ├── Issue counts: 2 minute TTL │ +│ ├── Reference data (domains, categories): 1 hour TTL │ +│ └── User preferences: 24 hour TTL │ +│ │ +│ LAYER 3: Database (PostgreSQL) │ +│ ├── Materialized Views: Refreshed every 5-15 minutes │ +│ │ ├── mv_domain_summary: 15 min │ +│ │ ├── mv_category_breakdown: 15 min │ +│ │ ├── mv_issue_pipeline: 5 min │ +│ │ ├── mv_cr_trends: 15 min │ +│ │ └── mv_daily_volume: 15 min │ +│ └── pg_cron job: REFRESH MATERIALIZED VIEW CONCURRENTLY │ +│ │ +│ Cache Invalidation: │ +│ ├── Issue state change → Invalidate pipeline cache │ +│ ├── New span classified → Invalidate domain/category caches │ +│ └── Alert triggered → Broadcast WebSocket, invalidate alert cache │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 9.6 Data Source Mapping + +| Widget | Primary Table/View | Fallback | Notes | +|--------|-------------------|----------|-------| +| OEI Gauge | `mv_domain_summary` | Computed from `spans` | Prefer MV | +| Domain Radar | `mv_domain_summary` | — | — | +| Domain Cards | `mv_domain_summary` | — | — | +| Issue Pipeline | `mv_issue_pipeline` | `issues` grouped | MV preferred | +| SLA Gauges | `issues` + `issue_state_history` | — | Computed | +| Workload | `issues` + routing config | — | Live query | +| Heatmap | `mv_category_breakdown` | — | — | +| Issue Table | `issues` JOIN `urt_domains` | — | Paginated | +| Time-series | `mv_daily_volume` | `spans` grouped | MV preferred | +| CR Trends | `mv_cr_trends` | `spans` filtered | MV preferred | +| Anomalies | Anomaly detection service | — | Real-time | +| Sankey | `spans` + `issues` + `reviews` | — | Complex query | + +--- + +## 10. User Roles & Permissions + +### 10.1 Role Definitions + +| Role | Description | Default Users | +|------|-------------|---------------| +| **executive** | Strategic overview, read-only | C-Suite, Directors | +| **operations** | Issue management, full write | Managers, Team Leads | +| **analyst** | Deep analytics, export | Data Analysts, BI Team | +| **admin** | Full access, configuration | System Administrators | +| **viewer** | Read-only basic access | General staff | + +### 10.2 Permission Matrix + +| Feature | Viewer | Executive | Operations | Analyst | Admin | +|---------|--------|-----------|------------|---------|-------| +| View Executive Dashboard | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Operations Dashboard | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Analytics Dashboard | — | ✓ | ✓ | ✓ | ✓ | +| View Deep-Dive | — | ✓ | ✓ | ✓ | ✓ | +| Acknowledge Issues | — | — | ✓ | — | ✓ | +| Change Issue State | — | — | ✓ | — | ✓ | +| Assign Issues | — | — | ✓ | — | ✓ | +| Add Issue Notes | — | ✓ | ✓ | ✓ | ✓ | +| Acknowledge Alerts | — | ✓ | ✓ | ✓ | ✓ | +| Create Issues from Alerts | — | — | ✓ | — | ✓ | +| Export Data | — | ✓ | ✓ | ✓ | ✓ | +| Configure Alerts | — | — | — | — | ✓ | +| Manage Users | — | — | — | — | ✓ | +| Configure Routing | — | — | — | — | ✓ | +| View Audit Logs | — | — | — | ✓ | ✓ | + +### 10.3 Dashboard Access by Role + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ ROLE-BASED DASHBOARD ACCESS │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ VIEWER │ +│ ├── Executive Dashboard (read-only) │ +│ └── Operations Dashboard (read-only, no actions) │ +│ │ +│ EXECUTIVE │ +│ ├── Executive Dashboard (default landing) │ +│ ├── Operations Dashboard (read, add notes) │ +│ ├── Analytics Dashboard (read, export) │ +│ └── Deep-Dive Views (read) │ +│ │ +│ OPERATIONS │ +│ ├── Operations Dashboard (default landing, full control) │ +│ ├── Executive Dashboard (read) │ +│ ├── Analytics Dashboard (read) │ +│ └── Deep-Dive Views (read, manage issues) │ +│ │ +│ ANALYST │ +│ ├── Analytics Dashboard (default landing, full features) │ +│ ├── Executive Dashboard (read) │ +│ ├── Operations Dashboard (read) │ +│ ├── Deep-Dive Views (read, add notes) │ +│ └── Custom Report Builder (if available) │ +│ │ +│ ADMIN │ +│ ├── All dashboards with full access │ +│ ├── Settings & Configuration │ +│ ├── User Management │ +│ └── Audit Logs │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 10.4 Data Filtering by Role + +| Role | Data Scope | Rationale | +|------|------------|-----------| +| **viewer** | All domains, no PII | General awareness | +| **executive** | All domains, aggregate only | Strategic overview | +| **operations** | All domains, full detail | Issue management | +| **analyst** | All domains, full detail + history | Deep analysis | +| **admin** | All data including system logs | Full visibility | + +### 10.5 Team-Based Filtering + +Operations users may be restricted to issues owned by their team: + +``` +IF user.role == 'operations' AND user.teamScope != 'all': + issues = issues.filter(owner_team IN user.teams) + alerts = alerts.filter(relevant_team IN user.teams) +``` + +--- + +## 11. Responsive Design + +### 11.1 Breakpoints + +| Breakpoint | Width | Layout | Target Devices | +|------------|-------|--------|----------------| +| **xs** | <576px | Single column | Mobile portrait | +| **sm** | 576-767px | Single column | Mobile landscape | +| **md** | 768-1199px | 2 columns | Tablet | +| **lg** | 1200-1439px | 3 columns | Small desktop | +| **xl** | ≥1440px | Full layout | Desktop, Large monitors | + +### 11.2 Executive Dashboard Responsive Layouts + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ EXECUTIVE DASHBOARD - RESPONSIVE LAYOUTS │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ XL (≥1440px): Full 3-Column Layout │ +│ ┌──────────────┬──────────────┬──────────────┐ │ +│ │ OEI Gauge │ Radar Chart │ Alerts │ │ +│ ├──────────────┴──────────────┴──────────────┤ │ +│ │ 7 Domain Score Cards (row) │ │ +│ ├────────────────────────────────────────────┤ │ +│ │ 12-Week Trend Line │ │ +│ ├──────────────────────┬─────────────────────┤ │ +│ │ Composite Indices │ Quick Stats │ │ +│ └──────────────────────┴─────────────────────┘ │ +│ │ +│ MD (768-1199px): 2-Column Layout │ +│ ┌──────────────┬──────────────┐ │ +│ │ OEI Gauge │ Radar Chart │ │ +│ ├──────────────┴──────────────┤ │ +│ │ Domain Cards (2x4 grid) │ │ +│ ├──────────────┬──────────────┤ │ +│ │ Alerts │ Trends │ │ +│ ├──────────────┴──────────────┤ │ +│ │ Trend Line │ │ +│ └─────────────────────────────┘ │ +│ │ +│ SM/XS (<768px): Single Column, Stacked │ +│ ┌─────────────────────────────┐ │ +│ │ OEI Gauge (large) │ │ +│ ├─────────────────────────────┤ │ +│ │ Domain Cards (carousel) │ ← Swipeable │ +│ ├─────────────────────────────┤ │ +│ │ Alerts (collapsible) │ │ +│ ├─────────────────────────────┤ │ +│ │ Trend Line (scrollable) │ │ +│ └─────────────────────────────┘ │ +│ Note: Radar chart hidden on mobile, replaced by domain cards │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 11.3 Operations Dashboard Responsive Layouts + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ OPERATIONS DASHBOARD - RESPONSIVE LAYOUTS │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ XL (≥1440px): Full Layout │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ Issue Pipeline (horizontal) │ │ +│ ├───────────────────────────────┬─────────────────────────────────────────┤ │ +│ │ SLA Gauges (3 stack) │ Owner Workload (bar chart) │ │ +│ ├───────────────────────────────┴─────────────────────────────────────────┤ │ +│ │ Category Heatmap (7x4 grid) │ │ +│ ├─────────────────────────────────────────────────────────────────────────┤ │ +│ │ Issue Table (full width) │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ MD (768-1199px): Stacked Sections │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ Issue Pipeline (compact) │ │ +│ ├─────────────────────────────────────────────────────────────────────────┤ │ +│ │ SLA Gauges │ Owner Workload │ │ +│ ├─────────────────────────────────────────────────────────────────────────┤ │ +│ │ Category Heatmap (scrollable) │ │ +│ ├─────────────────────────────────────────────────────────────────────────┤ │ +│ │ Issue Table (horizontal scroll) │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ SM/XS (<768px): Mobile-First │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ Pipeline Summary (counts only, no visualization) │ │ +│ ├─────────────────────────────────────────────────────────────────────────┤ │ +│ │ SLA Compliance (single combined gauge) │ │ +│ ├─────────────────────────────────────────────────────────────────────────┤ │ +│ │ Issue Cards (list view, swipe actions) │ │ +│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ ISSUE-0142 │ O2.05 │ INP │ ████ 5.60 │ 3d │ [→ Swipe for actions]│ │ │ +│ │ └───────────────────────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 11.4 Touch Interactions (Mobile) + +| Gesture | Action | Context | +|---------|--------|---------| +| **Tap** | Select / Open | All interactive elements | +| **Long Press** | Context menu | Issue cards, spans | +| **Swipe Left** | Quick actions (Ack, Assign) | Issue cards | +| **Swipe Right** | Dismiss / Archive | Alerts | +| **Pinch Zoom** | Zoom charts | Time-series, Sankey | +| **Pull Down** | Refresh data | All dashboards | +| **Two-finger Pan** | Pan zoomed charts | Analytics charts | + +--- + +## 12. Implementation Notes + +### 12.1 Accessibility Requirements + +| Requirement | Implementation | +|-------------|----------------| +| **Keyboard Navigation** | All interactive elements focusable, logical tab order | +| **Screen Reader** | ARIA labels, roles, live regions for updates | +| **Color Contrast** | WCAG 2.1 AA minimum (4.5:1 for text) | +| **Focus Indicators** | Visible focus rings on all focusable elements | +| **Skip Links** | Skip to main content, skip to navigation | +| **Alternative Text** | Descriptive alt text for all charts/images | +| **Reduced Motion** | Respect `prefers-reduced-motion` media query | + +### 12.2 Performance Targets + +| Metric | Target | Measurement | +|--------|--------|-------------| +| **First Contentful Paint** | <1.5s | Lighthouse | +| **Time to Interactive** | <3.0s | Lighthouse | +| **Largest Contentful Paint** | <2.5s | Lighthouse | +| **API Response Time** | <200ms (p95) | Server metrics | +| **Chart Render Time** | <100ms | Performance API | +| **Bundle Size** | <500KB (gzipped) | Webpack analyzer | + +### 12.3 Error Handling + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ ERROR HANDLING PATTERNS │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ API Errors: │ +│ ├── 4xx: Show user-friendly message, offer retry │ +│ ├── 5xx: Show error boundary, log to monitoring │ +│ └── Timeout: Show "Taking longer than expected", auto-retry │ +│ │ +│ Widget Errors: │ +│ ├── Data missing: Show placeholder with "No data available" │ +│ ├── Parse error: Show fallback component, log error │ +│ └── Render error: Error boundary catches, shows widget skeleton │ +│ │ +│ Real-time Errors: │ +│ ├── WebSocket disconnect: Auto-reconnect with exponential backoff │ +│ ├── Missed events: Request full refresh on reconnect │ +│ └── Stale data: Show "Data may be outdated" indicator │ +│ │ +│ User Feedback: │ +│ ├── Toast notifications for transient errors │ +│ ├── Inline error messages for form validation │ +│ └── Full-page error for critical failures │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 12.4 Testing Strategy + +| Test Type | Coverage | Tools | +|-----------|----------|-------| +| **Unit Tests** | Widget components, utilities | Jest, React Testing Library | +| **Integration Tests** | API interactions, state management | MSW, Cypress Component | +| **E2E Tests** | Critical user flows | Cypress, Playwright | +| **Visual Regression** | UI consistency | Percy, Chromatic | +| **Accessibility Tests** | WCAG compliance | axe-core, Pa11y | +| **Performance Tests** | Load time, render performance | Lighthouse CI | + +### 12.5 Deployment Considerations + +| Aspect | Recommendation | +|--------|----------------| +| **CDN** | Static assets via CloudFront/Cloudflare | +| **API** | Load-balanced behind API gateway | +| **Database** | Read replicas for dashboard queries | +| **Caching** | Redis cluster for API response caching | +| **Monitoring** | DataDog/New Relic for APM | +| **Logging** | Structured JSON logs to centralized system | +| **Feature Flags** | LaunchDarkly for gradual rollout | + +### 12.6 Future Enhancements + +| Enhancement | Priority | Description | +|-------------|----------|-------------| +| **Custom Dashboards** | Medium | User-configurable widget layouts | +| **Report Builder** | Medium | Drag-and-drop report creation | +| **Scheduled Reports** | Medium | Email/Slack delivery of snapshots | +| **Embedding** | Low | Embed widgets in external tools | +| **Mobile App** | Low | Native iOS/Android app | +| **AI Insights** | High | Automated insight generation | +| **Predictive Analytics** | High | Issue prediction, churn risk | + +--- + +## Document Control + +| Field | Value | +|-------|-------| +| **Document** | D1 - Dashboard Specification | +| **Version** | 1.0 | +| **Status** | Production Ready | +| **Date** | 2026-01-23 | +| **Author** | URT Working Group | +| **Part Of** | Track D: Integration Layer | + +--- + +## Related Documents + +| Document | Purpose | Status | +|----------|---------|--------| +| **B2-database-schema.sql** | Database tables and views | Complete | +| **B3-owner-routing.md** | Team routing configuration | Complete | +| **C1-Issue-Lifecycle-Framework.md** | Issue state management | Complete | +| **C2-KPI-Mapping-Guide.md** | KPI calculations and alerts | Complete | +| **D2-API-Specification** | API endpoint details | Planned | +| **D3-Integration-Guide** | Third-party integrations | Planned | + +--- + +*End of D1: Dashboard Specification*