Skip to main content

Recommendation Output Contract

This is the locked V1 recommendation output contract for IED.

Use this as the source of truth for:

  • the canonical recommendation results route
  • the canonical next-step route
  • required recommendation outputs
  • explanation and suitability requirements
  • low-confidence fallback behavior
  • what the recommendation does not promise in V1

Canonical Routes​

The canonical V1 recommendation routes are:

  • /results Recommendation output
  • /next-step Quote-path selection

/results stays focused on understanding the recommendation.

/next-step stays focused on choosing what to do next.

If these surfaces are ever merged later, that is a later product decision and not part of the V1 contract.

V1 Recommendation Shape​

The V1 recommendation must provide:

  • suggestedSystemSize Homeowner-facing guidance, not a formal design
  • batteryRecommendation One of:
    • yes
    • optional
    • not_needed
  • estimatedSavingsRange Guidance range only
  • generalPriceRange Guidance range only
  • suitabilityNote Plain-language suitability/confidence statement
  • reasoningSummary Plain-language explanation of why the recommendation was produced
  • nextStepRecommendation Plain-language guidance on what the user should do next before choosing a quote path

Output Semantics​

V1 recommendation results are:

  • educational
  • decision-support oriented
  • suitable for helping the homeowner understand likely fit

V1 recommendation results are not:

  • a formal quote
  • an installer system design
  • a guaranteed savings promise
  • a detailed pricing breakdown

Use guidance ranges, not quote-like precision.

Battery Recommendation​

The V1 battery recommendation uses a three-state model:

  • yes
  • optional
  • not_needed

This should remain plain-language and easy for homeowners to understand.

Do not turn battery output into a detailed battery sizing tool in V1.

Suitability And Confidence​

Every recommendation result must include:

  • a suitabilityNote
  • a reasoningSummary

V1 confidence presentation rules:

  • use simple plain-language suitability/confidence notes
  • do not introduce a numeric score
  • do not add an overbuilt confidence system

Low-Confidence Behavior​

If the system cannot make a strong recommendation in V1:

  • still show limited guidance if possible
  • soften the recommendation framing
  • direct the user toward manual review or contact
  • do not hard-block results unless there is no usable output at all

Low-confidence cases should degrade gracefully rather than fail hard.

Contract Boundaries​

These do not belong inside the recommendation output contract:

  • selectedPath Belongs after results on /next-step
  • lead lifecycle status Belongs in admin/backend workflow
  • installer assignment Belongs in routing and operations
  • detailed pricing breakdown Outside the V1 recommendation output

Next-Step Route Ownership​

/next-step handles quote-path choice.

V1 options:

  • compare quotes
  • recommended installer

This route should exist separately from /results in V1 so the recommendation surface remains focused on understanding the output first.

Validation Scenarios​

The model should support these scenarios:

  • a normal supported user receives all core outputs on /results
  • battery output can be yes, optional, or not_needed
  • savings and price are expressed as guidance ranges, not precise quotes
  • every result includes a plain-language explanation
  • every result includes a suitability/confidence note
  • a low-confidence case still produces limited guidance and a manual-review direction
  • /next-step handles path selection separately from /results
  • selectedPath is not part of the recommendation output contract
  • recommendation output remains distinct from installer assignment and lead lifecycle state