Add payer appeals-letter app (Aayush Mishra)

[aayushmishraaa]

Aayush Mishra

An API-driven app that drafts insurance appeal letters from a denial reason and a clinical fact, routed through human approval before anything is exported. A reviewer types one fictional denial reason and one clinical fact; the drafted letter addresses that denial using that fact, and nothing leaves the app unreviewed.

Built for the SuperDocs engineer task.

---

Verified against the live API

Input: CARC 197 — prior authorisation absent + "Prior authorization PA-2026-8823 was obtained on 2026-02-19 and was valid on the date of service."

Output: "This determination should be reconsidered because prior authorization PA-2026-8823 was obtained from the payer on 2026-02-19 and was valid on the date of service, directly addressing the stated denial reason."

Held at HITL, exported as .docx only after review.

The part worth reading: app/grounding.py

A model given a denial reason and a clinical fact writes a fluent appeal letter whether or not the fact answers the denial — and when they don't match, it bridges the gap by inventing clinical detail. In a payer appeal that isn't a bad user experience; it's a false statement submitted to an insurer over a clinician's name.

So relevance is checked before drafting, and the verdict is shown to the reviewer before they read a word.

When the fact doesn't fit, the app still drafts — refusing would just push the user to write it by hand with no warning at all — but drafts honestly. Given a prior-auth denial and a fact about seasonal allergies, it produced:

"Please note that the documentation directly addressing the prior authorization requirement is not enclosed with this letter."

No invented rebuttal. It also flags concrete specifics (numbers, dates, dosages) that appear in the letter but in none of the inputs — a payer will verify each one.

The gate is real

• Export returns 409 while any decision is outstanding
• The several approval rounds a large edit produces are surfaced, rather than letting a reviewer believe they've seen the whole letter
• In a live run of 4 changes with 3 approved and 1 rejected, the exported .docx still carries the untouched placeholder for the rejected section — the rejection is visible in the artefact, not only in a log

SuperDocs surfaces used

chat/async with approval_mode: ask_every_time · jobs/{id} polling · chat/{session}/approve · documents/export · sessions/{id}/jobs for recovering a wedged session.

The letter starts from a template document rather than being generated from nothing — appeal letters have a house format a compliance team already approved, and starting from a document means targeted edits on named sections.

Notes

Everything is fictional; the UI says so in a banner that doesn't dismiss. Limitations are stated plainly in the README — in-memory drafts, a deliberately coarse relevance check, and one fact per appeal.