Skip to content

ADR-003: LLM rationale fallback

Status: Accepted Source: prd.md §19

Context

The LLM call that produces the recommendation rationale (rationale_text) may fail or exceed the latency budget mid-demo. A blank rationale tile is unacceptable — the executive sees a rationale field on every recommendation and an empty value reads as broken software.

Decision

If rationale_text is empty after a 2s timeout, generate from a deterministic template:

1
"{action_label} is recommended because: {top_3_reason_codes_humanized}."

The template draws on the deterministic scorer (ADR-002 / PRD §10.x), which always has reason codes available because they're computed before the LLM call.

Consequences

  • The rationale tile is always populated. Sub-2s latency from the templated path keeps the demo flow tight.
  • The templated string is visibly less polished than a real LLM rationale — acceptable degradation for a demo failure path.
  • This ADR is not the same shape as ADR-008's widget Clarifier discipline. The decision-rationale path uses a deterministic templated fallback as a feature; the widget Clarifier in live mode raises an explicit error rather than silently producing a mock spec. The two paths have different UX requirements.

Cross-references