--- id: CAP-PFM-LLM-018 title: Give people understandable AI refusal messages feature: FEAT-PFM-LLM-06 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: - 'services-platform:docs/proposals/llm-observability/11-decisions.md#11.1 Settled by inspection (reported)' purpose: Translate AI refusal classifications into customer language and recognizable next steps. outcomes: - 'Refusal wording explains waiting, retrying or contacting support.' - 'Customer wording excludes provider, model, money and internal control details.' concepts: - CON-PFM-LLM-001 - CON-PFM-LLM-003 actors: - ACT-PFM-032 - ACT-PFM-007 surfaces: - console - api preconditions: [] postconditions: [] permissions: [] rules: - id: BR-CAP-PFM-LLM-018-01 proved_by: [ATS-PFM-LLM-001-18, ATS-PFM-LLM-017-11, ATS-PFM-LLM-018-01, TST-PFM-LLM-085] statement: >- Allowance-refusal wording explains that the period’s AI allowance is used and that AI resumes next month or sooner through support-provided capacity. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#tells an organization that has used its allowance when it resumes origin: none - id: BR-CAP-PFM-LLM-018-02 proved_by: [ATS-PFM-LLM-018-01, TST-PFM-LLM-085] statement: >- Concurrency-refusal wording asks the person to wait a few seconds because too many organizational AI requests are running. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#asks an organization with too many requests running to try again in a few seconds origin: none - id: BR-CAP-PFM-LLM-018-03 proved_by: [ATS-PFM-LLM-018-01, TST-PFM-LLM-085] statement: >- Disabled-feature wording says the organization’s AI feature is off and directs the person to Rhythm support for enablement. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#tells an organization with a feature turned off to ask Rhythm support origin: none - id: BR-CAP-PFM-LLM-018-04 proved_by: [ATS-PFM-LLM-018-01, TST-PFM-LLM-085] statement: >- The helper gives provider unavailability and the declared circuit-open refusal the same temporary-service message, although a circuit breaker is not implemented. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#says the same for an open circuit, because the organization cannot tell them apart origin: none - id: BR-CAP-PFM-LLM-018-05 proved_by: [] statement: >- Operator faults such as missing configuration or depleted provider credit receive no specialized customer sentence. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#has no sentence for a fault that is an operator’s to read about origin: none - id: BR-CAP-PFM-LLM-018-06 proved_by: [ATS-PFM-LLM-018-02, TST-PFM-LLM-085] statement: >- Customer sentences use organization language and avoid internal money, model, provider and override terminology. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#names a tenant, money, a model, a provider or an override in none of them origin: 'services-platform:docs/proposals/llm-observability/11-decisions.md#11.1 Settled by inspection (reported)' - id: BR-CAP-PFM-LLM-018-07 proved_by: [ATS-PFM-LLM-008-13] statement: >- The pause email shares the customer pause sentence, substituting the organization’s name for the direct customer address. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#quote the same at-limit words, the notice naming the organization where the console says "your" origin: none - id: BR-CAP-PFM-LLM-018-08 proved_by: [ATS-PFM-LLM-018-03] statement: >- Describe With AI displays allowance-refusal wording using a reset day supplied by the refusal or a next-month fallback. kind: policy enforced_at: - console must_prove: true provenance: observed source: 'react-console:lib/api/generate-query.ts:allowanceMessage' origin: none - id: BR-CAP-PFM-LLM-018-09 proved_by: [] statement: >- Credit figures use thousands separators and date formatting uses day and month with a year where the message supplies one. kind: policy enforced_at: - service must_prove: false provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts' origin: none - id: BR-CAP-PFM-LLM-018-10 proved_by: [] statement: HQ presents refusal reasons as readable labels or sentences instead of raw classifications. kind: policy enforced_at: - console must_prove: false provenance: test source: 'react-console:lib/hq/ai-usage-format.test.ts#says a refusal code in words and never as the token' origin: none scenarios: - id: SC-CAP-PFM-LLM-018-01 given: The organization has used its current allowance. when: A person submits another AI request. then: The proposed customer explanation gives the reset date and the option of support granting capacity. provenance: documented source: 'services-platform:docs/milestones/plans/PLAT-M1-plan.md#3. How it works for the user' edge_cases: [] constraints: - Exact customer wording remains subject to approval of the proposed plan. depends_on: - CAP-PFM-LLM-001 related: - CAP-PFM-LLM-008 - CAP-PFM-LLM-017 journeys: - JNY-PFM-LLM-001 open_questions: [] evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (What an organization sees); docs/milestones/plans/PLAT-M1-plan.md (§3, A12, S18); docs/proposals/llm-observability/11-decisions.md (11.1 Vocabulary); modules/llm/services/usage/usage-sentences.ts; tests unit/services/usage/usage-sentences.spec.ts. - >- react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: lib/api/generate-query.ts (allowanceMessage, generateCodeMessage; owned by the query layer and cited as the place the sentence is shown); lib/hq/ai-usage-format.ts and its test. controls: [TC-AVL-001, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, 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-06-01, FAS-PFM-LLM-06-02, FAS-PFM-LLM-06-03, FAS-PFM-LLM-06-04, FAS-PFM-LLM-06-05] suites: [TST-PFM-LLM-085] --- # Give people understandable AI refusal messages ## Purpose Translate AI refusal classifications into customer language and recognizable next steps. ## How It Works The usage-message helper supplies customer sentences for allowance, concurrency, disabled-feature and service refusals. Allowance messages identify when AI can resume and point to support for more capacity. Brief concurrency limits ask the person to retry. Disabled features direct the person to support instead of suggesting renewal will turn them on. Operator configuration problems have no dedicated customer sentence. Describe With AI uses its console error adapter to display allowance wording, while HQ renders request reasons in words. Notice content shares the pause sentence with the customer helper. The product should verify each console refusal path because helper tests alone do not prove what every screen displays. ## Relationships - Run AI requests with consistent attribution and accounting supplies the prerequisite behavior for this outcome.