3eda9bdbfa
Universal Review Taxonomy v5.1 implementation with: - Track A (Training): A1 Quickstart, A2 QA Protocol, A3 Calibration Set, A4 Full Manual - Track B (Engineering): B1 Code Registry, B2 Database Schema, B3 Owner Routing, B4 API Contract - Track C (Analytics): C1 Issue Lifecycle, C2 KPI Mapping Guide - Track D (Integration): D1 Dashboard Specification Covers 7 domains, 28 categories, 138 subcodes, 16 causal codes, and 7 metadata dimensions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1997 lines
86 KiB
Markdown
1997 lines
86 KiB
Markdown
# 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* |