# 1. AGENT OPPORTUNITY RECONSTRUCTION | Element | Content | Confidence | |---|---|---| | **PRIMARY USER** | Support agents/leads (recipients of escalation quality) and engineering on-call/teams (recipients of the brief) | HIGHLY LIKELY | | **PROBLEM** | Unresolved tickets that actually need engineering aren't consistently identified, evidenced, or routed to the right team | CONFIRMED | | **TRIGGER** | A ticket remains unresolved and/or is updated in Zendesk | HIGHLY LIKELY (exact threshold/timing rule not given — UNKNOWN) | | **DESIRED OUTCOME** | Correctly routed, evidence-backed escalation brief delivered to the right engineering team, with tracked follow-up | CONFIRMED | | **INPUTS** | Zendesk ticket + history, internal KB articles, (implicitly) product-area taxonomy | CONFIRMED / PLAUSIBLE for taxonomy detail | | **OBSERVABLE STATE** | Ticket status/age, prior escalation status, Jira issue status, Slack thread status | HIGHLY LIKELY | | **DECISIONS** | (a) Escalate or not, (b) which engineering team/product area, (c) what evidence is relevant, (d) whether a customer commitment requires human approval | CONFIRMED | | **ACTIONS** | Gather evidence, draft brief, create/route Jira issue, post to Slack, monitor for response, remind/escalate on silence | CONFIRMED | | **TOOLS/SYSTEMS** | Zendesk, Slack, Jira, internal KB | CONFIRMED (availability of API scopes — UNKNOWN) | | **HUMAN PARTICIPANTS** | Support agent (ticket owner), an approver for consequential customer commitments, engineering team as recipient | HIGHLY LIKELY | | **TIME HORIZON** | Multi-day, since "ticket state may change over several days" | CONFIRMED | | **COMPLETION CONDITION** | Escalation acknowledged/resolved by engineering, or ticket resolved without needing escalation | HIGHLY LIKELY | | **HIGH-IMPACT ACTIONS** | Refunds, account changes, production changes — explicitly excluded from autonomy | CONFIRMED | | **UNKNOWNS** | Escalation threshold rules, product-area→team mapping logic, ticket volume/concurrency, API scopes/rate limits, SLA for engineering response, whether a human must approve *every* escalation or only customer-facing commitments | UNKNOWN | **Classification:** This is an **AGENTIC WORKFLOW**, not a full autonomous multi-agent system, a copilot, or a single model call. It requires multi-step tool use, judgment (is this really an engineering issue? which team?), and state that persists across days — that rules out a single model call or pure copilot. But the control flow is largely a bounded sequence per ticket (observe → decide → act → track), which does **not** require open-ended multi-agent autonomy. Where deterministic logic can do the job (e.g., checking whether a Jira issue already exists for a ticket), it should — not every step needs an LLM call. --- # 2. WORKFLOW & CONTROL-FLOW MAP ``` TRIGGER (Zendesk ticket created/updated, unresolved beyond threshold — CONFIRMED trigger source, UNKNOWN threshold) → OBSERVE (fetch ticket + full history from Zendesk; retrieve related KB articles; check for existing Jira escalation) → INTERPRET (does this look like an engineering issue vs. a support-resolvable one? what product area?) → DECIDE (escalate / hold / resolve-with-KB; select target team) → ACT - draft evidence-backed brief - [HUMAN GATE if brief contains a customer commitment] - create/route Jira issue - post Slack notification to engineering channel → VERIFY (Jira issue exists, Slack post delivered, no duplicate escalation) → CONTINUE (durable state: wait for engineering response, days-long) → COMPLETE / ESCALATE (engineering responds → close loop; no response by SLA → remind or escalate to human) ``` - **SEQUENTIAL:** evidence-gather → decide → draft → route (each depends on the previous) - **PARALLEL:** ticket-history fetch and KB retrieval can run concurrently — PLAUSIBLE optimization, not required for correctness - **LONG-RUNNING:** post-escalation tracking (days) — CONFIRMED requirement - **RECURRING:** polling/checking for stale unresolved tickets and stale escalations — HIGHLY LIKELY needed even if primary trigger is event-based, since Zendesk webhooks can be missed - **EXCEPTION PATHS:** ambiguous product area → human routing decision; insufficient evidence → hold and request more info; likely-duplicate escalation → suppress - **HUMAN GATES:** required before any customer-facing commitment (CONFIRMED). Whether routine engineering routing itself needs approval is UNKNOWN — treated below as autonomous-with-notification, since routing to engineering is reversible and low-impact, unlike promising a refund. - **EXTERNAL WAIT STATES:** waiting on engineering response in Jira/Slack — CONFIRMED, drives the durable-state requirement - **RETRY POINTS:** any Zendesk/Slack/Jira API call - **COMPLETION STATES:** resolved-without-escalation, escalated-and-resolved, escalated-and-abandoned (SLA breach → human escalation) No agent-style reasoning loop is needed for the mechanical parts of this flow (posting to Slack, creating a Jira issue, checking status) — those are deterministic tool calls. The LLM's job is narrower: judging escalation-worthiness, selecting the team, and writing the brief. --- # 3. ARCHITECTURAL FORCES | Force | Evidence | Architectural Consequence | Confidence | |---|---|---|---| | **State duration** | "Ticket state may change over several days" | Requires durable, externally persisted state per ticket, not in-memory/session state | CONFIRMED | | **Tool complexity** | 4 systems (Zendesk, Slack, Jira, KB), each with read and/or write ops | Needs a tool gateway layer with per-tool error handling, not raw ad hoc calls | HIGHLY LIKELY | | **Decision complexity** | "Identify when engineering involvement is likely needed" + team routing by product area | Nontrivial judgment step — justifies an LLM-based classifier/decision step, not a static rule table alone | HIGHLY LIKELY | | **Action consequence** | Explicit exclusion of refunds/account/production changes; approval required for "high-impact customer commitments" | Two-tier autonomy: routine internal actions (Jira/Slack) can be autonomous; customer-facing commitments require a human gate | CONFIRMED | | **Traceability** | "Reliability is more important than maximum autonomy," evidence-backed brief required | Every escalation must carry an audit trail (what evidence, why this team, who approved what) | CONFIRMED | | **Event frequency** | Ticket monitoring over an unspecified but presumably ongoing volume | Needs event-driven triggering, not a single-run script | HIGHLY LIKELY | | **Reliability requirements** | "Reliability and traceability matter more than maximum autonomy" (explicit) | Favors deterministic control flow with LLM used at specific judgment points, bounded retries, explicit failure states — not open-ended autonomous looping | CONFIRMED | | **Need for specialization** | Single coherent responsibility chain (evidence → decision → brief → routing → tracking) | Does not clearly require multiple specialized agents; a single tool-using worker with clear phases is sufficient — MULTI-AGENT SPECIALIZATION IS NOT STRONGLY SUPPORTED | PLAUSIBLE (weighs against supervisor/worker) | | **Parallelism** | No evidence of need for concurrent independent workstreams within one ticket | Low — parallelism only helps at the retrieval sub-step, not architecturally significant | PLAUSIBLE | | **Human oversight** | Explicit approval requirement for consequential actions | Human-approval gate is a hard requirement, not optional | CONFIRMED | | **Recovery requirements** | Multi-day external wait states, tool calls to 3rd-party systems | Needs explicit retry/recovery for tool failures and for "engineering never responded" | HIGHLY LIKELY | | **Latency sensitivity** | Not stated | UNKNOWN — likely low sensitivity given multi-day horizon, but not confirmed | --- # 4. MINIMUM REQUIRED ARCHITECTURE | Capability | Needed? | Justification | |---|---|---| | Single agent (tool-use worker) | **YES** | Core per-ticket judgment + drafting + tool orchestration | | Router | **YES (lightweight)** | Product-area → engineering team mapping; can be rule-based augmented by LLM classification for ambiguous cases — does not require a full "supervisor" architecture | | Planner | NO | Workflow is a fixed sequence (observe→decide→act→track), not open-ended multi-step planning | | Supervisor + specialized workers | **NO (rejected — see Stage 7)** | No confirmed need for multiple concurrent specialized agents; a single worker with distinct phases covers the requirement | | Evaluator / verification step | **CONDITIONAL** | A lightweight "evidence-grounding check" before sending the brief reduces hallucination risk and supports the traceability requirement — justified, but should be a bounded check, not an open reflection loop | | Retrieval | **YES** | KB + ticket history lookup is core to "evidence-backed" | | Tool gateway | **YES** | Zendesk/Slack/Jira integration surface | | Durable state | **YES** | Explicit multi-day requirement | | Event triggers | **YES** | Ticket monitoring is inherently event-driven, with a recurring poll as a backstop | | Human approval gate | **YES** | Explicit requirement for consequential customer commitments | | Memory (long-term, cross-ticket) | **NOT CONFIRMED** | No evidence of a need for learning across tickets; only per-ticket durable state is required | **Conclusion:** The minimum architecture is a **single event-driven, tool-using agent operating over durable per-ticket state**, with a lightweight routing/classification step, a bounded evidence-verification check, and a human-approval gate for consequential actions. A full supervisor/multi-worker architecture is not currently justified. --- # 5. PATTERN CANDIDATE MATRIX | Pattern | Family | Source | |---|---|---| | Event-driven orchestration | Control | Derived + user-referenced | | Sequential workflow / state machine | Control | Derived | | Tool-use agent | Tools | User-referenced | | Tool gateway | Tools | Derived | | Retrieval-augmented context | Knowledge | Derived | | Working-state store (durable state) | Knowledge | User-referenced | | Human approval gate | Human control | User-referenced | | Verification / lightweight reflection (pre-send evidence check) | Reasoning | Derived (weak form of user-referenced "reflection") | | Supervisor–worker | Multi-agent | User-referenced | | Idempotent execution / duplicate-escalation suppression | Reliability | Derived | | Retry with bounds | Reliability | Derived | | Dead-letter / unresolved-task handling (SLA breach → human) | Reliability | Derived | --- # 6. PATTERN FIT / REJECTION ANALYSIS **Tool-use agent** - Problem solved: performing reads/writes across Zendesk, Jira, Slack, KB from LLM judgment - Requirement mapped: TOOLS/SYSTEMS, ACTIONS - Evidence: CONFIRMED (four named systems, explicit actions) - Benefit: single coherent execution surface - New complexity: tool-call error handling - Failure mode introduced: tool misuse / wrong-parameter calls - Preconditions: API access confirmed for all four systems (currently UNKNOWN) - **FIT: STRONG** **Durable-state store** - Problem solved: tracking escalation status across days, surviving process restarts - Requirement mapped: TIME HORIZON - Evidence: CONFIRMED ("ticket state may change over several days") - Benefit: reliable multi-day tracking, recoverability - New complexity: state schema design, staleness handling - Failure mode introduced: stale/inconsistent state if not synced with Zendesk/Jira truth - Preconditions: a persistence layer (DB or workflow-engine state) is available — PLAUSIBLE, not confirmed - **FIT: STRONG** **Event-driven orchestration** - Problem solved: initiating work when tickets change state, without constant polling - Requirement mapped: TRIGGER - Evidence: HIGHLY LIKELY (ticket monitoring implies events), but exact trigger mechanism UNKNOWN - Benefit: efficient, timely response - New complexity: webhook reliability, missed-event handling - Failure mode introduced: missed triggers → escalations silently not created - Preconditions: Zendesk supports webhooks/triggers — PLAUSIBLE, not confirmed - **FIT: STRONG, with a recurring-poll backstop (CONDITIONAL) to cover missed events** **Human approval gate** - Problem solved: preventing autonomous consequential customer commitments - Requirement mapped: explicit constraint (no autonomous refunds/account/production changes) - Evidence: CONFIRMED - Benefit: matches stated reliability-over-autonomy priority - New complexity: approval routing, timeout handling if approver doesn't respond - Failure mode introduced: approval bottleneck if approver is unavailable - Preconditions: an identified approver/role — UNKNOWN - **FIT: STRONG** **Lightweight verification/evidence check ("reflection")** - Problem solved: reduces risk of an ungrounded or wrong-team escalation reaching engineering - Requirement mapped: "evidence-backed," reliability priority - Evidence: PLAUSIBLE (not explicitly requested, but strongly implied by "evidence-backed" and "reliability matters more than autonomy") - Benefit: catches unsupported claims before they leave the system - New complexity: one extra bounded LLM pass - Failure mode introduced: none significant if bounded (single pass, not a loop) - Preconditions: none beyond the drafting step existing - **FIT: CONDITIONAL — include as a single bounded check, not open-ended reflection** **Supervisor–worker (multi-agent)** - Problem solved: coordinating multiple specialized agents working concurrently - Requirement mapped: none directly — the workflow is a single coherent chain per ticket, not multiple parallel specialized responsibilities - Evidence: user-referenced as a pattern to *consider*, but no workflow evidence of concurrent specialization needs - Benefit: would allow, e.g., a dedicated "evidence agent" and "routing agent" — but nothing in the requirements needs them to run independently or concurrently - New complexity: inter-agent handoff protocol, coordination overhead, more failure surface, harder traceability (works against the stated reliability priority) - Failure mode introduced: supervisor bottleneck, duplicated/contradictory state between workers - Preconditions: a genuine need for parallel specialized judgment — not established - **FIT: WEAK — see Stage 7 for full rejection rationale** **Router (product-area → team mapping)** - Problem solved: "engineering routing depends on product area" - Requirement mapped: CONFIRMED - Evidence: CONFIRMED - Benefit: correct team receives the brief - New complexity: maintaining a mapping table; ambiguous cases need fallback - Failure mode introduced: misrouted escalation - Preconditions: a product-area taxonomy and team mapping exist — PLAUSIBLE, not confirmed - **FIT: STRONG, as a lightweight classification/lookup step — not as a full architectural "router pattern" requiring separate infrastructure** **Idempotent execution / duplicate suppression** - Problem solved: avoiding duplicate Jira issues/Slack posts if the same ticket triggers multiple times - Requirement mapped: derived from durable state + event-driven trigger combination - Evidence: PLAUSIBLE (a natural consequence of the architecture, not explicitly stated) - Benefit: prevents noisy, duplicate escalations that would undermine trust in the system - New complexity: dedupe key design (ticket ID ↔ Jira issue ID) - Failure mode introduced: none if implemented correctly - Preconditions: durable state exists (already required) - **FIT: STRONG** --- # 7. OVERENGINEERING & ANTI-PATTERN CHECK - **Unnecessary multi-agent design:** The workflow is a single coherent per-ticket chain (evidence → decision → brief → route → track). There is no confirmed need for concurrent, independently-reasoning specialized agents. A supervisor–worker architecture would add coordination overhead, a new failure surface (inter-agent handoff), and would work against the explicit priority of "reliability and traceability... over maximum autonomy." **Rejected.** - **Unnecessary planning loop:** No evidence of open-ended multi-step planning; the sequence is fixed per ticket. A planner would add complexity without benefit. **Rejected.** - **Unbounded reflection:** A single evidence-grounding check before sending the brief is justified; an iterative critique loop is not supported by evidence and risks unbounded latency/cost. **Rejected in unbounded form; accepted as one bounded pass.** - **Excessive memory:** No evidence of a need for cross-ticket long-term memory (e.g., learning patterns over time). Only per-ticket durable state is justified. **Rejected for now — flagged as a possible future addition, not built.** - **Agent-to-agent chat without functional need:** Since no multi-agent architecture is adopted, this doesn't arise. **N/A.** - **Duplicate responsibilities:** Avoided by keeping evidence-gathering, decision, drafting, and routing as sequential steps of one worker rather than splitting them into overlapping agents. - **Too many model calls:** The design uses distinct, purposeful LLM calls (classify/decide, draft, verify) rather than looping — bounded and traceable. - **Autonomy without value:** Routine internal actions (creating a Jira issue, posting to Slack) are autonomous because they're reversible and low-impact; nothing autonomous is added beyond what's needed to hit the stated outcome. - **Central supervisor bottleneck / hidden single point of failure:** Avoided by not introducing a supervisor process at all; the durable-state store (not a supervisor agent) is the single source of truth, and it's a data store, not a reasoning bottleneck. --- # 8. SELECTED PATTERN STACK 1. **Event-driven trigger** (Zendesk webhook, with recurring-poll backstop) 2. **Tool-use agent** (single worker, phased: gather → decide/route → draft → verify → act → track) 3. **Retrieval-augmented context** (ticket history + KB) 4. **Lightweight router/classifier** (product area → engineering team) 5. **Durable-state store** (per-ticket escalation record) 6. **Bounded verification pass** (evidence-grounding check before send) 7. **Human approval gate** (only for customer-facing commitments) 8. **Idempotent execution / duplicate suppression** 9. **Retry-with-bounds + dead-letter handling** (for tool failures and SLA-breach escalations) --- # 9. COMPOSED AGENT ARCHITECTURE **Event trigger** - Role: initiates a per-ticket run - Upstream: Zendesk webhook / recurring poll job - Downstream: Context Builder - State read: last-processed state (to avoid reprocessing) - State written: run-started marker - Tools used: Zendesk (read) - Failure handling: missed webhook covered by periodic poll; poll failure retried with backoff - Human interaction: none **Context Builder (retrieval)** - Role: assembles ticket, ticket history, and relevant KB articles - Upstream: Event trigger - Downstream: Decision/Router step - State read: ticket ID, existing escalation record (dedupe check) - State written: assembled context snapshot (working context, not persistent) - Tools used: Zendesk (read), internal KB (read) - Failure handling: partial context (e.g., KB unavailable) → proceed with reduced confidence flag, do not block - Human interaction: none **Decision/Router** - Role: judges escalation-worthiness; if escalating, selects product area/team - Upstream: Context Builder - Downstream: Brief Drafter, or terminates (no escalation needed) - State read: assembled context - State written: decision + rationale (audit trail) - Tools used: none directly (LLM reasoning over assembled context) - Failure handling: ambiguous product area → flag for human routing rather than guess - Human interaction: none unless ambiguous **Brief Drafter** - Role: writes the evidence-backed escalation brief - Upstream: Decision/Router - Downstream: Verification step - State read: context + decision - State written: draft brief - Tools used: none directly - Failure handling: missing evidence for a claim → omit claim rather than fabricate - Human interaction: none **Verification (bounded)** - Role: checks the brief's claims are grounded in retrieved evidence; flags anything unsupported - Upstream: Brief Drafter - Downstream: Human Gate (if customer commitment present) or Action step - State read: draft brief + source context - State written: verification result - Tools used: none directly - Failure handling: fails verification → returns to Brief Drafter once (bounded retry), then escalates to human if still failing - Human interaction: none unless it fails twice **Human Approval Gate** - Role: reviews only when the brief contains a customer-facing commitment - Upstream: Verification - Downstream: Action step - State read: draft brief - State written: approval decision + approver identity (audit) - Tools used: Slack (notify approver) - Failure handling: no response within SLA → reminder, then escalate to a backup approver/manager - Human interaction: **primary human gate** **Action (Router execution)** - Role: creates/updates Jira issue, posts Slack notification - Upstream: Human Gate (if triggered) or Verification directly - Downstream: Result Verification - State read: decision, brief, approval record - State written: Jira issue ID, Slack message ID (linked to ticket record — dedupe key) - Tools used: Jira (write), Slack (write) - Failure handling: bounded retry (e.g., 3 attempts with backoff); on persistent failure, mark record as "action failed" and notify a human - Human interaction: notification only **Result Verification** - Role: confirms Jira issue and Slack post exist as expected - Upstream: Action - Downstream: State Update - State read: tool call results - State written: confirmed-delivered flag - Tools used: Jira (read), Slack (read) - Failure handling: mismatch → retry action once, then flag for human - Human interaction: none unless flagged **State Update / Tracker (durable)** - Role: maintains the escalation record over its multi-day life - Upstream: all prior steps - Downstream: recurring "check status" trigger - State read/written: full escalation record (status, timestamps, links) - Tools used: Jira (read, on each check), Zendesk (write, to reflect status back to the ticket) - Failure handling: SLA breach with no engineering response → reminder, then human escalation - Human interaction: only on SLA breach --- # 10. STATE / MEMORY / CONTEXT MODEL | State type | What is stored | Why | Lifetime | Readers | Writers | Stale-state risk | Privacy/access | |---|---|---|---|---|---|---|---| | **Execution state** | Current step in the per-ticket workflow (observed/decided/drafted/verified/approved/actioned) | Enables resume after failure/restart | Until ticket escalation resolved | Orchestrator | Orchestrator | Low if updated transactionally with each step | Internal only | | **Working context** | Assembled ticket + history + KB snippets for one run | Feeds decision/drafting steps | Single run (not persisted beyond it) | Decision, Drafter, Verification steps | Context Builder | N/A (ephemeral) | Internal only | | **Retrieved knowledge** | KB article excerpts relevant to the ticket | Grounding for the brief | Single run | Drafter, Verification | Context Builder | Risk of outdated KB content — mitigate by citing article + last-updated date in the brief | Internal only | | **Persistent (durable) escalation record** | Ticket ID, decision + rationale, brief, Jira issue ID, Slack message ID, approval record, status timeline | Multi-day tracking, dedupe, audit | From escalation creation until closed + defined retention window | Tracker, Action, Result Verification, humans reviewing history | Orchestrator | Risk of drifting out of sync with actual Zendesk/Jira state — mitigate with periodic reconciliation reads | Internal, support/engineering-visible | | **Audit history** | Every decision, evidence used, approvals, tool actions taken, timestamps | Traceability requirement (explicit priority) | Long-term (retention policy — UNKNOWN, likely governed by company data policy) | Support leads, compliance if applicable | Orchestrator (append-only) | Low — append-only by design | Should follow existing customer-data handling policy — UNKNOWN specifics | **No long-term cross-ticket memory** (e.g., "agent learns escalation patterns over time") is included — not supported by current evidence, and would add complexity and privacy surface without a confirmed requirement. --- # 11. TOOL & INTEGRATION ARCHITECTURE | Tool | Purpose | R/W | Input | Expected output | Failure | Retry | Idempotency need | Approval requirement | Post-action verification | Availability | |---|---|---|---|---|---|---|---|---|---|---| | **Zendesk** | Read ticket + history; write status/notes back | Read + Write | Ticket ID | Ticket object, conversation history | API error, rate limit | Bounded (3x, backoff) | Not critical for reads; writes should be idempotent (avoid duplicate notes) | No | Confirm note/status persisted | CONFIRMED available, exact API scope UNKNOWN | | **Internal KB** | Retrieve relevant documentation | Read | Query/keywords from ticket | Article excerpts | Search failure/no results | Bounded | N/A | No | N/A | CONFIRMED available, retrieval mechanism (search API vs. index) UNKNOWN | | **Jira** | Create/route escalation issue; check status | Read + Write | Product-area/team, brief content | Issue ID, issue status | API error, permission error, wrong project | Bounded | **Critical** — must not create duplicate issues for the same ticket | No (routine), unless issue content includes a customer commitment | Confirm issue created in correct project with correct fields | CONFIRMED available, project/team mapping UNKNOWN | | **Slack** | Notify engineering team; notify approver | Write | Channel/user, message content | Message ID | API error, wrong channel | Bounded | Should avoid duplicate posts | No (routine notification); yes if message contains a commitment | Confirm message delivered | CONFIRMED available | No tool availability, API scope, or rate limit is assumed beyond what's stated — all marked per the table above. --- # 12. AUTONOMY & HUMAN-GATE MATRIX | Action | Classification | Autonomous? | Approval required? | Evidence required? | Escalation condition | |---|---|---|---|---|---| | Read ticket/history/KB | Read-only | Yes | No | N/A | N/A | | Decide to escalate / select team | Low-impact (internal) | Yes | No | Yes — must cite evidence for the decision | Ambiguous product area → human routing | | Draft escalation brief | Low-impact (internal, not yet sent) | Yes | No | Yes — every claim grounded | Verification failure twice → human review | | Create/route Jira issue (no customer commitment) | Reversible | Yes | No | Yes | Tool failure after retries → human notified | | Post Slack notification to engineering | Reversible | Yes | No | Yes | Delivery failure after retries → human notified | | Brief containing a customer-facing commitment (e.g., "we will refund," "we will expedite a fix by X") | **Consequential** | **No** | **Yes — required per explicit constraint** | Yes | No approver response within SLA → backup approver | | Refund / account changes | Irreversible / human-only | **No** | **Yes, and outside this agent's scope entirely** | N/A | Always routed to a human process, not this agent | | Production changes | Irreversible / human-only | **No** | **Yes, and outside this agent's scope entirely** | N/A | Always routed to a human process, not this agent | Autonomy is scoped strictly to internal, reversible actions (creating tickets, notifying teams, tracking). Anything touching customer commitments or the excluded categories (refunds, accounts, production) is a hard human gate or entirely out of scope, matching the explicit constraint. --- # 13. FAILURE & RECOVERY ARCHITECTURE | Failure | Detection | Containment | Retry | Recovery | Escalation | User-visible state | |---|---|---|---|---|---|---| | **Tool failure (Zendesk/Jira/Slack API error)** | Non-2xx response / timeout | Halt that step only | Bounded (e.g., 3x, exponential backoff) | Resume from last successful state | After max retries → notify human, mark record "action failed" | "Escalation pending — action failed, needs review" | | **Missing/incomplete context (KB unavailable)** | Retrieval returns empty/error | Proceed with reduced-confidence flag rather than blocking entirely | One retry | Continue with available context, note gap in audit trail | If decision confidence too low → flag for human | "Escalation drafted with limited evidence" | | **Stale state** | Reconciliation read finds mismatch (e.g., ticket already resolved elsewhere) | Halt further action | N/A | Re-sync state from source of truth (Zendesk/Jira) | If unresolvable automatically → human review | "State conflict detected" | | **Bad/irrelevant retrieval** | Verification step flags unsupported claims | Draft not sent | One re-draft attempt | Re-run Drafter with feedback from Verification | Fails twice → human review | "Brief needs review — evidence insufficient" | | **Unsupported/ambiguous decision (product area unclear)** | Classifier confidence below threshold | Do not auto-route | N/A | N/A | Immediate → human routing decision | "Needs manual routing" | | **Duplicate action (double escalation for same ticket)** | Dedupe key check against durable state before acting | Prevented before it happens | N/A | N/A | If detected after the fact → merge/close duplicate, notify human | "Duplicate escalation prevented/merged" | | **Routing failure (wrong team)** | Engineering marks issue as wrong team (Jira field/comment), or no response + manual flag | Re-route | N/A | Update routing record, notify correct team | If pattern recurs → flag mapping table for human review (not auto-corrected) | "Re-routed to correct team" | | **Human non-response (approval or SLA)** | Timer against SLA | N/A | One reminder | N/A | Escalate to backup approver/manager after SLA breach | "Awaiting approval — reminder sent" / "Escalated for non-response" | | **Partial completion (e.g., Jira created but Slack post failed)** | Result Verification step | Record marked partially complete | Retry the failed sub-action only | Complete the missing sub-action | After max retries → human notified with exact gap | "Partially completed — Slack notification pending" | | **External system failure (Jira/Slack/Zendesk outage)** | Repeated failures across many tickets, not just one | Circuit-breaker: pause new actions against that system | Backoff with longer intervals | Resume when system healthy | If prolonged → notify human ops | "System outage — escalations queued" | **No infinite autonomous retry** is used anywhere; every retry path is bounded and terminates in either success or a human-visible state. --- # 14. ARCHITECTURE DECISION RECORD | Decision | Driving force | Selected mechanism | Alternative | Why selected | Trade-off | Revisit trigger | |---|---|---|---|---|---|---| | Single tool-using agent vs. supervisor/multi-worker | No confirmed need for concurrent specialization; reliability > autonomy priority | Single phased worker | Supervisor–worker multi-agent | Simpler, more traceable, fewer failure surfaces | Less parallelism if volume grows very high | If ticket volume or the need for genuinely independent concurrent judgment (e.g., separate teams needing separate simultaneous negotiation) emerges | | Durable state store vs. in-memory/session state | Multi-day time horizon (confirmed) | Persistent per-ticket record | In-memory workflow | Required for correctness given the stated time horizon | Added storage/reconciliation complexity | N/A — this is fixed by the stated requirement | | Bounded verification pass vs. no check / vs. open reflection loop | "Evidence-backed" + reliability priority, but not open-ended | One-pass grounding check with one re-draft retry | No check (risk of hallucinated evidence) / iterative reflection loop (risk of unbounded cost/latency) | Balances reliability against overengineering | Adds one LLM call per escalation | If false-positive/negative rate on verification proves too high or low in practice — UNKNOWN until tested | | Human gate scoped to customer commitments only, not all escalations | Explicit constraint only names refunds/account/production changes as excluded; routine engineering routing not stated as needing approval | Narrow human gate | Approve every escalation | Matches "reliability over maximum autonomy" without introducing an approval bottleneck for low-risk actions | Risk: if stakeholders actually want *all* escalations approved, this under-gates | **Must be confirmed with stakeholders before build — currently an assumption, not evidence** | | Router as lightweight classification/lookup, not a standalone architectural component | "Routing depends on product area" — a mapping problem, not evidence of complex multi-step routing logic | Rule table + LLM fallback for ambiguous cases | Full dedicated routing agent/service | Matches the scale of the actual problem | If the mapping is very complex (e.g., many overlapping product areas), may need to grow into its own component | If product-area taxonomy proves large/ambiguous in practice | --- # 15. IMPLEMENTATION BLUEPRINT | Unit ID | Component | Responsibility | Dependencies | Input/Output | State | Tools | Failure handling | Human gate | Definition of done | |---|---|---|---|---|---|---|---|---|---| | U1 | Durable state schema | Define the escalation record structure | None | — / schema | Persistent record | None | N/A | No | Schema supports all fields in Stage 10 | | U2 | Zendesk trigger integration | Detect new/updated unresolved tickets | U1 | Zendesk event → ticket ID | Run-started marker | Zendesk (read) | Missed events covered by poll (U3) | No | Reliably fires on ticket create/update in test env | | U3 | Recurring poll backstop | Catch missed events, catch SLA breaches | U1 | Scan of open records | Reconciliation | Zendesk, Jira (read) | Bounded retries | No | Detects a deliberately-missed test event | | U4 | Context Builder | Assemble ticket history + KB | U2 | Ticket ID → context bundle | Working context | Zendesk, KB (read) | Degrade gracefully on partial data | No | Produces complete bundle for a known test ticket | | U5 | Decision/Router step | Escalate? which team? | U4 | Context → decision + rationale | Execution + audit state | None (LLM reasoning) | Low-confidence → human flag | No (unless ambiguous) | Correctly classifies a labeled test set of tickets | | U6 | Brief Drafter | Write evidence-backed brief | U5 | Decision + context → draft | Execution state | None | Missing evidence → omit claim | No | Draft cites only retrieved evidence | | U7 | Verification step | Ground-check the brief | U6 | Draft + context → pass/fail + notes | Execution state | None | One re-draft retry, then human | No (unless fails twice) | Catches deliberately-inserted unsupported claim in test | | U8 | Human Approval Gate | Approve customer-commitment briefs | U7 | Draft → approve/reject | Approval record | Slack (notify) | SLA reminder → backup approver | **Yes** | Approval flow completes end-to-end in test | | U9 | Action executor | Create Jira issue, post Slack | U7/U8 | Approved brief → issue ID, message ID | Persistent record update | Jira, Slack (write) | Bounded retry, dead-letter on persistent failure | No | Issue and message verifiably created | | U10 | Result Verification | Confirm actions landed | U9 | Tool results → confirmed flag | Persistent record | Jira, Slack (read) | Retry once, then human flag | No | Detects a deliberately-failed action in test | | U11 | Tracker / follow-up | Monitor for engineering response over days | U10 | Ongoing | Persistent record | Jira, Zendesk (read/write) | SLA breach → reminder → human escalation | On SLA breach | Correctly flags a simulated non-response after SLA | **Sequencing / highest-risk-first:** Build and test **U5 (Decision/Router)** and **U7 (Verification)** first — these carry the actual judgment risk (wrong escalation calls, ungrounded briefs). The tool-plumbing units (U2, U9, U10) are comparatively low-risk engineering work. Prove the judgment quality before investing in the full durable-state and tracking infrastructure. --- # 16. EVALUATION PLAN | Test | Behavior under test | Pass condition | Fail condition | What failure would change | |---|---|---|---|---| | **Task success** | End-to-end: unresolved ticket → correctly escalated or correctly left unescalated | Matches a human-labeled ground-truth set on escalate/no-escalate decision | Wrong decision on labeled cases | Revisit decision-step prompting/threshold; possibly add more context signals | | **Routing quality** | Product area → correct engineering team | Matches labeled team assignment | Misrouted brief | Revisit routing table completeness; may need dedicated routing logic | | **Tool selection** | Correct tool called for each phase (e.g., doesn't call Jira write during read-only context step) | No out-of-scope tool calls in trace | Any unauthorized tool call | Tighten tool-access scoping per step | | **Tool execution** | Jira issue / Slack message created with correct fields | Fields match expected schema | Missing/incorrect fields | Fix tool-call construction | | **Evidence grounding** | Every claim in the brief traceable to retrieved evidence | Verification step catches all deliberately-inserted unsupported claims in a red-team test set | Any unsupported claim passes through | Strengthen verification step or its grounding source list | | **State continuity** | Durable state correctly resumes after a simulated process restart mid-workflow | Workflow resumes at the correct step, no lost or duplicated work | Lost state or duplicated action after restart | Fix state persistence/checkpointing | | **Duplicate-action prevention** | Same ticket triggering twice doesn't create two Jira issues | Only one issue created | Duplicate issue created | Fix dedupe-key logic | | **Human escalation** | Approval gate fires only when a customer commitment is present; SLA breach triggers reminder then human escalation | Gate fires correctly on labeled test cases; SLA logic fires exactly at threshold | Gate skipped when it should fire, or fires when it shouldn't; SLA timing wrong | Revisit commitment-detection logic or SLA timer | | **Recovery** | Tool failure triggers bounded retry then human-visible failure state, never silent loss | Failure surfaces correctly after max retries | Silent failure or infinite retry | Fix retry bounds/dead-letter handling | | **End-to-end completion** | Full lifecycle from trigger to resolved/closed state | Record reaches a terminal state correctly in simulated full-run test | Record stuck in an undefined state | Audit state machine transitions for gaps | No benchmark numbers are asserted — these are the tests to run; none have been executed. --- # 17. AGENT PATTERN ARCHITECTURE PACK ## ARCHITECTURE IN ONE VIEW ``` Zendesk event (+ poll backstop) ↓ Context Builder (Zendesk history + KB retrieval) ↓ Decision/Router (escalate? which team?) ──ambiguous──> Human routing ↓ Brief Drafter (evidence-backed) ↓ Verification (bounded grounding check) ──fails 2x──> Human review ↓ [Human Approval Gate] ← only if brief contains a customer commitment ↓ Action executor (Jira issue + Slack notify) ↓ Result Verification ↓ Durable State Update ↓ Tracker (days-long wait) ──SLA breach──> Reminder → Human escalation ↓ COMPLETE (resolved) or loop back on new ticket activity ``` ## PRIMARY PATTERN Event-driven, tool-using single agent operating over durable per-ticket state. ## SUPPORTING PATTERNS Retrieval-augmented context, lightweight routing/classification, bounded verification pass, human approval gate, idempotent execution, bounded retry with dead-letter/SLA escalation. ## WHY THIS ARCHITECTURE FITS Maps directly to confirmed forces: multi-day state (durable store), four-system tool use (tool gateway), product-area routing (lightweight router), explicit exclusion of autonomous high-impact actions (human gate), and the explicit priority of reliability/traceability over maximum autonomy (bounded steps, audit trail, no open-ended loops). ## REJECTED COMPLEXITY - **Supervisor–worker multi-agent architecture** — no evidence of a need for concurrent, independently-reasoning specialists; would add coordination risk without a corresponding benefit. - **Open-ended reflection/planning loops** — replaced with one bounded verification pass. - **Long-term cross-ticket memory** — not supported by current evidence; only per-ticket durable state is built. ## CONTROL LOOP ``` TRIGGER (unresolved ticket) → OBSERVE (context) → DECIDE (escalate/route) → ACT (brief, gate, Jira, Slack) → VERIFY (grounding, delivery) → COMPLETE / CONTINUE (track) / ESCALATE (SLA breach, ambiguity, repeated failure) ``` ## STATE MODEL Persist: per-ticket escalation record (decision, rationale, brief, Jira/Slack IDs, approval record, status timeline, audit trail). Do not persist: raw working context per run, long-term cross-ticket memory. ## TOOL MODEL Zendesk (read/write), Jira (read/write, dedupe-protected), Slack (write, notification), internal KB (read). No write access beyond these; no refund/account/production system access at all. ## AUTONOMY BOUNDARY The agent may autonomously read from all four systems, decide escalation-worthiness, draft briefs, create Jira issues, and post Slack notifications — provided the brief contains no customer-facing commitment. ## HUMAN GATES Any brief containing a customer-facing commitment; ambiguous product-area routing; verification failing twice; SLA breach with no engineering response. Refunds, account changes, and production changes are entirely outside this agent's action space, not merely gated. ## FIRST FAILURE TO DESIGN FOR **Ungrounded/hallucinated evidence in the escalation brief** — this is the failure most likely to erode trust with engineering teams and directly contradicts the "evidence-backed" requirement; the bounded verification step exists specifically to catch this. ## FIRST COMPONENT TO PROTOTYPE **Decision/Router + Verification steps** — these carry the actual judgment risk. Prove escalation-decision accuracy and evidence-grounding quality against a labeled ticket set before building the full tool-integration and tracking scaffolding. ## FIRST EVALUATION **Evidence-grounding test** (red-team set with deliberately unsupported claims) — this has the highest information value, since a failure here undermines the entire "evidence-backed" premise of the system regardless of how well the plumbing works. ## DO NOT BUILD YET Cross-ticket long-term memory/pattern learning; any component touching refunds, account changes, or production systems; a full supervisor/multi-agent expansion — none are supported by current evidence. ## REVISIT WHEN - Stakeholders confirm whether *all* escalations require human approval, or only customer-commitment ones (currently an assumption). - Ticket volume or the need for genuinely concurrent, independent specialist judgment emerges (would revisit supervisor/worker rejection). - The product-area taxonomy proves too complex for a lookup table (would revisit router design). - API access/scopes for Zendesk, Jira, or Slack are confirmed or found insufficient. ## STATUS **READY WITH OPEN DECISIONS** — the architecture is coherent and bounded, but two material unknowns should be resolved before full build: (1) exact API access/scopes for the four systems, and (2) whether human approval should be scoped to customer commitments only or to every escalation. --- Want this saved as a reference document (e.g., a Word or Markdown file) for your team?