Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sputhenofficial/claimjumper/llms.txt

Use this file to discover all available pages before exploring further.

draft() in lib/pipeline/draft.ts accepts a DraftInput (full parsed claim + service line + triage decision) and a model client, then produces a DraftArtifact. For appeal and corrected_claim lanes it calls GPT-5.6 Terra and then validates every citation in the response before the artifact is returned. For human_review it generates a deterministic plain-text brief without any model call. For patient_bill and write_off it throws immediately — those lanes never receive drafted artifacts and the route handler catches that error gracefully.

​
Function signature

export async function draft(
  input: DraftInput,
  model: DraftModelClient,
): Promise<DraftArtifact>
DraftModelClient is a type alias for the exact shape of responseWithTextSchema from lib/openai.ts: 
export type DraftModelClient = (
  model: string,
  systemPrompt: string,
  input: string,
  schema: typeof DraftModelOutputSchema,
  options: { effort: "medium" },
) => Promise<DraftModelOutput>;
Passing the client as an argument rather than importing it directly creates a seam for testing: a fixture function that returns a pre-built DraftModelOutput can substitute for the live OpenAI call.

​
adaptForDrafting()

The route handler uses adaptForDrafting() to assemble a DraftInput from the three sources it has in scope. This join helper parses the assembled object through DraftInputSchema, catching any structural problem before it reaches the model: 
export function adaptForDrafting(
  claim: DraftInput['claim'],
  serviceLine: DraftInput['service_line'],
  triage: DraftInput['triage'],
): DraftInput
DraftInput intentionally carries the full ClaimSchema object rather than the leaner AdjustmentLine used in triage. Draft citations reference nested fields such as claim.remittance.code_legend and claim.claim.claim_id, which are not present in the adjustment-line projection.

​
validateCitations()

export function validateCitations(input: DraftInput, citations: readonly DraftCitation[]): void
After the model responds, draft() calls validateCitations() on every citation in the output before constructing the DraftArtifact. A citation carries a source ("parse" or "legend"), a field_path, and a value. Validation resolves each citation against the original DraftInput and checks that the resolved value matches the cited string exactly. Parse citations — field_path is a dotted property path from the DraftInput root (e.g. claim.claim.claim_id or service_line.group_code). The resolver walks the path using Object.hasOwn checks for objects and numeric index parsing for arrays. Legend citations — field_path follows the pattern CODE_SYSTEM:CODE.field (e.g. CARC:50.definition or RARC:N115.definition). The resolver locates the matching entry in claim.remittance.code_legend by code_system and code, then reads the named field. If a path does not resolve, or if the resolved value does not match citation.value exactly (as a string), validateCitations() throws an error. This prevents the artifact from being returned to the caller, ensuring that every factual claim in a draft can be traced back to a verified remittance field.

​
validateArtifact()

After citations are verified, draft() calls validateArtifact(), which enforces three content safety rules on the draft body: Prohibited submission phrases — a regex match for language that implies automated action. Phrases such as "we have submitted", "this appeal has been filed", and "approved" are blocked because they misrepresent the draft’s status as a human-review work product. 
const PROHIBITED_PHRASES =
  /\bwe\s+have\s+(?:submitted|filed|appealed)\b|\b(?:this\s+)?appeal\s+has\s+been\s+(?:submitted|filed)\b|\bapproved\b/i;
Denial codes required in body — for appeal and corrected_claim drafts, the group code, CARC, and RARC (when present) must each appear literally in the body text. A draft that omits the denial codes that drove the routing is considered incomplete. CARC 50 medical necessity assertion prohibition — for appeal drafts where carc === "50", the body may not make any of the following assertions: 
export const CARC_50_MEDICAL_NECESSITY_ASSERTIONS = [
  /medical\s+necessity\s+(?:is|was|has\s+been)\s+(?:established|demonstrated|proven)/i,
  /(?:record|documentation)\s+(?:meets|satisfies|establishes|demonstrates)\s+(?:the\s+)?(?:lcd\s+)?criteria?/i,
  /(?:criterion|criteria)\s+(?:is|are|was|were)\s+met/i,
  /meets\s+(?:an?\s+|the\s+)?(?:lcd\s+)?criterion/i,
];
These patterns cover assertions of proof specifically — they do not block quoting the payer’s denial language or making a procedural request for criterion identification, which the prompt explicitly permits.

​
Human-review brief

When the lane is human_review, draft() calls the internal reviewBrief() function instead of the model. reviewBrief() builds a deterministic plain-text brief from the claim, service line, and triage result — no model call, no citations to validate: 
HUMAN REVIEW REQUIRED — Review Brief (not submission-ready)
Claim: {claim_id}; Patient: {patient_name}; Line: {line_number}
Service: {service_date}; Procedure: {procedure_code}; Denial: {group_code} / CARC {carc} / RARC {rarc}
Rationale: {rationale}
Evidence needed: {evidence_needed joined by " | "}
Overrides:
- {override reason 1}
- {override reason 2}
reviewBrief() still runs validateArtifact() on the generated content to ensure no prohibited phrase was accidentally introduced by a triage rationale or evidence string. The resulting DraftArtifact has citations: [] and a lane of "human_review". It cannot be approved or exported by the UI.

​
Prompt design

The draft prompt at prompts/draft.md gives the model a focused lane-specific drafting role with strict grounding constraints. The key lane rules:
  • appeal with CARC 29 — reference service_date, claim_received_date, and the clearinghouse-acknowledgment date in notes. Request review of timely filing.
  • appeal with CARC 50 and RARC N115 — make a procedural request only. Quote the supplied CARC and RARC definitions. Ask the payer to identify the specific LCD and criterion. Do not assert medical necessity, any patient condition, or that any criterion was met.
  • corrected_claim with CARC 16 and RARC M51 — produce a worklist naming the exact fields to correct. Do not use appeal language.
The citation rules require every factual statement in the body to be backed by a citation, with citation.value matching the source field’s canonical string value exactly. The grounding constraints are: 
Constraints:
- Include the exact group code, CARC, and any RARC in body.
- Never invent facts, policy numbers, dates, LCD identifiers, or clinical facts.
- Never claim that this appeal was submitted, filed, or approved. Factual
  references to the original claim's timely-filing history are allowed.
- This is a draft for human review; do not imply automated action.
Drafts produced by ClaimJumper are not filing-ready forms. Before using any artifact, a billing team member must verify payer-specific requirements, supporting records, signer information, deadlines, and submission instructions. ClaimJumper never submits, files, emails, or otherwise transmits anything to a payer.

Build docs developers (and LLMs) love

Get started for freeTalk to us