--- id: CAP-PFM-LLM-012 title: Explain an AI refusal or unsuccessful conversation feature: FEAT-PFM-LLM-04 product_area: platform module: llm revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: [] purpose: Give support a decision-time explanation and a separate check of what would happen now. outcomes: - A refusal explanation uses its recorded admission figures. - Failed requests expose attempt-level verdicts. - A current comparison shows whether capacity changes affect admission. concepts: - CON-PFM-LLM-001 - CON-PFM-LLM-003 actors: - ACT-PFM-033 - ACT-PFM-004 surfaces: - console - api preconditions: - The request has a refusal or error outcome. postconditions: - Explanation does not reserve credits or charge the organization. permissions: - key: hq.llm-usage.read where_checked: api scope: global rules: - id: BR-CAP-PFM-LLM-012-01 proved_by: [ATS-PFM-LLM-012-01, TST-PFM-LLM-006] statement: Only Rhythm staff with the HQ AI usage read key can obtain explanations through the HQ route. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#is refused 403 for a customer’s administrator, because the route is system origin: none - id: BR-CAP-PFM-LLM-012-02 proved_by: [ATS-PFM-LLM-011-09, ATS-PFM-LLM-012-02, TST-PFM-LLM-025] statement: >- Refusal explanations preserve the recorded policy and decision-time figures and describe allowance arithmetic, concurrency or the disabled switch without recomputing history. kind: policy enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/explain/explain-invocation.ts' origin: none - id: BR-CAP-PFM-LLM-012-03 proved_by: [ATS-PFM-LLM-012-03, TST-PFM-LLM-025] statement: >- Referenced capacity grants are resolved with their windows, and an unreadable reference remains visible as not found. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/llm/tests/integration/services/explain/explain-invocation.integration.spec.js#says so when an override the snapshot named cannot be read back, rather than dropping it origin: none - id: BR-CAP-PFM-LLM-012-04 proved_by: [ATS-PFM-LLM-007-15, ATS-PFM-LLM-012-04, ATS-PFM-LLM-012-08, TST-PFM-LLM-025] statement: >- The current-position block describes allowance, committed and remaining credits and grants since the refusal, then evaluates the same estimate under present admission rules without reserving credits. kind: calculation enforced_at: - service - database must_prove: true provenance: observed source: 'services-platform:modules/llm/services/explain/explain-invocation.ts' origin: none - id: BR-CAP-PFM-LLM-012-05 proved_by: [] statement: >- An older refusal without a snapshot uses the retained request fields and its estimate for the current admission check. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-platform:modules/llm/tests/integration/services/explain/explain-invocation.integration.spec.js#still answers block 3 for a refusal with no snapshot, against the row’s own estimate origin: none - id: BR-CAP-PFM-LLM-012-06 proved_by: [ATS-PFM-LLM-002-13, ATS-PFM-LLM-012-05, ATS-PFM-LLM-012-09, TST-PFM-LLM-025, TST-PFM-LLM-074] statement: >- Failure explanations present classification, ending and ordered attempts with status, error, latency and retry verdict, including a truncation warning when appropriate. kind: calculation enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/explain/explain-invocation.ts' origin: none - id: BR-CAP-PFM-LLM-012-07 proved_by: [] statement: >- A limit-ending explanation identifies the exhausted limit and the value recorded in the operation’s routing version. kind: policy enforced_at: - service must_prove: false provenance: observed source: 'services-platform:modules/llm/services/explain/explain-invocation.ts' origin: none - id: BR-CAP-PFM-LLM-012-08 proved_by: [ATS-PFM-LLM-012-06, TST-PFM-LLM-006, TST-PFM-LLM-025] statement: >- A healthy settled request is rejected as having nothing to explain, while missing and foreign requests return not found. kind: validation enforced_at: - service - api must_prove: true provenance: observed source: 'services-platform:modules/llm/services/explain/explain-invocation.ts' origin: none - id: BR-CAP-PFM-LLM-012-09 proved_by: [] statement: Explanation reads do not open captured content or disclose its storage reference. kind: invariant enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/llm.md#Explaining a refusal' origin: none scenarios: - id: SC-CAP-PFM-LLM-012-01 given: A recorded refusal is followed by capacity grants. when: Support requests its explanation. then: The response keeps refusal facts and lists later grants alongside a current comparison. provenance: test source: >- services-platform:modules/llm/tests/integration/services/explain/explain-invocation.integration.spec.js#lists the overrides granted since, newest first, including one that has already ended - id: SC-CAP-PFM-LLM-012-02 given: The HQ detail contains a refused request. when: The explanation panel renders. then: Its three sections and evidence statuses appear without captured bodies. provenance: test source: >- react-console:e2e/mock/hq-ai-usage.mock.spec.ts#a refused request explains itself in three blocks, and shows evidence statuses without content edge_cases: [] constraints: [] depends_on: - CAP-PFM-LLM-007 - CAP-PFM-LLM-002 related: - CAP-PFM-LLM-011 journeys: - JNY-PFM-LLM-002 open_questions: [] evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (Explaining a refusal, The refusal snapshot); aws/api/llm-usage.routes.ts (explainHqTenantLlmUsageInvocation); services/explain/explain-invocation.ts, explain-sentences.ts; services/persistence/allowance-periods.ts (wouldAuthorizeCredits); tests integration/services/explain/explain-invocation.integration.spec.js, unit/services/explain/explain.spec.ts, e2e/llm-adjustments-and-organization.e2e.spec.js. - >- react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/console/hq/ai-usage/request/explain-panel.tsx, attempts-card.tsx; e2e/mock/hq-ai-usage.mock.spec.ts. controls: [TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-LLM-04-01, FAS-PFM-LLM-04-02, FAS-PFM-LLM-04-03, FAS-PFM-LLM-04-04, FAS-PFM-LLM-04-05] suites: [TST-PFM-LLM-006, TST-PFM-LLM-025, TST-PFM-LLM-074] --- # Explain an AI refusal or unsuccessful conversation ## Purpose Give support a decision-time explanation and a separate check of what would happen now. ## How It Works Staff open the explanation for a problem request. For a refusal, Platform starts with the stored policy decision and arithmetic. It resolves the referenced capacity grants without replacing the original figures with current ones. A second part describes changes since the refusal and checks present admission without reserving credits. Older records receive a more limited explanation when no decision snapshot exists. Failed conversations show their attempts and retry outcomes, and bounded conversations identify the limit reached. A healthy settled request has no refusal or failure explanation to open. The explanation contains operational evidence without opening a prompt or response. ## Relationships - Admit AI work against the organization’s monthly allowance supplies the prerequisite behavior for this outcome. - Bound AI conversations and handle recoverable failures supplies the prerequisite behavior for this outcome.