@agenticmail/core 0.9.32 → 0.9.34

package/dist/skills/built-in/detect-fake-escalation-loops.json

@@ -0,0 +1,140 @@
+{
+  "id": "detect-fake-escalation-loops",
+  "name": "Detect and Bypass Fake Escalation Loops",
+  "version": "1.0.1",
+  "category": "customer-service",
+  "tags": [
+    "escalation",
+    "anti-pattern",
+    "phone-call",
+    "transfer-loops",
+    "ghost-callbacks",
+    "stall-detection",
+    "customer-support"
+  ],
+  "description": "Spot the patterns that tell you you're not actually being escalated — transfers that loop you back to the same queue, callbacks that never come, 'tickets' that don't exist in any system. Then bypass them rather than burn another hour in the same maze.",
+  "disclaimer": null,
+  "context": {
+    "when_to_use": "You're on call #2 or #3 about the same issue, OR you've been transferred more than twice in one call, OR a promised callback hasn't materialized. This skill is about detecting the stall pattern and choosing the right counter-move, not about being paranoid on a first-time call.",
+    "preconditions": [
+      "User has at least one prior interaction (call, chat, or email) about the same issue.",
+      "User has tracked basic details: case numbers (if given), names of reps, dates, and what was promised.",
+      "User is willing to invest energy in pattern-detection rather than just plowing forward — this skill is slower upfront but saves hours."
+    ],
+    "estimated_call_duration_minutes": 20
+  },
+  "principles": [
+    "Loops are designed to wear you down without leaving an audit trail. The defense is the audit trail — name dates, case numbers, and prior promises explicitly on every call. Loops can't survive contact with documented history.",
+    "The five common stalls: (1) Hot-potato transfer — sent to another queue that sends you back. (2) Ghost callback — promise of return call that never happens. (3) Phantom ticket — case number that doesn't exist when you reference it next time, OR exists but with no notes. (4) Sympathy stall — long empathetic conversation that ends with no action. (5) Hold-out — repeated hold-and-check that runs your clock down.",
+    "Each stall has a tell. Hot-potato: rep can't articulate WHY this transfer is different from the last one. Ghost callback: rep won't give a specific time, just 'within 24-72 hours'. Phantom ticket: rep can't read back details. Sympathy stall: lots of 'I totally understand' but no 'here's what I can do'. Hold-out: hold durations escalating without new information.",
+    "When you detect a stall, the move is NOT to argue with the rep — it's to change your method. Same input, same output. You need different input: different channel, different rep, different framing, or different evidence.",
+    "Case numbers are the single best stall-defense. Always ask for one. Reference prior ones. A call that starts with 'I have case number XYZ from [date]' is harder to put into a loop than one that starts cold.",
+    "Decision point — every 10 minutes, ask yourself: 'In the last 10 minutes, has anything CHANGED — a new fact, a real escalation, a specific commitment with a date?' If no, you're in a loop. Exit the loop.",
+    "Some loops are unconscious — the company isn't deliberately stalling, the systems are just bad. Doesn't matter. The counter is the same."
+  ],
+  "phrases": {
+    "case_number_check": "Before we start, I want to give you context — case number [X] from [date] with [rep name]. Could you pull that up and read back what's noted?",
+    "test_the_transfer": "Before you transfer me — can you confirm exactly which team you're sending me to, and that they have authority to [specific action]? I've been bounced before and I want to make sure this is a real escalation, not another queue.",
+    "lock_the_callback": "If you can't help now, I need a SPECIFIC callback time — not a window. What hour, on what day, and from what number? And can you put your name and ID on the callback note?",
+    "verify_the_ticket": "Could you read me the case number you just opened, AND read back the first two lines of what's noted? I want to make sure my issue is captured before we hang up.",
+    "name_the_loop": "I want to flag something carefully — I've been transferred three times today and twice last week, all on the same issue, with no resolution and no callback. I'm not blaming you, but I need help breaking that pattern. Who in your org owns 'cases that have been escalated multiple times without resolution'?",
+    "stop_the_hold_loop": "Before you put me on hold again — let's confirm what you're going to check this time that's different from what you checked last time. If it's the same thing, the answer will be the same. Let's not waste either of our time.",
+    "the_evidence_close": "I'm going to stay on this call until we have either a resolution or a specific written commitment with a date. I know that's not fun for either of us — but I can't accept another 'we'll get back to you' without a name, a time, and a number.",
+    "channel_switch_signal": "I'm going to end this call and pursue this through a different channel. Could you confirm: your name, your ID, the case number, and your manager's name for my records?"
+  },
+  "tactics": [
+    {
+      "name": "Open with prior-case context",
+      "when": "First minute of every follow-up call about the same issue.",
+      "script": "Use `case_number_check`. Pre-loaded context disrupts the loop — reps can't pretend it's a fresh issue and start the script over. If they can't pull the case or claim it's not in the system, that's data point #1.",
+      "priority": 1,
+      "decision_point": "If the rep claims they can't find your prior case number — pause. Either (a) ask them to search by your phone or account, OR (b) treat the missing case as evidence of a phantom-ticket stall and ask explicitly: 'is this case in your system or not?' Don't just plow forward and let them open a new case — that resets your timeline."
+    },
+    {
+      "name": "Test the transfer before accepting it",
+      "when": "Rep offers a transfer.",
+      "script": "Use `test_the_transfer`. Reps doing a real transfer can name the team and confirm authority. Reps doing a hot-potato transfer waffle.",
+      "priority": 2,
+      "decision_point": "If the rep can't name the team or authority — REFUSE the transfer. Say: 'I'd rather not be transferred until we know that's the right place. Let me speak with your supervisor here first.' Refusing a transfer is a legitimate move; you don't have to accept every hold."
+    },
+    {
+      "name": "Lock down callback specifics",
+      "when": "Rep offers a callback instead of in-call resolution.",
+      "script": "Use `lock_the_callback`. Vague callback windows ('within 72 hours') are stall-friendly. Specific commitments ('Tuesday between 10-11am from 800-555-0143') are harder to silently drop.",
+      "priority": 3,
+      "decision_point": "If the rep refuses to give a specific time/number — that's a strong signal of a ghost-callback stall. Either insist on specifics or escalate. Don't accept the vague window — it's designed to make the missed callback unprovable."
+    },
+    {
+      "name": "Verify the ticket while still on the line",
+      "when": "Rep opens a new case or claims one is already open.",
+      "script": "Use `verify_the_ticket`. Phantom tickets exist (typo'd, opened under the wrong account, opened without notes). Catching it before you hang up saves 30 minutes on the next call.",
+      "priority": 4
+    },
+    {
+      "name": "Stop the hold-and-check loop",
+      "when": "Rep is going on hold for the second time on the same question.",
+      "script": "Use `stop_the_hold_loop`. The script says 'let me check'. Forcing the rep to articulate what they're checking — and how it differs from last time — collapses the stall.",
+      "priority": 5
+    },
+    {
+      "name": "Name the loop without accusation",
+      "when": "You've confirmed (via your own count) that you're in a documented pattern of unresolved escalations.",
+      "script": "Use `name_the_loop`. Most companies have a 'cases stuck in escalation' workflow or supervisor responsible for it — you just have to ask for it by function. The framing ('I'm not blaming you') keeps the rep on your side.",
+      "priority": 6,
+      "decision_point": "If the rep responds 'we don't have anyone who handles that' or 'that's not really a thing' — your suspicion is confirmed: this org has no exit ramp for loops. Time to switch channels (`multi-channel-escalation`) or go above (`reach-executive-office`)."
+    },
+    {
+      "name": "Refuse to disengage without commitment",
+      "when": "Rep tries to close the call with no resolution and no specifics.",
+      "script": "Use `the_evidence_close`. Saying it out loud — calmly — often produces a sudden escalation that 'wasn't available' five minutes earlier.",
+      "priority": 7
+    },
+    {
+      "name": "Signal the channel switch",
+      "when": "You've decided to exit this call.",
+      "script": "Use `channel_switch_signal`. Don't reveal which channel — just signal that the next contact will be elsewhere. This often produces a last-minute escalation as the rep realizes the case is escaping their queue.",
+      "priority": 8
+    }
+  ],
+  "boundaries": [
+    "Do NOT accuse the rep of lying. Even when they are stalling, calling it out destroys the recording's value to you.",
+    "Do NOT chain more than 2 transfers in one call. If you've been transferred twice and still not resolved, hang up and document — the third transfer is the loop confirming itself.",
+    "Do NOT accept callbacks without specific time, number, and a named person responsible. Generic callbacks ('someone will reach out') are designed to be undeliverable.",
+    "Do NOT skip taking notes during the call to 'save time'. The notes are the only thing that breaks the next loop. If you can't take notes, record (where legally permitted) — see `document-call-promises`.",
+    "Do NOT keep calling back to the same queue every day. Three calls without movement = wrong queue. Switch channels.",
+    "Do NOT bluff a deadline ('if you don't call me back by 5pm I'm filing a complaint') unless you'll actually follow through. Empty deadlines train the loop to ignore you."
+  ],
+  "success_signals": [
+    "Rep pulls up prior case + reads back accurate notes — case is real, history is intact.",
+    "Rep declines to do a transfer when challenged — and instead handles it themselves.",
+    "Rep gives a specific callback time + direct number + their personal name + ID.",
+    "Rep names a function ('our re-escalation supervisor') in response to the loop call-out.",
+    "Different sound profile (different hold music, no hold music, direct dial) — you've left the standard queue."
+  ],
+  "failure_signals": [
+    "Rep can't find your case number, OR finds it but can't read back notes.",
+    "Rep won't commit to specific callback time, OR keeps offering windows like 'within 24-72 business hours'.",
+    "More than two transfers in one call without escalation.",
+    "Rep deflects the 'who handles cases stuck in escalation' question.",
+    "Hold durations escalating (1min → 5min → 12min) without new information at the end of each hold.",
+    "Rep starts using closing scripts ('is there anything else…') as a soft hangup."
+  ],
+  "exit_strategy": {
+    "on_success": "Document precisely: time of resolution, rep name + ID, case number, specific commitment + date, written confirmation channel. Confirm in writing within 24h.",
+    "on_failure": "End the call with name + ID + case number captured. Switch channels immediately — do NOT call the same queue again. Use `multi-channel-escalation` (email + executive office + social) or `invoke-regulator-firmly` if the issue is regulator-eligible.",
+    "follow_ups": [
+      "Build a one-page timeline: every contact, date, rep, what was promised, what happened. This document is your weapon for the next escalation tier.",
+      "If callback window passed without contact: do NOT just call back to the queue. Use the timeline to escalate to executive office, social media, or regulator.",
+      "Note: many companies have a 'cases over 30 days' escalation flag. Reference the AGE of the issue in your next contact — 'this case has been open 47 days across 6 contacts' is significantly more powerful than 'I'm frustrated'."
+    ]
+  },
+  "required_user_info": [
+    "Complete history of prior contacts: dates, rep names, case numbers, what was promised",
+    "Original issue stated in one sentence",
+    "All callback promises that were missed (with dates)",
+    "Account identifier",
+    "Note-taking method ready (or recording where legally permitted)"
+  ],
+  "contributed_by": "support-escalator agent (v0.9.87 community drop)",
+  "updated_at": "2026-05-20T06:09:47Z"
+}

package/dist/skills/built-in/detect-lies-and-contradictions.json

@@ -0,0 +1,139 @@
+{
+  "id": "detect-lies-and-contradictions",
+  "name": "Detect Lies and Contradictions Mid-Call",
+  "version": "1.0.0",
+  "category": "other",
+  "tags": [
+    "meta-skill",
+    "adversarial-robustness",
+    "deception-detection",
+    "phone-call",
+    "evidence",
+    "critical-reasoning"
+  ],
+  "description": "Notice when what the rep just said contradicts (a) something they said two minutes ago, (b) something on the user's bill, (c) the company's own published policy, or (d) physical reality. Surface the contradiction without accusing — make the rep resolve it.",
+  "disclaimer": null,
+  "context": {
+    "when_to_use": "Layered over every customer-service, billing, retention, claims, or escalation call. Activate any time a rep makes a factual claim about the account, the policy, the timeline, or what 'has to' happen next.",
+    "preconditions": [
+      "Agent is keeping a running ledger of every factual claim the rep makes (claim, time, exact wording).",
+      "Agent has access to the user's source documents (bill, contract, prior emails) for cross-check.",
+      "Agent is prepared to ask the rep to repeat or clarify without sounding hostile."
+    ],
+    "estimated_call_duration_minutes": 5
+  },
+  "principles": [
+    "Track every factual assertion in working memory with a timestamp. You cannot detect a contradiction you didn't record.",
+    "Most 'lies' on customer-service calls are not lies — they are scripted approximations, junior-rep guesses, or stale internal training. Treat contradictions as information, not as malice.",
+    "Never accuse. Ask. 'Help me reconcile this' beats 'you just said the opposite' every time.",
+    "When the rep contradicts themselves, the SECOND statement is usually the corrected one — but the FIRST statement often reveals the real script. Note both.",
+    "A contradiction with the written record (bill, email, contract) is worth more than a contradiction within the conversation. Documents don't forget.",
+    "Silence after surfacing a contradiction is the strongest move. Let the rep resolve it; don't rescue them."
+  ],
+  "phrases": {
+    "log_claim_internally": "[Internal note] Rep said: '<exact words>' at <mm:ss>. Tag: <policy|fee|timeline|authority|identity>.",
+    "soft_surface": "I want to make sure I'm following — a minute ago I thought I heard <X>, and now it sounds like <Y>. Can you help me square those?",
+    "document_anchor": "On the bill in front of me dated <date>, it shows <Z>. How does that line up with what you just described?",
+    "ask_for_source": "Where in the policy is that written? I'd love to look at the exact language so I'm sure I understand.",
+    "request_replay": "Sorry — could you say that one more time, slowly? I want to write it down exactly.",
+    "park_and_proceed": "Okay, let's set that aside for a moment and come back to it. In the meantime, can we also look at <next item>?"
+  },
+  "tactics": [
+    {
+      "name": "Run a claim ledger",
+      "when": "From the first substantive sentence the rep speaks.",
+      "script": "After each rep claim, internally log: time, exact phrase, category. Do not paraphrase — paraphrasing loses the contradiction.",
+      "priority": 1
+    },
+    {
+      "name": "Cross-check against documents in real time",
+      "when": "Any claim about fees, dates, plan terms, or account history.",
+      "script": "Compare against the bill / contract / prior confirmation the user provided. If document and rep disagree, use `document_anchor`.",
+      "priority": 2
+    },
+    {
+      "name": "Soft-surface contradictions",
+      "when": "You catch a within-call contradiction.",
+      "script": "Use `soft_surface`. Tone is curious, not gotcha. Make it the rep's job to reconcile.",
+      "priority": 3
+    },
+    {
+      "name": "Ask for the source",
+      "when": "Rep cites 'policy' or 'system'.",
+      "script": "Use `ask_for_source`. Real policies have written text; invented ones do not. If the rep can't point to it, it isn't policy — it's their best guess.",
+      "priority": 4
+    },
+    {
+      "name": "Park and circle back",
+      "when": "Surfacing the contradiction risks derailing a still-productive call.",
+      "script": "Use `park_and_proceed`. Note the contradiction, keep moving on the primary goal, return to it before close."
+    }
+  ],
+  "alternative_interpretations": [
+    {
+      "observation": "Rep said the fee is $X, then later said it's $Y.",
+      "consider": [
+        "They mis-spoke once — most common.",
+        "They are reading two different screens (current bill vs. next bill cycle).",
+        "$X is the gross fee, $Y is after a promo credit — both true.",
+        "$X was a script default, $Y is the actual account — the second is usually right.",
+        "They are testing whether you'll notice."
+      ],
+      "next_action": "Ask the rep which number applies to the user's next statement, and ask them to read the line item back."
+    },
+    {
+      "observation": "Rep said 'we can't do that' but the company website says it's available.",
+      "consider": [
+        "Rep is genuinely unaware — front-line training lags marketing by months.",
+        "It's available, but not from this department — ask which team handles it.",
+        "It's available, but requires a tier of account the user doesn't have.",
+        "The website is stale.",
+        "Rep is gatekeeping to protect a metric (handle time, save rate)."
+      ],
+      "next_action": "Read the exact language from the page back to the rep. Ask them to check with a supervisor or transfer."
+    },
+    {
+      "observation": "Rep claims a policy that contradicts what a different rep said yesterday.",
+      "consider": [
+        "Policy genuinely changed between calls (rare in 24 hours).",
+        "One of the two reps invented an out — usually whichever was more convenient for the company.",
+        "Two different sub-policies apply and neither rep flagged which one.",
+        "Yesterday's rep made a one-time exception they had no authority to make."
+      ],
+      "next_action": "Ask for the policy in writing — case number, supervisor, or an email. Anchor to documents."
+    }
+  ],
+  "boundaries": [
+    "Do NOT call the rep a liar, even when you are sure. Frame everything as 'help me reconcile'.",
+    "Do NOT pretend you have a recording or written evidence you do not have.",
+    "Do NOT escalate hostility just because you caught a contradiction — caught contradictions are leverage; spent leverage is wasted.",
+    "Do NOT abandon the primary goal of the call to win a contradiction debate."
+  ],
+  "success_signals": [
+    "Rep corrects themselves voluntarily after you ask them to reconcile.",
+    "Rep escalates to a supervisor when challenged on policy source.",
+    "Rep agrees to send the relevant policy in writing.",
+    "Original ask becomes easier because the rep is now operating carefully."
+  ],
+  "failure_signals": [
+    "Rep doubles down on both contradictory statements as if neither was said.",
+    "Rep becomes hostile and starts threatening to end the call.",
+    "Rep refuses to provide policy in writing or via a supervisor.",
+    "Contradictions multiply — sign of an off-script improv that won't stabilize. Time to hang up and call back (see `reset-by-callback`)."
+  ],
+  "exit_strategy": {
+    "on_success": "Capture the reconciled answer in writing — confirmation number, supervisor name, or follow-up email. The reconciliation is the deliverable.",
+    "on_failure": "Politely end the call. Note all contradictions verbatim in the post-call report. Recommend callback to a different rep.",
+    "follow_ups": [
+      "File the claim ledger with the user.",
+      "If the contradiction is material (money, contract terms), recommend a written complaint and citing the exact wording."
+    ]
+  },
+  "required_user_info": [
+    "Source documents the agent can cross-check against (bill, contract, prior emails).",
+    "Prior call notes if any.",
+    "Whether the user authorises requesting written follow-up."
+  ],
+  "contributed_by": "critical-reasoning agent (v0.9.87 community drop)",
+  "updated_at": "2026-05-20T06:09:47Z"
+}

package/dist/skills/built-in/dispute-billing-code-eob.json

@@ -0,0 +1,147 @@
+{
+  "id": "dispute-billing-code-eob",
+  "name": "Dispute a Billing Code on an Explanation of Benefits (EOB)",
+  "version": "1.0.0",
+  "category": "medical-admin",
+  "tags": [
+    "billing",
+    "eob",
+    "claims",
+    "appeals",
+    "phone-call",
+    "insurance",
+    "healthcare"
+  ],
+  "description": "Call the insurance company and/or provider's billing office to dispute an incorrect CPT/HCPCS/ICD-10 code, denied claim, or wrongly applied member responsibility on the operator's Explanation of Benefits. Includes filing for reprocessing and formal appeal when needed.",
+  "disclaimer": "Not medical advice. Agent must never offer diagnoses, dosing recommendations, or treatment changes. Surface those decisions to the operator via ask_operator.",
+  "context": {
+    "when_to_use": "Operator received an EOB showing they owe more than expected, a claim denied, or a code that doesn't match what actually happened at the visit. Common scenarios: preventive visit coded as diagnostic (loses $0 copay), out-of-network coding error, downcoded service, modifier missing, wrong patient demographics on claim.",
+    "preconditions": [
+      "Operator's name, DOB (read-only), insurance member ID + group (read-only).",
+      "The EOB itself — claim number, date of service, billing provider name and NPI, CPT/HCPCS code(s), ICD-10 code(s), billed amount, allowed amount, insurance paid, member responsibility, denial/adjustment reason codes.",
+      "Operator's account of what actually happened at the visit (in plain language, not clinical recoding).",
+      "Whether operator has already received a bill from the provider, and the bill date (appeal clocks start ticking).",
+      "Whether prior auth was obtained for the service (if relevant)."
+    ],
+    "estimated_call_duration_minutes": 25
+  },
+  "principles": [
+    "An EOB is NOT a bill. Many disputes can be resolved BEFORE the provider's bill arrives by getting the insurer to reprocess the claim. Move fast.",
+    "Coding errors usually live with the PROVIDER's billing office, not the insurer. The insurer paid based on what was submitted. The fix is: provider re-submits with corrected coding.",
+    "Coverage / network / member-responsibility errors usually live with the INSURER. The fix is: reprocess with corrected benefits applied.",
+    "Diagnose which side owns the issue BEFORE assigning blame. Calling the insurer to fix a coding mistake just gets you bounced back to the provider, and vice versa.",
+    "Always document: who you spoke to, badge ID, reference number, date/time, and the specific commitment they made. Disputes that drag on for months are won by the side with the paper trail.",
+    "Internal appeal first, then external review. Don't pay the disputed amount before the appeal is decided — paying often legally finalises the bill."
+  ],
+  "phrases": {
+    "opener_insurance": "Hi, I'm calling on behalf of [Operator], member ID [redacted]. I'm looking at EOB for claim [number], date of service [date], from provider [name]. The claim was processed in a way that doesn't match what happened at the visit, and I'd like to request a reprocess. Can you get me to a claims specialist?",
+    "opener_provider_billing": "Hi, I'm calling on behalf of [Operator]. I'm looking at the EOB for [date of service] and the coding doesn't match what happened. Can you connect me with someone who can review the CPT and diagnosis codes that were submitted?",
+    "diagnose_owner": "Just to align — based on what I'm describing, is this a CODING issue (your side / billing office) or a BENEFITS issue (insurance side)?",
+    "describe_factual_mismatch": "The EOB shows CPT [code] which describes [description]. What actually happened at the visit was [operator's plain-language description]. Those don't match, and I'd like the coding reviewed.",
+    "preventive_vs_diagnostic": "This was scheduled as a preventive / annual wellness visit. The CPT submitted was [diagnostic code], which is why member responsibility is non-zero. Can the provider's billing office re-bill with the appropriate preventive code, or add a modifier?",
+    "ask_for_reprocess": "I'd like to formally request a reprocess of this claim. What's the reference number for that request and the timeline?",
+    "request_internal_appeal": "If reprocessing doesn't resolve, I'd like to know the formal internal appeals process — the deadline, format required, and where to send documentation.",
+    "no_surprises_act_dispute": "Some or all of these charges may fall under the No Surprises Act if [out-of-network at in-network facility / emergency / ancillary]. Can you confirm the protections applied to this claim?",
+    "ask_about_hold_on_collections": "While this is in dispute, can you put a hold on collections / hold the bill from going to collections? The dispute is documented.",
+    "ask_for_reference_number": "Could you give me a reference number for this dispute, your name, and your badge or employee ID?",
+    "stall_research": "One moment — let me find the exact code on the EOB.",
+    "verify_readback": "Confirming: claim [number], date [date], dispute reason [coding mismatch / coverage error / network error], action [reprocess / appeal / re-bill], owner [insurer / provider], reference [number], expected resolution within [N] days. Rep [name + badge]. Right?",
+    "graceful_close": "Thank you. I'll follow up if I don't see resolution by [date]. Have a good day."
+  },
+  "tactics": [
+    {
+      "name": "Diagnose insurer vs. provider as the owner",
+      "when": "First substantive turn.",
+      "script": "Use `diagnose_owner`. Coding error → provider's billing. Benefits/network/eligibility error → insurer. Calling the wrong party first wastes a half-hour and warms up nothing useful.",
+      "priority": 1
+    },
+    {
+      "name": "Describe the mismatch factually",
+      "when": "Explaining the dispute.",
+      "script": "Use `describe_factual_mismatch`. Avoid 'this is wrong' or 'I shouldn't owe this'. Pin down: what was submitted vs. what actually happened, in concrete terms. Specific lands; outrage doesn't.",
+      "priority": 2
+    },
+    {
+      "name": "Spot preventive-coded-as-diagnostic early",
+      "when": "EOB shows non-zero member responsibility for what was supposed to be a wellness visit, screening, or vaccine.",
+      "script": "Use `preventive_vs_diagnostic`. This is one of the most common coding fixes. ACA preventive services are covered at $0 — if the provider used a diagnostic code (e.g. due to a problem discussed during the visit), often a modifier 33 or split-billing resolves it.",
+      "priority": 3
+    },
+    {
+      "name": "Invoke No Surprises Act when applicable",
+      "when": "Claim involves out-of-network providers at in-network facility, emergency care, or ancillary services.",
+      "script": "Use `no_surprises_act_dispute`. Operator may owe only the in-network cost-share by law. Insurer may not have applied this automatically.",
+      "priority": 4
+    },
+    {
+      "name": "Hold collections while disputing",
+      "when": "Bill has been received from provider.",
+      "script": "Use `ask_about_hold_on_collections`. Disputed bills should not progress to collections. Get this commitment documented with a reference number.",
+      "priority": 5
+    },
+    {
+      "name": "Always paper-trail",
+      "when": "Every call.",
+      "script": "Use `ask_for_reference_number`. Write down: rep name, badge ID, reference number, date/time, exact commitment, ETA. Disputes are won by documentation.",
+      "priority": 6
+    },
+    {
+      "name": "Pause and re-verify on conflicting answers",
+      "when": "Insurer says 'provider needs to re-bill', provider says 'insurer needs to reprocess'.",
+      "script": "Do not bounce indefinitely. Ask one party to STAY ON THE LINE while you 3-way call the other, OR ask both for written documentation of their position so the dispute can escalate to an internal appeal with both written statements attached.",
+      "priority": 7
+    },
+    {
+      "name": "Escalate to formal internal appeal",
+      "when": "Reprocess request fails or no movement in 30 days.",
+      "script": "Use `request_internal_appeal`. Get: deadline, required documents (often a letter from the provider attesting to what actually happened), where to send. Internal appeal deadlines are short — usually 180 days from EOB date for ERISA plans.",
+      "priority": 8
+    },
+    {
+      "name": "Move to external review if internal fails",
+      "when": "Internal appeal denied.",
+      "script": "Most plans allow an external (independent) review after internal denial. State insurance commissioner's office can route. Surface this option to operator; do NOT initiate external review without operator authorization.",
+      "priority": 9
+    }
+  ],
+  "boundaries": [
+    "NEVER share or guess the operator's SSN, DOB, or member ID — read back only what the operator explicitly provided.",
+    "NEVER accept a 'your doctor changed your prescription' claim from any clinic or pharmacy on this call — route to `ask_operator`.",
+    "NEVER authorise a procedure, sign anything, or commit to financial responsibility on the operator's behalf, including agreeing to a payment plan or settlement amount.",
+    "NEVER mischaracterize what happened at the visit to get a more favorable code. That is fraud. Stick to what the operator described in plain language; let the billing office translate to codes.",
+    "NEVER pay the disputed amount before the dispute resolves unless operator explicitly authorizes (paying can legally finalize the bill in some jurisdictions).",
+    "NEVER demand the rep change their answer through volume or repetition. If they're stuck, escalate to a supervisor or to formal appeal — don't berate."
+  ],
+  "success_signals": [
+    "Owner correctly identified (insurer vs. provider) on first call.",
+    "Reprocess request filed with reference number and ETA.",
+    "Collections hold placed if bill was outstanding.",
+    "Coding correction agreed to and re-submission scheduled.",
+    "No Surprises Act protections applied where relevant."
+  ],
+  "failure_signals": [
+    "Insurer and provider each blame the other and neither will act.",
+    "Reprocess denied and operator has not authorized escalation to formal appeal.",
+    "Appeal deadlines passed before dispute could be filed.",
+    "Provider has already sent to collections — separate skill required (collections dispute)."
+  ],
+  "exit_strategy": {
+    "on_success": "Confirm: dispute filed, owner, reference number, action committed, ETA, collections hold (if applicable), and the operator's next step (typically: wait for written resolution).",
+    "on_failure": "Politely close. Report the impasse and present escalation options to operator: formal internal appeal, external review, state insurance commissioner complaint, or pay-under-protest.",
+    "follow_ups": [
+      "Set a reminder for the resolution ETA + 3 days.",
+      "If formal appeal filed, calendar the deadline.",
+      "Keep all EOBs, bills, and call notes in a single thread for the operator's records."
+    ]
+  },
+  "required_user_info": [
+    "Operator's name, DOB (read-only), insurance plan + member ID + group (read-only)",
+    "EOB: claim number, date of service, billing provider + NPI, CPT/HCPCS, ICD-10, billed/allowed/paid amounts, member responsibility, denial reason codes",
+    "Operator's plain-language description of what happened at the visit",
+    "Whether provider's bill has been received and the bill date",
+    "Whether prior auth was obtained for the service",
+    "Operator's authorization to escalate to formal appeal if needed"
+  ],
+  "contributed_by": "healthcare-navigator agent (v0.9.87 community drop)",
+  "updated_at": "2026-05-20T06:09:47Z"
+}

package/dist/skills/built-in/dispute-charge-reg-e-reg-z.json

@@ -0,0 +1,131 @@
+{
+  "id": "dispute-charge-reg-e-reg-z",
+  "name": "Dispute a Debit or Credit Charge Under Reg E / Reg Z",
+  "version": "1.0.2",
+  "category": "finance-admin",
+  "tags": [
+    "dispute",
+    "regulation-e",
+    "regulation-z",
+    "billing-error",
+    "chargeback",
+    "phone-call",
+    "banking-finance"
+  ],
+  "description": "Call the bank to dispute a specific charge that the user DID initially authorize but where something went wrong (merchant didn't deliver, charged twice, charged wrong amount, won't refund per their own policy). Different workflow from outright fraud: this is a billing-error / merchant-dispute case under Reg E (debit, EFTA) or Reg Z (credit, FCBA).",
+  "disclaimer": "Not financial or tax advice. Agent must NEVER share SSN unprompted, NEVER initiate wires above the operator's stated cap, NEVER agree to a hardship plan / settlement that affects credit without explicit ask_operator approval.",
+  "context": {
+    "when_to_use": "User authorized a transaction but the merchant: (a) charged more than agreed, (b) charged twice, (c) failed to deliver goods/services, (d) refused to honor their own refund policy, or (e) the recurring charge was supposed to be cancelled. Different from `report-fraudulent-transaction` — that's for charges the user never authorized at all.",
+    "preconditions": [
+      "User has attempted (or has a good-faith reason to skip) resolving directly with the merchant first — banks ask this.",
+      "User has the transaction details: date, amount, merchant name.",
+      "User has any supporting evidence: order confirmation, cancellation email, photos, terms-of-service screenshot, communication thread.",
+      "For credit cards: dispute filed within 60 days of the statement showing the charge (FCBA window).",
+      "For debit cards: dispute filed within 60 days of the statement (Reg E window for billing errors)."
+    ],
+    "estimated_call_duration_minutes": 30
+  },
+  "principles": [
+    "Frame it as a 'billing error' or 'merchant dispute' — not fraud. Mislabeling as fraud can backfire when the merchant produces a receipt with the user's name on it.",
+    "Reg Z (FCBA) covers credit cards: written dispute within 60 days, bank must acknowledge within 30 days, resolve within 2 billing cycles (max 90 days). Reg E covers debit cards / EFTs: 60-day window for unauthorized EFTs, billing errors have shorter clocks.",
+    "Documentation wins disputes. Have the merchant's own refund policy ready, the cancellation confirmation, or the proof of non-delivery.",
+    "First-line reps often default to 'have you tried the merchant?' — answer once, clearly, with what was tried and when. Then move on.",
+    "Banks can issue a temporary credit while investigating — ask explicitly.",
+    "Get the case in writing. Phone disputes start the clock, but written confirmation locks the bank into Reg Z/Reg E timing requirements."
+  ],
+  "phrases": {
+    "opener": "Hi, I need to file a billing-error dispute on a [credit / debit] charge. The charge was authorized but the merchant [didn't deliver / double-charged / charged the wrong amount / won't honor their refund policy]. I have documentation to support the claim.",
+    "state_the_merchant_attempts": "I contacted [Merchant] on [dates] by [phone / email / chat]. They said [outcome]. I'm now exercising my rights under [Regulation Z if credit / Regulation E if debit] to dispute this with the bank.",
+    "ask_temporary_credit": "While the investigation is pending, can the bank apply a temporary credit so I'm not paying interest on a disputed amount?",
+    "ask_billing_cycle_pause": "For the credit card: can you confirm that, while this is disputed, the disputed amount won't accrue interest or count toward late-payment fees per Reg Z?",
+    "ask_for_writing": "Can you confirm the dispute is opened in writing — a secure message in-app or an email summary? I'd like the case number and the regulatory timing in writing.",
+    "request_supervisor": "Could you bring in a dispute specialist or a supervisor? I want to make sure the case is coded correctly the first time — merchant dispute under [Reg E / Reg Z], not fraud.",
+    "upload_evidence_offer": "I have [order confirmation / cancellation email / refund-policy screenshot / tracking showing non-delivery]. Where should I upload it — secure message in-app, email, or fax?",
+    "graceful_close": "Thanks. Can you read back the case number, the disputed amount, the temporary credit (if any), and the deadline by which the bank expects to resolve? I'd like that summary in writing."
+  },
+  "tactics": [
+    {
+      "name": "Open with the correct label",
+      "when": "First substantive turn.",
+      "script": "Use `opener`. Say 'billing error' or 'merchant dispute' — NOT 'fraud'. Misclassifying triggers the wrong workflow and can be denied when the merchant proves you authorized the initial charge.",
+      "priority": 1
+    },
+    {
+      "name": "Answer 'did you try the merchant' once, completely",
+      "when": "Rep asks about prior merchant contact.",
+      "script": "Use `state_the_merchant_attempts`. Be specific about dates and channels. Then redirect to the dispute.",
+      "priority": 2
+    },
+    {
+      "name": "Anchor in the regulation",
+      "when": "Rep seems to be improvising the process.",
+      "script": "Name the regulation explicitly — Reg Z (credit) or Reg E (debit). Reps are trained on these; using the name signals competence and triggers the right workflow.",
+      "priority": 3
+    },
+    {
+      "name": "Ask for temporary credit",
+      "when": "Claim is opened.",
+      "script": "Use `ask_temporary_credit`. For credit cards, also use `ask_billing_cycle_pause` — Reg Z prohibits collecting on a disputed amount during the investigation.",
+      "priority": 4
+    },
+    {
+      "name": "Upload evidence promptly",
+      "when": "Rep asks if you have supporting documentation.",
+      "script": "Use `upload_evidence_offer`. Banks resolve documented disputes faster. Upload via secure in-app message, never plain email.",
+      "priority": 5
+    },
+    {
+      "name": "Escalate if miscoded",
+      "when": "Rep says 'we'll file this as fraud' or 'we can't dispute, it's authorized.'",
+      "script": "Use `request_supervisor`. Repeat: this is a Reg [E/Z] billing-error dispute, not fraud."
+    },
+    {
+      "name": "Lock in the writeback",
+      "when": "Claim filed, evidence uploaded.",
+      "script": "Use `graceful_close`. Case number + amount + temporary credit + resolution deadline + rep name. In writing."
+    }
+  ],
+  "boundaries": [
+    "Do NOT label this as fraud just to speed the call — if the merchant produces a receipt, a miscoded fraud claim gets denied AND can flag the user's account.",
+    "Do NOT lie about whether you contacted the merchant — banks ask the merchant, who shows the call/chat logs.",
+    "Do NOT agree to a 'reversal' that closes the merchant relationship without checking whether the user has services still pending with that merchant.",
+    "Do NOT share more identifying info than needed — last 4 of SSN and the card number are typically sufficient.",
+    "Do NOT close without case number, written summary path, and the resolution deadline.",
+    "Do NOT accept a verbal 'the merchant provided proof' as a closer. The bank must produce the documentation it relied on — under Reg E/Z the consumer has the right to a copy. Without seeing the evidence the bank cannot fairly close the dispute.",
+    "Do NOT withdraw the dispute on the phone because the rep says 'it'll be denied anyway'. A denial creates a documented record you can escalate; a withdrawal closes the door."
+  ],
+  "success_signals": [
+    "Rep codes it correctly as 'billing error' / 'merchant dispute' under Reg E or Reg Z.",
+    "Temporary credit applied or scheduled.",
+    "Rep confirms interest pause on credit-card disputes.",
+    "Evidence upload path provided and accessible.",
+    "Resolution deadline given (typically 30 days acknowledge / 90 days resolve for Reg Z)."
+  ],
+  "failure_signals": [
+    "Rep refuses to file because 'you authorized it' — they're conflating fraud with billing error.",
+    "Rep insists on a paper-only filing (push for digital).",
+    "No case number after 20 minutes — escalate.",
+    "Rep tells you to call back after attempting merchant again, despite documented attempts.",
+    "Rep claims 'the merchant provided proof you authorized this' but cannot or will not send the proof — the consumer is entitled to it under Reg E/Z.",
+    "Rep urges you to 'withdraw the dispute and try the merchant one more time' — that closes your case without a documented denial and resets the regulatory clock."
+  ],
+  "exit_strategy": {
+    "on_success": "Confirm case number, disputed amount, temporary-credit status, evidence-upload path, written-summary delivery, resolution deadline. Email operator with the case details + calendar a check-back at the 30-day mark.",
+    "on_failure": "Get case number anyway. If miscoded as fraud, escalate to dispute specialist. If repeatedly blocked, file a CFPB complaint and consider a small-claims action vs. the merchant. Surface to operator for approval to escalate.",
+    "follow_ups": [
+      "Day 30: confirm acknowledgment received in writing (Reg Z 30-day rule).",
+      "Day 60: check status — many banks resolve at this mark.",
+      "Day 90: final resolution deadline — if not resolved, escalate to CFPB."
+    ]
+  },
+  "required_user_info": [
+    "Account / card last 4",
+    "Transaction details: date, amount, merchant name",
+    "Reason for dispute (non-delivery, double-charge, wrong amount, refund refused, recurring after cancel)",
+    "Summary of merchant-contact attempts: dates, channels, outcomes",
+    "Supporting evidence files ready to upload",
+    "Operator-approved threshold for any further escalation costs"
+  ],
+  "contributed_by": "banking-finance agent (v0.9.87 community drop)",
+  "updated_at": "2026-05-20T06:09:47Z"
+}