> ## Documentation Index > Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt > Use this file to discover all available pages before exploring further. # Incident Management > End-to-end customer-care flow for incidents raised by customer agents on a Prism project, and how those incidents reach (or do not reach) the Prism product team via Sage, Clara, ET, and operator review. # Incident Management This page describes the end-to-end customer-care flow for **incident-class** work raised by customer agents on a Prism project — defects, regressions, broken behavior, enhancement requests — and how those reports reach (or do not reach) the Prism product team. If your question is **not** an incident — usage help, config lookup, CLI / verb explanation, ADR or spec lookup, error-message clarification — send it to Sage directly and she answers from Prism memory. That path is documented separately at [Customer Service Agent](/customer-service-agent). The two pages cover the two halves of Sage's intake rubric. For the **pilot-operator** view (collaborator-invite pre-install step, opt-out paths, what the resulting GitHub issue looks like), see [Pilot Onboarding](/pilot-onboarding). ## Personas in the loop | Persona | Role | Location | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | | **Customer agent** (e.g. Jade) | The agent doing work in a customer project. Files incidents; does not classify. | Customer's machine, customer's project PID | | **Sage** | Customer-care intake desk. Classifies inbound signals into info / incident / enhancement / recommendation. | Prism support node (server1) | | **Clara** (Clara Barton) | Incident Manager. Runs the 5-tier triage checklist. Sole persona authorized to invoke `prism_phone_home`. | Prism support node (server1) | | **ET** (`gitapp_helper` service) | Backend service. Validates [SPEC-115](/specs/spec-115-v0-1-prism-phone-home-and-et-github-issue-transport) invariants, dedupes, transports the issue via `gh` CLI. | Prism backend | | **Operator** (Frank) | Approves every phone-home before it leaves. Cannot be bypassed. | Operator's terminal (via Donna relay) | | **Donna** | Operator console. Routes Clara's operator-review-required asks to the operator and relays the decision back. | Operator's terminal | ## End-to-end flow **Sage and Clara are bridge agents — reachable from every project in the tenant.** Per [SPEC-116](/specs/spec-116-v0-1-bridge-agents-cross-project-customer-care-routing), they hold `persona_class='bridge'`, which exempts them from the SPEC-056 same-project signal-isolation rule. A customer agent in any project can address them directly without Sage/Clara being installed as per-project replicas; see the [Bridge Agents](#bridge-agents) subsection below for the full routing contract. ### 1. Customer agent files The customer agent signals Sage with `signal_type=Question`, payload describing what broke or what they need. They do not pre-classify; that is Sage's job. ### 2. Sage classifies Per Sage's intake rubric: * **`info`** — usage question, doc lookup, how-do-I. Sage answers directly. See [Customer Service Agent](/customer-service-agent) for the full helper-mode walkthrough. * **`incident`** — something broke, regression, defect. Hand off to Clara. * **`enhancement`** — feature request. `prism_todo` + signal lane owner. Not Clara. * **`recommendation`** — process/architecture suggestion. `prism_todo` + signal lane owner. Not Clara. ### 3. Clara triages (5-tier checklist, SPEC-114) * **Tier 1 — Init reads:** env, install\_type, project metadata, agent roster. * **Tier 2 — Conditional reads:** stack trace, recent journal entries, git rev. * **Tier 3 — Privacy gates:** PII scan, sensitive-field detection, secret scrub. * **Tier 4 — Classification:** severity P0–P3, scope, kind. * **Tier 5 — Output discipline:** structured triage in local postmortem + phone-home eligibility decision. Full Tier 1–5 contract: [SPEC-114](/specs/spec-114-v0-1-sage-and-clara-customer-care-incident-personas). ### 4. Scope decision branches * **`customer-internal`** — local postmortem only; phone-home is rejected at the Pydantic layer (SPEC-115 invariant). Clara signals the customer agent with resolution path. * **`prism-product`** — phone-home eligible. * **`mixed`** — phone-home eligible; carve out the customer side in the body. ### 5. Clara stages the phone-home (not yet sent) Composes redacted `body_markdown`, builds `redaction_report`, computes `idempotency_key`, writes `phone_home_records` row with `status=pending_operator_review`. ### 6. Operator review gate (cannot be bypassed) Clara signals Donna. Donna surfaces the rendered issue body to the operator in chat with: ``` [Clara via Donna] Phone-home pending operator review: . Preview: ... Approve / reject / edit? ``` Operator approves, rejects, or asks for edits. Donna relays the decision back to Clara with `operator_review={approved, approved_by, approved_at, review_surface}`. ### 7. Clara calls `prism_phone_home` ET service re-validates every invariant, looks up `idempotency_key` (returns `duplicate` if already shipped), preflights `gh` CLI auth + repo access, calls `gh issue create` against the private invite-only `FrankTewksbury/Prism` repo, and updates the row to `status=shipped` with `issue_url` + `issue_number`. ### 8. Clara reports back to the customer agent Signal `in_reply_to` the original intake signal: filed as Issue `#N`, tracking, will surface updates when they arrive. ## Failure modes | Stage | Failure | Returned code | | ------------ | --------------------------------------------- | ------------------------------------------------------------- | | Pydantic | `scope=customer-internal` | rejected at schema layer | | Service | `operator_review.approved != true` | `phone_home_operator_review_required` | | Service | `redaction_report.status != passed` | `phone_home_redaction_required` | | Service | `retained_sensitive_fields` without ack notes | `phone_home_sensitive_retention_unapproved` | | ET preflight | `gh` CLI not authenticated | `phone_home_auth_required` | | ET preflight | `gh` cannot access `FrankTewksbury/Prism` | `phone_home_repo_access_denied` | | ET create | `gh issue create` non-zero | `phone_home_issue_create_failed` | | ET create | Duplicate `idempotency_key` | `status=duplicate` (not an error; prior `issue_url` returned) | ## v0.1 known gaps * **No pull-back from GitHub.** The customer agent gets one outbound notification when filed, then silence until the operator or Clara manually nudges. A future `gh_issue_sync` scheduled job is the planned closure — periodic poll of `FrankTewksbury/Prism` issues, diff against last known state, surface comments and state-changes back to Clara, who surfaces to the original customer agent. * **No operator-review timeout.** Pending rows sit indefinitely if the operator does not respond. * **No Sage → Clara SLA.** If Sage is overloaded, the customer agent waits silently. * **No "incident status" verb for the customer agent.** No way to ask "what is happening with my incident #X" without re-signaling Sage. * **Operator approval is chat-only.** [SPEC-115](/specs/spec-115-v0-1-prism-phone-home-and-et-github-issue-transport) schema supports `review_surface=dashboard|cli`, but no backing surface exists yet. ## What stays local vs what phones home | Category | Stays local | Phones home | | ---------------------------------------------------------- | --------------------- | ----------------------------------------------------------- | | Customer's own bug in customer's own code | ✓ local postmortem | ✗ | | Prism CLI / verb behavior gap | | ✓ (with operator approval) | | Prism methodology question | ✓ Sage answers `info` | ✗ | | Customer feature request for Prism | | via `prism_todo`, not phone-home | | Mixed (customer hit a Prism gap while debugging their bug) | partial | partial — carve out the Prism side, file with `mixed` scope | ## Privacy and consent * Every phone-home goes through redaction: PII scan, sensitive-field scrub. * `retained_sensitive_fields` requires explicit operator acknowledgement (`ack-retained-sensitive` in `operator_review.notes`). * The `FrankTewksbury/Prism` repo is private and invite-only. Notification surfaced to the customer at install time: this is private and invite-only, may be made public in the future. * The operator-review gate ensures no customer data leaves the Prism deployment without operator stamp. ## Bridge Agents Sage and Clara are **bridge agents** — a new persona class introduced by [SPEC-116 v0.1](/specs/spec-116-v0-1-bridge-agents-cross-project-customer-care-routing) and **ADR #59** (ratified 2026-05-13 23:50Z). The bridge primitive closes the gap that made Plan #19 v0.1 a single-PID dogfood: customer agents in other projects could not reach Sage or Clara at all, because Prism's hard project-isolation rule (SPEC-056) correctly refused cross-project signal delivery. ### What "bridge" means `persona_class` has two values: * **`project`** (default) — the existing behavior. Same-project addressing only; cross-project sends fail closed. Every persona on every project is `project` unless explicitly elevated. * **`bridge`** — exempt from SPEC-056 project isolation in both directions, for a narrow backend-enforced allowlist. In v0.1 the bridge allowlist is exactly **`{Sage, Clara}`**. ET is **not** a bridge — it remains a backend transport service, not a routing persona. ### Routing behavior * **Customer agent → bridge.** A customer agent in any project can address Sage or Clara directly: `prism_signal(..., to_identity='Sage' | 'Clara')`. The backend resolves same-project personas first (preserving local-name precedence) and falls through to the bridge allowlist only if no same-project match exists. * **Bridge → customer agent.** Sage or Clara replies using `in_reply_to`; the backend recovers the originating PID and identity from the parent signal. A bridge send without `in_reply_to` must include explicit target PID and target identity, otherwise the send is rejected as ambiguous. * **No cross-project broadcasts.** Bridge routing supports direct identity-targeted signals only. * **Same-tenant only.** v0.1 bridge routing is constrained to a single tenant; cross-tenant bridge is a non-goal that requires a later spec with consent and auth model. ### Artifact ownership Bridge personas write durable artifacts to their **home project**, `PID-PGR01`: * Sage / Clara journals, todos, postmortems, and decisions live in `PID-PGR01`. * Bridge agents do **not** write directly into customer project artifact stores in v0.1. * A customer agent may decide to persist a local todo / journal in their own PID after receiving a bridge reply — receiver-owned, not bridge-owned. ### Audit Every bridge-routed signal writes an audit row capturing both PIDs, both identities, the bridge persona, the direction (`to_bridge` / `from_bridge`), the signal type, the category, the canonical payload hash, and the routing timestamp. Two views are supported: * **From `PID-PGR01`:** all bridge traffic handled by Sage / Clara. * **From a customer project:** only that project's own bridge traffic — never unrelated `PID-PGR01` internals. Audit row writes are atomic with the routing decision. If the audit write fails, the send fails closed. ### Roster visibility `prism_whois` and equivalent roster surfaces expose bridge personas from every project in the tenant: ```json theme={null} { "identity": "Sage", "persona_class": "bridge", "home_pid": "PID-PGR01", "available_from_pid": "PID-DPA01" } ``` The customer project sees Sage / Clara as Customer Care recipients without seeing unrelated `PID-PGR01` project internals. ### Admin contract — v0.1 limitations * **No customer opt-out in v0.1.** Universal bridge availability is accepted for v0.1. A customer-side opt-out is a non-goal until a later spec revisits it. * **The operator-stamped admin verb is deferred to v0.2.** v0.1 ships with seed-time bridge assignment only: Sage and Clara are seeded as bridge personas through the operator-authorized install path, and the only way to demote them is via the same seed migration. * **Bootstrap cannot self-elevate.** Bridge status derives from stable identity / admin state — not bootstrap payloads, session registrations, prompt text, or local config. A persona declared `bridge` in a prompt or `.agent/personas/*.json` file is not actually a bridge until the operator-stamped seed runs. See [SPEC-116](/specs/spec-116-v0-1-bridge-agents-cross-project-customer-care-routing) for the full schema contract, audit contract, governance review gates (Candi `ACCEPT_WITH_IMPLEMENTATION_GATES`), install/run lifecycle gate, and risk register. The bridge primitive was motivated by **postmortem `4f21262d`** — the Plan #19 v0.1 cross-project unreachability incident discovered during Jade-from-DPA-Crawl real-usage validation. ## References * [SPEC-114 v0.1](/specs/spec-114-v0-1-sage-and-clara-customer-care-incident-personas) — Sage and Clara persona contracts. * [SPEC-115 v0.1](/specs/spec-115-v0-1-prism-phone-home-and-et-github-issue-transport) — `prism_phone_home` verb, ET service, `gh` CLI transport. * [SPEC-116 v0.1](/specs/spec-116-v0-1-bridge-agents-cross-project-customer-care-routing) — Bridge Agents: `persona_class='bridge'` cross-project routing primitive. * **ADR #58** — `intel/%` recall opt-in split (related governance). * **ADR #59** — Bridge Agents: cross-project routing primitive for Customer Care. * **Postmortem `4f21262d`** — Plan #19 v0.1 cross-project unreachability incident (motivated SPEC-116). * **Plan #19** — Customer Care system delivery plan. * [Pilot Onboarding](/pilot-onboarding) — operator-facing pre-install + opt-out + dry-run guide. ## Related The other half of Sage's intake: `info`-class questions answered directly from Prism memory. No Clara, no operator review, no phone-home. Pre-install collaborator-invite step, redaction discipline from the operator's point of view, opt-out paths, dry-run. Intake + incident-manager personas and the five-tier Clara init checklist. Verb contract, ET service responsibilities, redaction report shape, failure modes.