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>
66 KiB
66 KiB
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 multiplierdecay(t)= Time decay functionrecurrence_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
{
"$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
{
"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:
- New span aggregated to issue
- Daily decay recalculation (batch)
- CR marker detected (CR-S, CR-W, CR-B)
- Issue reopened
- 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