Functional requirements

Ten product contracts covering the valid path, exceptions, service boundaries and recoverability.

Product decision
A claim advances only when the evidence for its next state is complete.

Document type

Functional requirements

Status

Portfolio sample · written from my healthcare claims experience

Product decision

A claim advances only when the evidence for its next state is complete.

Portfolio sample from my healthcare product experience. Requirements, thresholds and review records are illustrative; they are not employer documents or historical sign-offs.

In this document 6 sections

Product and interface contract

The sample centers on a medical-claims intake product. The provider API supplies a resolution result; the receiving claims system retains adjudication authority. The platform replay requirement applies to the separate migration example.

1. a medical-claims intake product
2. The provider API supplies a resolution result
3. the receiving claims system retains adjudication authority

The platform replay requirement applies to the separate migration example.

Detailed functional requirements

Each requirement includes a positive path and a defined exception. IDs connect to the BRD, test cases and release gates.

ID / capability	Given	When	Then
FR1 · Supported forms	A complete CMS-1500 or UB-04 source is received	The intake service classifies it	Create a traceable claim record and select the professional or institutional mapping; quarantine unsupported or unreadable forms.
FR2 · Extraction & correction	A required field is missing, uncertain or inconsistent with the source	An authorized operator reviews the candidate	Display the source beside the field; record the correction and revalidate before the claim can advance.
FR3 · Normalization	A name or address uses different casing, spacing or standard abbreviations	The provider request is normalized	Retain original and normalized values with the transformation version; preserve substantive identity and unit/location distinctions.
FR4 · Provider resolution	The authorized central source has current, uniquely supported provider evidence	The API resolves the request	Return the matched provider reference, evidence version and reason; return distinct missing, no-match, ambiguous or stale statuses otherwise.
FR5 · EDI validation	A complete reviewed claim has resolved required provider evidence	The applicable 837P or 837I transaction is generated	Validate against the applicable implementation and receiver contract; block invalid transactions and return an actionable field-level reason.
FR6 · Adjudication handoff	A validated claim is authorized for the receiving adjudication system	The transaction is submitted and acknowledged	Persist submission and acknowledgement separately; update final disposition only from the receiving system’s adjudication result.
FR7 · Retry & duplicate protection	A request times out or is repeated with the same processing identity	The service checks status or retries	Preserve identity, inspect known receiver status and prevent an unintended second claim submission; do not treat silence as failure.
FR8 · Replay & reconciliation	An authorized migration comparison replays a bounded inventory	Old and new outputs are compared	Keep live submission isolated from comparison; account for every record and explain discrepancies before a cutover recommendation.
FR9 · Authorization & audit	An actor requests claim access, correction or export	Their identity and permissions are evaluated	Allow only the permitted operation and record the action; deny unauthorized access without exposing protected values in errors or logs.
FR10 · Exception ownership	A claim is held, rejected or awaiting a confirmed result	Operations opens the exception queue	Show current state, reason, accountable queue and age; a resolved correction re-enters validation with its source history intact.

Provider API response contract

These are public sample response semantics; production endpoints and proprietary mappings are omitted.

Result	Required response	Permitted next action
MATCHED	Provider reference, source/version, lookup time and match reason	Advance only if all required claim fields are valid.
MISSING_DATA / NO_MATCH	Missing evidence or no supported candidate, with a reason	Request correction or assign review. Do not fabricate the missing name.
AMBIGUOUS	Conflicting candidate evidence without automatic selection	Authorized resolution with a recorded rationale.
SOURCE_STALE / UNAVAILABLE	Source health/freshness status and traceable request identity	Hold or controlled retry; an old result cannot silently become current.

Data, states and audit

Keep intake identity, source reference, original/extracted/corrected values, provider resolution, validation version, current state, timestamps and actor/reason history. Reporting uses the latest mutually exclusive state plus the event history; it does not count each handoff as another completed claim.

1. Keep intake identity, source reference
2. provider resolution, validation version, current state timestamps and actor/reason history
3. Reporting uses the latest mutually exclusive state plus the event history it does not count each handoff as another completed claim

Acceptance examples for provider ambiguity

Given two plausible providers at a normalized address, when lookup completes, then return AMBIGUOUS and retain the unresolved claim. Given an absent provider name and other insufficient identifiers, when lookup is attempted, then return MISSING_DATA. A normalization rule cannot create identity evidence.

1. two plausible providers at a normalized address
2. return AMBIGUOUS and retain the unresolved claim
3. an absent provider name and other insufficient identifiers
4. return MISSING_DATA A normalization rule cannot create identity evidence

Performance and recovery acceptance

For this sample contract, test provider resolution at 50 requests/second with p95 response time ≤500 ms; report cache-hit and source-query paths separately. Inject a timeout and replay the same request identity to verify that a second live claim is not emitted. These are proposed acceptance targets, not historical production measurements.

CMS: professional claims and CMS-1500 ↗ · CMS: institutional CMS-1450 / 837I ↗ · CMS: adopted transaction standards ↗

1. test provider resolution at 50 requests/second with p95 response time ≤500 ms
2. report cache-hit and source-query paths separately
3. Inject a timeout and replay the same request identity verify that a second live claim is not emitted

These are proposed acceptance targets, not historical production measurements.