Rhythm 2.0 Specifications

Appearance

CAP-PFM-LLM-012Explain an AI refusal or unsuccessful conversation

Markdown

CAP-PFM-LLM-012

Explain an AI refusal or unsuccessful conversation

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-LLM-04
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
Key concepts
CON-PFM-LLM-001, CON-PFM-LLM-003
Actors
ACT-PFM-033, ACT-PFM-004
Journeys
JNY-PFM-LLM-002
Depends on
CAP-PFM-LLM-007, CAP-PFM-LLM-002
Related
CAP-PFM-LLM-011
Proved by
ATS-PFM-LLM-012

Implementation

Executable suites
TST-PFM-LLM-006, TST-PFM-LLM-025, TST-PFM-LLM-074

KindCapabilityProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

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.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
A refusal explanation uses its recorded admission figures.Failed requests expose attempt-level verdicts.A current comparison shows whether capacity changes affect admission.
Surfaces
consoleapi
Preconditions
The request has a refusal or error outcome.
Postconditions
Explanation does not reserve credits or charge the organization.

Controls

32 controls apply, from the corpus control catalogue.

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

Permissions

KeyChecked atScope
hq.llm-usage.readapiglobal

Business Rules

9 rules, 6 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Only Rhythm staff with the HQ AI usage read key can obtain explanations through the HQ route.
proved by ATS-PFM-LLM-012-01, TST-PFM-LLM-006
permissionapitest
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
02must prove
Proposed
Refusal explanations preserve the recorded policy and decision-time figures and describe allowance arithmetic, concurrency or the disabled switch without recomputing history.
proved by ATS-PFM-LLM-011-09, ATS-PFM-LLM-012-02, TST-PFM-LLM-025
policyserviceobserved
services-platform:modules/llm/services/explain/explain-invocation.ts
03must prove
Proposed
Referenced capacity grants are resolved with their windows, and an unreadable reference remains visible as not found.
proved by ATS-PFM-LLM-012-03, TST-PFM-LLM-025
policyservicetest
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
04must prove
Proposed
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.
proved by ATS-PFM-LLM-007-15, ATS-PFM-LLM-012-04, ATS-PFM-LLM-012-08, TST-PFM-LLM-025
calculationservice, databaseobserved
services-platform:modules/llm/services/explain/explain-invocation.ts
05
Proposed
An older refusal without a snapshot uses the retained request fields and its estimate for the current admission check.
policyservicetest
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
06must prove
Proposed
Failure explanations present classification, ending and ordered attempts with status, error, latency and retry verdict, including a truncation warning when appropriate.
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
calculationserviceobserved
services-platform:modules/llm/services/explain/explain-invocation.ts
07
Proposed
A limit-ending explanation identifies the exhausted limit and the value recorded in the operation’s routing version.
policyserviceobserved
services-platform:modules/llm/services/explain/explain-invocation.ts
08must prove
Proposed
A healthy settled request is rejected as having nothing to explain, while missing and foreign requests return not found.
proved by ATS-PFM-LLM-012-06, TST-PFM-LLM-006, TST-PFM-LLM-025
validationservice, apiobserved
services-platform:modules/llm/services/explain/explain-invocation.ts
09
Proposed
Explanation reads do not open captured content or disclose its storage reference.
invariantservicedocumented
services-platform:docs/llm.md#Explaining a refusal

Scenarios

IdGivenWhenThenProvenance
01A recorded refusal is followed by capacity grants.Support requests its explanation.The response keeps refusal facts and lists later grants alongside a current comparison.test
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
02The HQ detail contains a refused request.The explanation panel renders.Its three sections and evidence statuses appear without captured bodies.test
react-console:e2e/mock/hq-ai-usage.mock.spec.ts#a refused request explains itself in three blocks, and shows evidence statuses without content

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software