fix(triage): one preamble on the follow-up + chip-matching category labels (PP-4847) (#1317)

mauricecarrier7 · t · web-flow · commit 099bf2c41305 · 2026-07-21T16:50:52.000-04:00
Two cosmetic defects from a regression sim-drive:

1. Doubled preamble. The reducer always prepends "Before I file this — " to the
   escalation follow-up, but 3 of 7 corpus prompts carried their OWN preamble
   ("Before I send this to support —", "Quick question before I file this —",
   "Before I escalate —"), so the patron saw two. Standardize: the reducer owns
   the single canonical preamble; the corpus prompts are now bare questions.
   A new corpus lint (EscalationPreambleTests) loads the shipped catalog and
   fails if any prompt reintroduces a self-preamble.

2. Category label mismatch. The ticket-preview "Category" rendered
   draft.category.rawValue.capitalized → "Signin" (no space) and surfaced the
   internal `reader` case as "Reader", neither matching the chip the patron
   tapped. Add KBCategory.displayName (audiobook→Audiobook, reader→Reading,
   signin→Sign in, …) and route BOTH the preview and the chips through it, so
   the two can never drift again.

Verified: TriageBotCore 22/22 green (new KBCategoryDisplayNameTests +
EscalationPreambleTests); catalog.json re-validated. UI label wiring
(#if canImport(UIKit)) is exercised by the iOS build in CI.

**Scope:** category display label + the follow-up preamble wording/corpus only.

**Not done:** PP-4846 (intermittent stuck-Send race) — separate branch,
repro-first.

**Deferred:** none.

Co-authored-by: t &lt;t@t.io&gt;
diff --git a/.forgeos/intent/pp-4847-triage-preamble-labels.md b/.forgeos/intent/pp-4847-triage-preamble-labels.md
@@ -0,0 +1,46 @@
+---
+name: pp-4847-triage-preamble-labels
+created: 2026-07-21
+author: claude-opus-4-8
+---
+
+**ADR refs:** none recorded for the triage-bot area.
+
+## Context
+
+Two cosmetic triage-bot defects from a regression sim-drive (PP-4847):
+1. **Doubled preamble.** The reducer always prepends "Before I file this — " to
+   the escalation follow-up question, but 3 of 7 corpus prompts carry their OWN
+   preamble ("Before I send this to support —", "Quick question before I file
+   this —", "Before I escalate —"), so the patron sees two.
+2. **Category label mismatch.** The ticket-preview "Category" field renders
+   `draft.category.rawValue.capitalized` — so `signin` → "Signin" (no space) and
+   `reader` → "Reader", neither matching the chip the patron tapped ("Sign in",
+   "Reading").
+
+## Claims
+
+- adds public computed property `displayName` to `KBCategory` (patron-facing
+  label matching the category-chip wording)
+- migrates `TicketPreviewCard` category row from `rawValue.capitalized` to
+  `category.displayName`
+- migrates `CategoryChipsView` chip labels to `category.displayName` (single
+  source of truth so chip and preview can never drift again)
+- removes the self-preamble from the 3 corpus `escalationFollowUp.prompt`s in
+  catalog.json so the reducer owns the single canonical preamble
+
+## Anti-claims
+
+- does NOT change the reducer's preamble wording or the escalation flow
+- does NOT change any category `rawValue` (JSON/telemetry keys unchanged)
+- does NOT touch redaction, send-consent, or ticket-submission logic
+- does NOT touch any auth / DRM / borrow / download path
+
+## Files in scope
+
+- Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Models/KBEntry.swift
+- Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Resources/catalog.json
+- Palace/Packages/PalaceTriageBot/Sources/TriageBotUI/TicketPreviewCard.swift
+- Palace/Packages/PalaceTriageBot/Sources/TriageBotUI/CategoryChipsView.swift
+- Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/KBCategoryDisplayNameTests.swift
+- Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/EscalationPreambleTests.swift
diff --git a/Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Models/KBEntry.swift b/Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Models/KBEntry.swift
@@ -31,6 +31,21 @@ public enum KBCategory: String, Codable, Sendable, CaseIterable {
     case download
     case library
     case other
+
+    /// Patron-facing label, matching the category-chip wording exactly so the
+    /// ticket-preview "Category" field reads the same as the chip the patron
+    /// tapped (PP-4847). `rawValue.capitalized` produced "Signin" (no space) and
+    /// surfaced the internal `reader` case as "Reader" instead of "Reading".
+    public var displayName: String {
+        switch self {
+        case .audiobook: return "Audiobook"
+        case .reader:    return "Reading"
+        case .signin:    return "Sign in"
+        case .download:  return "Download"
+        case .library:   return "Library"
+        case .other:     return "Other"
+        }
+    }
 }
 
 /// What KIND of entry this is — the axis that lets general-help content live
diff --git a/Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Resources/catalog.json b/Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Resources/catalog.json
@@ -105,7 +105,7 @@
         ]
       },
       "escalation_follow_up": {
-        "prompt": "Before I send this to support — which audiobook title is doing this? It helps them spot patterns across publishers.",
+        "prompt": "Which audiobook title is doing this? It helps them spot patterns across publishers.",
         "placeholder": "e.g. The Midnight Library by Matt Haig",
         "diagnostic": "audiobook.followup_title_captured"
       },
@@ -326,7 +326,7 @@
         ]
       },
       "escalation_follow_up": {
-        "prompt": "Quick question before I file this — which library are you trying to add? (City, county, or system name is fine.)",
+        "prompt": "Which library are you trying to add? (City, county, or system name is fine.)",
         "placeholder": "e.g. Brooklyn Public Library",
         "diagnostic": "library.followup_name_captured"
       },
@@ -395,7 +395,7 @@
         "jira": "PP-4430"
       },
       "escalation_follow_up": {
-        "prompt": "Before I escalate — what car model + year are you using, and is it wired CarPlay or wireless? Helps us repro on the same setup.",
+        "prompt": "What car model + year are you using, and is it wired CarPlay or wireless? Helps us repro on the same setup.",
         "placeholder": "e.g. 2021 Honda Civic, wired",
         "diagnostic": "carplay.followup_car_captured"
       },
diff --git a/Palace/Packages/PalaceTriageBot/Sources/TriageBotUI/CategoryChipsView.swift b/Palace/Packages/PalaceTriageBot/Sources/TriageBotUI/CategoryChipsView.swift
@@ -14,13 +14,16 @@ struct CategoryChipsView: View {
 
     @Environment(\.dynamicTypeSize) private var dynamicTypeSize
 
-    private let categories: [(KBCategory, String, String)] = [
-        (.audiobook, "🎧", "Audiobook"),
-        (.reader, "📖", "Reading"),
-        (.signin, "🔑", "Sign in"),
-        (.download, "⬇️", "Download"),
-        (.library, "📚", "Library"),
-        (.other, "💬", "Other")
+    // Emoji per category; the label comes from `KBCategory.displayName` so the
+    // chip wording and the ticket-preview "Category" field share one source of
+    // truth and can't drift (PP-4847).
+    private let categories: [(KBCategory, String)] = [
+        (.audiobook, "🎧"),
+        (.reader, "📖"),
+        (.signin, "🔑"),
+        (.download, "⬇️"),
+        (.library, "📚"),
+        (.other, "💬")
     ]
 
     var body: some View {
@@ -31,8 +34,8 @@ struct CategoryChipsView: View {
         // compact adaptive grid at normal sizes.
         if dynamicTypeSize.isAccessibilitySize {
             VStack(alignment: .leading, spacing: 8) {
-                ForEach(categories, id: \.0) { category, emoji, label in
-                    chip(category, emoji, label)
+                ForEach(categories, id: \.0) { category, emoji in
+                    chip(category, emoji, category.displayName)
                 }
             }
         } else {
@@ -41,8 +44,8 @@ struct CategoryChipsView: View {
             // / "Download" onto two lines. (Re-land of the pill-label fix.)
             LazyVGrid(columns: [GridItem(.adaptive(minimum: 155), spacing: 8)],
                       alignment: .leading, spacing: 8) {
-                ForEach(categories, id: \.0) { category, emoji, label in
-                    chip(category, emoji, label)
+                ForEach(categories, id: \.0) { category, emoji in
+                    chip(category, emoji, category.displayName)
                 }
             }
         }
diff --git a/Palace/Packages/PalaceTriageBot/Sources/TriageBotUI/TicketPreviewCard.swift b/Palace/Packages/PalaceTriageBot/Sources/TriageBotUI/TicketPreviewCard.swift
@@ -54,7 +54,7 @@ struct TicketPreviewCard: View {
             }
 
             VStack(alignment: .leading, spacing: 6) {
-                staticRow("Category", value: draft.category.rawValue.capitalized)
+                staticRow("Category", value: draft.category.displayName)
                 staticRow("App", value: "\(draft.context.appVersion) (\(draft.context.appBuild))")
                 staticRow("Device", value: "\(draft.context.deviceModel) · iOS \(draft.context.osVersion)")
 
diff --git a/Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/EscalationPreambleTests.swift b/Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/EscalationPreambleTests.swift
@@ -0,0 +1,59 @@
+import XCTest
+@testable import TriageBotCore
+
+/// PP-4847: the reducer owns a single "Before I file this —" preamble on the
+/// escalation follow-up question. Corpus prompts must therefore be bare
+/// questions — a prompt that carries its own preamble renders doubled
+/// ("Before I file this — Before I send this to support — which title…").
+final class EscalationPreambleTests: XCTestCase {
+
+    /// Corpus lint: no follow-up prompt may carry its own "Before I file/send/
+    /// escalate" preamble. Loads the real shipped catalog.
+    func testCorpusFollowUpPrompts_carryNoOwnPreamble() throws {
+        let entries = try BundledCatalogSource.loadCatalogSync().entries
+        let banned = ["before i file", "before i send", "before i escalate"]
+        var offenders: [String] = []
+        for entry in entries {
+            guard let prompt = entry.escalationFollowUp?.prompt else { continue }
+            let lower = prompt.lowercased()
+            if banned.contains(where: { lower.contains($0) }) {
+                offenders.append("\(entry.id): \(prompt)")
+            }
+        }
+        XCTAssertTrue(offenders.isEmpty,
+            "these follow-up prompts carry their own preamble; the reducer adds one, so they render doubled: \(offenders)")
+    }
+
+    private func drive(_ r: ConversationReducer, category: KBCategory, text: String) -> ConversationState {
+        var (state, _) = r.reduce(state: ConversationState(), action: .start)
+        (state, _) = r.reduce(state: state, action: .userTappedCategory(category))
+        (state, _) = r.reduce(state: state, action: .inputChanged(text))
+        return r.reduce(state: state, action: .userSubmittedDescription).0
+    }
+
+    /// The reducer renders exactly one preamble, sitting directly in front of the
+    /// bare-question prompt.
+    func testReducer_followUpMessage_hasExactlyOnePreamble() {
+        let entries = [KBEntry(id: "KI-FU", category: .other, status: .open,
+                               symptomKeywords: ["frobnicate widget"],
+                               userFacingWorkaround: "Try turning it off and on again please.",
+                               escalationFollowUp: KBEscalationFollowUp(prompt: "Which widget model is it?"),
+                               confidenceThreshold: 0.1)]
+        let r = ConversationReducer(knowledgeBase: KnowledgeBase(
+            catalog: KBCatalog(version: "test", updatedAt: "2026-07-20", entries: entries)))
+        let state = drive(r, category: .other, text: "my frobnicate widget is broken")
+
+        let followUp = state.messages.compactMap { message -> String? in
+            if case .text(let t) = message.kind, t.contains("Which widget model is it?") { return t }
+            return nil
+        }.first
+
+        guard let text = followUp else {
+            return XCTFail("expected a follow-up message containing the prompt; got \(state.messages)")
+        }
+        let preambleCount = text.components(separatedBy: "Before I file this —").count - 1
+        XCTAssertEqual(preambleCount, 1, "expected exactly one preamble, got \(preambleCount): \(text)")
+        XCTAssertTrue(text.contains("Before I file this — Which widget model is it?"),
+                      "the single preamble must sit directly in front of the bare question: \(text)")
+    }
+}
diff --git a/Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/KBCategoryDisplayNameTests.swift b/Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/KBCategoryDisplayNameTests.swift
@@ -0,0 +1,32 @@
+import XCTest
+@testable import TriageBotCore
+
+/// PP-4847: the ticket-preview "Category" field must read like the chip the
+/// patron tapped, not `rawValue.capitalized` (which produced "Signin" and
+/// surfaced the internal `reader` case as "Reader" instead of "Reading").
+final class KBCategoryDisplayNameTests: XCTestCase {
+
+    func testDisplayName_matchesChipWording() {
+        XCTAssertEqual(KBCategory.audiobook.displayName, "Audiobook")
+        XCTAssertEqual(KBCategory.reader.displayName, "Reading")
+        XCTAssertEqual(KBCategory.signin.displayName, "Sign in")
+        XCTAssertEqual(KBCategory.download.displayName, "Download")
+        XCTAssertEqual(KBCategory.library.displayName, "Library")
+        XCTAssertEqual(KBCategory.other.displayName, "Other")
+    }
+
+    /// The two cases that were actually wrong under `rawValue.capitalized`. A
+    /// regression back to that would make these equal again — so assert they differ.
+    func testDisplayName_signinAndReader_differFromRawValueCapitalized() {
+        XCTAssertNotEqual(KBCategory.signin.displayName, KBCategory.signin.rawValue.capitalized,
+                          "'signin'.capitalized == 'Signin' (no space) — displayName must fix it")
+        XCTAssertNotEqual(KBCategory.reader.displayName, KBCategory.reader.rawValue.capitalized,
+                          "'reader'.capitalized == 'Reader' — the chip says 'Reading'")
+    }
+
+    func testDisplayName_everyCaseNonEmpty() {
+        for category in KBCategory.allCases {
+            XCTAssertFalse(category.displayName.isEmpty, "\(category) must have a display name")
+        }
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ struct TicketPreviewCard: View {`
`54`	`54`	`}`
`55`	`55`
`56`	`56`	`VStack(alignment: .leading, spacing: 6) {`
`57`		`- staticRow("Category", value: draft.category.rawValue.capitalized)`
	`57`	`+ staticRow("Category", value: draft.category.displayName)`
`58`	`58`	`staticRow("App", value: "\(draft.context.appVersion) (\(draft.context.appBuild))")`
`59`	`59`	`staticRow("Device", value: "\(draft.context.deviceModel) · iOS \(draft.context.osVersion)")`
`60`	`60`