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>
1205 lines
66 KiB
Markdown
1205 lines
66 KiB
Markdown
# 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*
|