Skip to main content

📘 UX-CLAIMS-DISPUTES.md

This document specifies UX patterns for Claims & Disputes in Evalium.

Goal:

  • keep contested-result workflows operationally simple
  • preserve legal/audit defensibility
  • prevent ambiguous or non-reproducible decisions

Capability Baseline (Validated 2026-02-25)​

Backend-live now:

  • Claims API: list/get/create, event append, ratification.
  • Disputes API: list/get/create, event append, ratification.
  • Event-led lifecycle and status derivation are live.
  • Verification/context policy enforcement and step-up integration are live.
  • Idempotency-key enforcement is live on create/event/ratify writes.

Current workflow gap:

  • End-to-end product UX for claims/disputes is not yet first-class in frontend.

Implication:

  • This doc defines the first-class UX contract to activate existing backend primitives without inventing new truth models.

0. Doctrine (MUST)​

  1. Claim/Dispute is evidence-first: every assertion or challenge is linked to a defensible source.
  2. Event history is canonical: lifecycle is append-only; no destructive edits.
  3. Status is derived from events/rules: UI must not allow manual status mutation outside defined actions.
  4. High-assurance actions are explicit: ratification requires step-up and visible confirmation copy.
  5. Cross-surface continuity: claims/disputes must deep-link to submissions, findings, and ledger context.

0.1 Claims/Disputes Interface Guardrails (MUST)​

  • All lifecycle actions append events; no UI path may imply destructive edit of prior events.
  • Legal/defensibility states must be presented with deterministic labels and explicit timestamped context.
  • Ratification and other high-assurance actions must include step-up UX and clear irreversible-impact messaging.
  • Evidence/source references must be linkable and accessible via keyboard and screen reader.
  • Mobile/iPad supports filing, viewing, and basic response actions; deep legal review workflows may be desktop-optimized with explicit handoff.
  • Error handling must distinguish validation, policy, and permission failures with actionable next steps.

1. Core Domain Semantics (UX Contract)​

1.1 Claims​

A Claim is a professional assertion bound to:

  • a subject (subjectId)
  • a claim type + statement
  • one or more sources:
    • submissionId
    • submissionItemId
    • ledgerEventId

Claim event types:

  • asserted
  • amended
  • withdrawn
  • voided
  • note
  • ratified (via ratify endpoint)

Claim validity semantics:

  • validFrom, optional validUntil
  • computed validityStatus: future / active / expired
  • list filter supports validAt

1.2 Disputes​

A Dispute is a formal challenge targeting exactly one of:

  • claimId
  • submissionId
  • submissionItemId

Dispute event types:

  • opened (system-generated on create)
  • challenge
  • response
  • resolution
  • withdrawn
  • note
  • ratified (via ratify endpoint)

Dispute status semantics:

  • initial open
  • resolution event -> resolved
  • withdrawn event -> withdrawn

Implementation note:

  • default list behavior hides withdrawn disputes unless explicitly filtered.

2. Information Architecture​

Primary pages:

  1. Claims Hub (/claims)
  2. Claim Detail (/claims/:id)
  3. Disputes Hub (/disputes)
  4. Dispute Detail (/disputes/:id)

Context drawers (read-only peek on drawer-enabled surfaces):

  • Subject
  • Related submission/submission item
  • Related finding/ledger event (where linked)

Primary assets and edit/deeper workflows (full page):

  • Claim
  • Dispute
  • Submission

3. Claims UX​

3.1 Claims Hub (List)​

Columns (minimum):

  • Claim type
  • Statement (truncated)
  • Subject
  • Status
  • Validity status (future/active/expired)
  • Valid from / until
  • Created at
  • Created by

Filters:

  • subjectId
  • actorUserId
  • claimType
  • status
  • validAt

Actions:

  • Create claim
  • Open detail

3.2 Create Claim (Wizard or Modal)​

Required fields:

  • Subject
  • Claim type
  • Statement
  • At least one source reference

Optional fields:

  • Status override (advanced; default to asserted behavior)
  • Valid from / valid until
  • Authority/context metadata

Validation rules (MUST):

  • validUntil must be after validFrom
  • each source must reference at least one of submission/submission-item/ledger-event
  • idempotency key attached on submit

3.3 Claim Detail​

Sections:

  1. Claim Summary
  2. Sources
  3. Event Timeline
  4. Validity Window
  5. Ratification Panel

Timeline composer actions:

  • Amend
  • Add note
  • Withdraw
  • Void

Each timeline event shows:

  • event type
  • timestamp
  • actor
  • message
  • context metadata indicator (if present)

4. Disputes UX​

4.1 Disputes Hub (List)​

Columns (minimum):

  • Dispute ID
  • Target type (claim/submission/item)
  • Target reference
  • Reason (truncated)
  • Status
  • Updated at
  • Created by

Filters:

  • subjectId
  • claimId
  • submissionId
  • submissionItemId
  • status

Actions:

  • Open dispute
  • Create dispute

4.2 Create Dispute​

Required fields:

  • Exactly one target (claim OR submission OR submission item)
  • Reason

Optional:

  • Subject
  • Context/metadata

Validation rules (MUST):

  • enforce one-target-only selector in UI
  • idempotency key attached on submit

4.3 Dispute Detail​

Sections:

  1. Dispute Summary
  2. Target Context
  3. Event Timeline
  4. Ratification Panel

Timeline composer actions:

  • Challenge
  • Response
  • Resolution
  • Withdraw
  • Note

Validation rules (MUST):

  • dispute event message is required for challenge/response/resolution/withdrawn/note
  • idempotency key attached on event submit

5. Ratification UX (Claims + Disputes)​

Ratification is a high-assurance action and must use a dedicated flow.

5.1 Ratify Action Contract​

Required:

  • step-up method
  • step-up token

Optional:

  • stateHash
  • comment
  • verified-at timestamp

UX requirements:

  • explicit high-stakes confirmation copy
  • display reason/comment box
  • clear error for missing step-up (step_up_required)
  • idempotency key attached on ratify submit

5.2 Ratification Result​

On success:

  • show immutable ratified event in timeline
  • show returned status payload (ratified)
  • show who/when details

6. Cross-Linking & Explainability​

6.1 Linking Rules​

Claims/disputes must link to:

  • related submission detail
  • related submission item context
  • related ledger/finding anchor where present

Observation linkage:

  • where findings are present, use finding/ledger references to anchor claim/dispute rationale.

6.2 Evidence Basis Rule​

Claims/disputes are not stand-alone opinions in UI:

  • every claim/dispute view must surface source references prominently.
  • unresolved items without clear sources should be visually flagged for follow-up.

7. Status & State Language (Canonical)​

Claims:

  • status from backend claim status field
  • validity shown separately: future, active, expired

Disputes:

  • open, resolved, withdrawn

Do not merge validity and lifecycle into one badge.

8. Permissions & Safety​

Capability model:

  • read:
    • claims.read
    • disputes.read
  • write/manage:
    • claims.manage
    • disputes.manage

Rules:

  • hide mutating controls if manage capability is missing.
  • keep read surfaces visible if read capability exists.
  • preserve org/tenant RLS boundaries in all list/detail views.

9. Error, Retry, and Idempotency UX​

Writes covered:

  • create claim
  • add claim event
  • ratify claim
  • create dispute
  • add dispute event
  • ratify dispute

UX behavior:

  • attach Idempotency-Key on each write intent.
  • on replay, show deterministic success replay outcome.
  • on hash mismatch/key reuse, show conflict with “request already used for different payload.”
  • show structured validation errors inline (not raw backend strings).

10. Screen-Level Definition of Done​

Before enabling claims/disputes frontend:

  • Claim and dispute list pages with canonical filters are implemented.
  • Detail pages render timeline, sources/target context, and status chips.
  • Event composer enforces allowed event types and required message rules.
  • Ratification flow requires step-up and handles step_up_required cleanly.
  • Idempotency-key behavior is implemented on all mutating actions.
  • Links to submissions/finding anchors/ledger context are present.
  • RLS/capability gates are enforced in UI controls.
  • Accessibility and keyboard navigation verified for list/detail/drawer flows.

11. Navigation Contract Summary​

TaskPatternPrimary CTALink Contract
Review claimsTable + filtersOpen claimSubject/source peek drawers + claim full page
Create claimWizard/modalCreate claimSource links to submission/item/ledger
Evolve claim lifecycleTimeline composerAdd eventEvent audit trail inline
Review disputesTable + filtersOpen disputeTarget context peek + dispute full page
Progress disputeTimeline composerAdd response/resolutionSource and target links preserved
Ratify outcomeGuarded modalRatifyStep-up proof required