# 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*