@agenticmail/core 0.9.31 → 0.9.33

package/dist/skills/built-in/handle-time-pressure.json

@@ -0,0 +1,159 @@
+{
+  "id": "handle-time-pressure",
+  "name": "Time Pressure: Using It, Neutralizing It",
+  "version": "1.0.1",
+  "category": "negotiation",
+  "tags": ["deadlines", "urgency", "exploding-offers", "BATNA", "phone-call", "real-time"],
+  "description": "Time pressure is the most-used and least-real leverage in commercial negotiation. 'This offer expires today', 'I have another buyer', 'my manager only approved this for an hour' — these are almost always partly fictional. Recognize them, neutralize them, and deploy real time pressure of your own when warranted.",
+  "disclaimer": "Some deadlines ARE real. Calling a real deadline as fake is the most expensive mistake in this skill. Always test before dismissing.",
+  "context": {
+    "when_to_use": "Any negotiation where the counterparty introduces a deadline, expiration, or urgency claim. Or when you have legitimate time pressure of your own to leverage.",
+    "preconditions": [
+      "You have a BATNA (best alternative to a negotiated agreement) so you can credibly slow down.",
+      "You are NOT yourself under emergency time pressure — if you are, neutralizing theirs is harder.",
+      "You have authorization from the user to let an offer expire if it turns out to have been real."
+    ],
+    "estimated_call_duration_minutes": 25
+  },
+  "principles": [
+    "Manufactured urgency is the negotiator's most-deployed weapon because it's cheap to fake and effective on amateurs.",
+    "The asymmetric-urgency rule: the side that NEEDS the deal sooner loses leverage. Never reveal your urgency.",
+    "Slow down deliberately when the counterparty speeds up. Pace asymmetry is its own leverage — they reveal their position to fill the silence.",
+    "Real deadlines have specific, verifiable, system-level consequences. 'My manager went home at 5' is verifiable; 'this is our best offer for today' is not.",
+    "When using time pressure yourself, anchor on EXTERNAL constraints (board meeting, fiscal year, regulatory date) not internal preference. External constraints feel non-negotiable; internal preference is negotiable.",
+    "If a counterparty's 'expiring' offer was real, it will be re-offered within 48 hours — usually at the same number or better. Calling the bluff is rarely catastrophic."
+  ],
+  "phrases": {
+    "test_the_deadline": "What happens if I decide tomorrow instead of today?",
+    "test_the_other_buyer": "It sounds like you have momentum elsewhere — should we pause and let you close that? I don't want to be a distraction.",
+    "test_the_manager_window": "Can you confirm that in writing before we lose the window?",
+    "slow_the_pace": "Let me take a minute to think this through — I want to make sure I'm making the right call.",
+    "neutralize_calmly": "I hear there's a deadline on your end — and I respect that. But I can't make a decision this size in [N] minutes. What's the longest you can hold this?",
+    "deploy_real_pressure": "I need to close this by [specific date] because of [external constraint]. After that, my best alternative is [BATNA].",
+    "deploy_fy_pressure": "We're committing remaining budget by end of fiscal — anything we don't close by [date] rolls to next year.",
+    "graceful_walk_from_fake_deadline": "Okay. If the offer's gone tomorrow, that tells me what I need to know about the flexibility on your end — I'll move forward elsewhere. No hard feelings."
+  },
+  "tactics": [
+    {
+      "name": "Test every deadline before believing it",
+      "when": "Counterparty mentions an expiration, deadline, or limited window.",
+      "script": "`test_the_deadline`: 'What happens if I decide tomorrow?' If the answer is vague, the deadline is soft. If the answer is specific and system-level, it's likely real.",
+      "priority": 1
+    },
+    {
+      "name": "Slow down when they speed up",
+      "when": "Rep accelerates pace, repeats the deadline, or pushes for immediate close.",
+      "script": "Use `slow_the_pace`. Take a deliberate pause. Your composure is a counter-leverage.",
+      "priority": 2
+    },
+    {
+      "name": "Call the other-buyer bluff softly",
+      "when": "Rep claims 'I have another buyer interested'.",
+      "script": "`test_the_other_buyer` — graciously yield the field. 'Great, then it sounds like you don't need me — good luck.' 90% of the time the other buyer materializes only when you do.",
+      "priority": 3
+    },
+    {
+      "name": "Get the time pressure in writing",
+      "when": "Rep claims the manager approval has a window.",
+      "script": "`test_the_manager_window`: 'Can you confirm that in writing?' Most fake windows evaporate at the request for documentation.",
+      "priority": 4
+    },
+    {
+      "name": "Deploy YOUR external deadline carefully",
+      "when": "You have a real, defensible external deadline (fiscal year, project start, regulatory deadline).",
+      "script": "Use `deploy_real_pressure` or `deploy_fy_pressure`. Name the external anchor. Make it falsifiable so it reads as real.",
+      "priority": 5
+    },
+    {
+      "name": "Walk gracefully if the fake deadline is real",
+      "when": "You called the bluff and they walked.",
+      "script": "Use `graceful_walk_from_fake_deadline`. No anger, no recrimination. Door stays open. They often come back within 48 hours."
+    }
+  ],
+  "decision_tree": {
+    "description": "Time-pressure moves happen quickly. The first 5 seconds after a deadline is stated determine whether you fold or test. Run this every time.",
+    "branches": [
+      {
+        "if_you_hear": "'This offer expires today / this hour / by EOD.'",
+        "interpretation": "80% fake. Test before accepting.",
+        "say": "`test_the_deadline`: 'What happens if I decide tomorrow?'",
+        "do_not": "Do not fold. Do not accept the deadline as-stated."
+      },
+      {
+        "if_you_hear": "'I have another buyer / another customer interested in this slot.'",
+        "interpretation": "Often bluff. Even if true, you have nothing to lose by yielding.",
+        "say": "`test_the_other_buyer` — yield gracefully: 'Sounds like you don't need me.'",
+        "do_not": "Do not get into a bidding war on their terms. Do not match urgency."
+      },
+      {
+        "if_you_hear": "'My manager only approved this discount for the next [hour].'",
+        "interpretation": "Possibly real, possibly script. Ask for documentation.",
+        "say": "`test_the_manager_window`: 'Can you confirm that in writing?'",
+        "do_not": "Do not accept verbal-only deadlines. Documentation requests reveal fakes."
+      },
+      {
+        "if_you_hear": "Specific, verifiable, system-level deadline (e.g., 'price increase takes effect Jan 1 — already in the system').",
+        "interpretation": "Likely real. System constraints are harder to fake.",
+        "say": "Acknowledge the real deadline but slow your own decision: `neutralize_calmly`. 'I hear it — what's the longest you can hold it?'",
+        "do_not": "Do not panic-buy. Even real deadlines have grace periods if you ask."
+      },
+      {
+        "if_you_hear": "Rep keeps mentioning the clock multiple times in 5 minutes.",
+        "interpretation": "Pressure tactic, not real deadline. Real deadlines get stated once.",
+        "say": "Name it gently: 'I notice the clock keeps coming up — can you help me understand what changes after [time]?'",
+        "do_not": "Do not let the repetition pressure you. Repetition signals weakness, not strength."
+      },
+      {
+        "if_you_hear": "Counterparty tries to extend the call past your scheduled end.",
+        "interpretation": "They want to push you past decision fatigue.",
+        "say": "'I need to wrap up at [time]. Let's pick this up tomorrow with the rest unresolved.' Set the boundary.",
+        "do_not": "Do not let them control the clock. Decision fatigue is real."
+      },
+      {
+        "if_you_hear": "You feel YOURSELF rushing — internal urgency leaking.",
+        "interpretation": "Most dangerous moment. You're about to give away leverage.",
+        "say": "Take a manufactured break: 'Hold on one moment, I want to check something.' 30-second pause resets your tempo.",
+        "do_not": "Do not let your tone reveal urgency. Pause aggressively."
+      },
+      {
+        "if_you_hear": "You have a REAL external deadline they don't know about.",
+        "interpretation": "Hidden leverage on their side if revealed. Hidden constraint on yours.",
+        "say": "Decide whether to use it. If you can credibly hide it longer than they can wait, hide it. If your hand is forced, name it AS external ('fiscal year', not 'I need to close').",
+        "do_not": "Do not name internal urgency. External deadlines are leverage; internal ones are tells."
+      },
+      {
+        "if_you_hear": "They walk after you tested the deadline.",
+        "interpretation": "Either you over-tested OR the deadline was real after all.",
+        "say": "`graceful_walk_from_fake_deadline`. Door stays open. Most return within 48 hours.",
+        "do_not": "Do not chase. Do not panic-accept. Do not bad-mouth them."
+      }
+    ]
+  },
+  "boundaries": [
+    "Do NOT manufacture fake deadlines yourself. The user's reputation is at stake; fake deadlines from you damage long-term trust.",
+    "Do NOT call a clearly system-level deadline a bluff (e.g., 'all flights to that destination are full' is real, not a tactic).",
+    "Do NOT use 'I have other offers' unless you actually do.",
+    "Do NOT push past a counterparty's stated end-of-day. They can be rushed; you cannot break their reasonable boundaries."
+  ],
+  "success_signals": [
+    "After your test, the rep softens or extends the deadline ('let me see if I can hold it through tomorrow').",
+    "Rep stops mentioning the deadline after you test it once.",
+    "Rep volunteers that the deadline was nominal ('honestly, we usually have a grace period').",
+    "Walked-away counterparty calls back within 48 hours."
+  ],
+  "failure_signals": [
+    "Rep documents the deadline immediately when asked — it was real. Decide fast.",
+    "Rep ends the call after your test — over-tested; review.",
+    "You agreed under pressure and now regret the terms — diagnose what you missed."
+  ],
+  "exit_strategy": {
+    "on_success": "If you neutralized the deadline, proceed at your pace and close on real terms.",
+    "on_failure": "If the deadline was real and you missed the window, log the lesson and verify next time before testing. If you walked and they don't return, validate that your BATNA was sound."
+  },
+  "required_user_info": [
+    "User's BATNA — what happens if they walk?",
+    "User's real deadlines (so we don't conflate negotiating tactics with real constraints).",
+    "Whether the user has authority to let an offer expire."
+  ],
+  "contributed_by": "negotiation-master agent (v0.9.87 community drop)"
+}

package/dist/skills/built-in/health-prior-auth-appeal.json

@@ -0,0 +1,131 @@
+{
+  "id": "health-prior-auth-appeal",
+  "name": "Appeal a Health-Insurance Prior-Authorization Denial",
+  "version": "1.0.1",
+  "category": "finance-admin",
+  "tags": [
+    "health",
+    "prior-auth",
+    "denial",
+    "appeal",
+    "medical-necessity",
+    "phone-call",
+    "insurance"
+  ],
+  "description": "Push a denied prior-authorization (PA) request back through the carrier's appeal pipeline. Force a peer-to-peer review, surface the medical-necessity criteria the denial actually cited, and start the formal written appeal with deadlines. Most PA denials are overturned on appeal — but only if appealed.",
+  "disclaimer": "Agent must NEVER admit fault, NEVER agree to a settlement on the operator's behalf, NEVER speculate about prior conditions, NEVER sign a release. All of those route through ask_operator.",
+  "context": {
+    "when_to_use": "A health insurer has denied prior auth for a procedure, medication, imaging, or referral that the prescribing clinician has ordered. Use AFTER receiving the denial and BEFORE the procedure date or medication runaround.",
+    "preconditions": [
+      "User has the denial letter or denial reference number.",
+      "User has the prescribing clinician's name, NPI, and office contact.",
+      "User has the CPT/HCPCS code (procedure) or NDC (medication) being denied.",
+      "User knows whether the plan is fully-insured (state-regulated) or self-funded ERISA (federal — different appeal rules).",
+      "User has the policy's evidence-of-coverage document or member handbook."
+    ],
+    "estimated_call_duration_minutes": 30
+  },
+  "principles": [
+    "PA denials are issued against medical-necessity criteria (often Milliman/MCG or InterQual). The criteria are written; demand to know which the denial cites.",
+    "Peer-to-peer (P2P) review is the fastest unlock — your clinician talks to the carrier's medical director. Schedule it.",
+    "Internal appeal first, then external review (state or federal). Most plans must offer both.",
+    "Expedited appeal is available when delay would jeopardize health (e.g. cancer treatment, post-op infection). Use it when applicable — 72-hour decisions instead of 30 days.",
+    "The denying physician's specialty matters. A primary-care MD denying an oncology drug is challengeable on its face.",
+    "Documenting prior failed therapies is often the key to overturning step-therapy denials."
+  ],
+  "phrases": {
+    "opener": "Hi, I'm calling about a prior-authorization denial — reference [number], member ID [id], for [procedure/medication, CPT/NDC code]. I want to start the appeal and request a peer-to-peer review with my [clinician name].",
+    "ask_criteria": "What specific medical-necessity criteria — Milliman, MCG, InterQual, or your internal policy — were used to evaluate this request? Could you send me the criteria document and the specific criteria that weren't met?",
+    "request_p2p": "I'd like to schedule a peer-to-peer review between my prescribing [specialist] and your medical director. What's the soonest available slot, and who do I have my clinician's office contact?",
+    "request_expedited": "Given that delay could [jeopardize my health / cause irreversible harm / lead to hospitalization], I'd like to file this as an expedited appeal. The standard is 72 hours for expedited internal appeals. Can we proceed on that timeline?",
+    "ask_reviewer_specialty": "What was the specialty of the physician who issued the denial? Was it the same specialty as my prescribing clinician?",
+    "request_written_appeal_path": "Please walk me through the formal appeal process: internal appeal deadline, external review path, what evidence I can submit, and where to send it.",
+    "decline_substitution": "Thanks, but my clinician has already considered [alternative] and ruled it out because [reason]. I'd like to stay focused on the originally prescribed treatment.",
+    "graceful_close": "Thank you. To confirm: peer-to-peer is scheduled for [date/time], appeal deadline is [date], expedited status is [confirmed/pending], and the criteria document will be sent to [email] by [date]."
+  },
+  "tactics": [
+    {
+      "name": "Open with the appeal request, not the complaint",
+      "when": "First substantive turn.",
+      "script": "Use the `opener` phrase. Two deliverables: P2P scheduled + appeal opened. Don't get pulled into re-arguing the underlying clinical question with a phone rep.",
+      "priority": 1
+    },
+    {
+      "name": "Demand the specific criteria",
+      "when": "Rep says 'not medically necessary' without specifics.",
+      "script": "Use the `ask_criteria` phrase. The clinician needs the exact criteria the denial cited to build the P2P case and the written appeal.",
+      "priority": 2
+    },
+    {
+      "name": "Schedule the peer-to-peer",
+      "when": "Once the denial is confirmed.",
+      "script": "Use the `request_p2p` phrase. P2P often overturns the denial in a single 15-minute call between the clinician and the medical director.",
+      "priority": 3
+    },
+    {
+      "name": "Escalate to expedited if clinically warranted",
+      "when": "Delay would harm the user's health.",
+      "script": "Use the `request_expedited` phrase. Documented urgency unlocks 72-hour timelines. Clinician's office can submit a letter of medical necessity stating the urgency.",
+      "priority": 4
+    },
+    {
+      "name": "Challenge the reviewer's specialty",
+      "when": "Drug or procedure is specialty-specific.",
+      "script": "Use the `ask_reviewer_specialty` phrase. A non-specialist denial is grounds for a same-specialty re-review on appeal — and is itself appealable.",
+      "priority": 5
+    },
+    {
+      "name": "Map the full appeal ladder",
+      "when": "Mid-call.",
+      "script": "Use the `request_written_appeal_path` phrase. Internal appeal → external review → state DOI / federal IRO depending on plan type. Each rung has a deadline and a clock.",
+      "priority": 6
+    },
+    {
+      "name": "Decline 'alternative' substitutions",
+      "when": "Rep suggests a cheaper drug or different procedure.",
+      "script": "Use the `decline_substitution` phrase. The phone rep is not the clinician. Substitutions belong in P2P with documented clinical reasoning, not on a service call.",
+      "priority": 7
+    }
+  ],
+  "boundaries": [
+    "Do NOT speculate about pre-existing conditions, prior symptoms, or family history on this call.",
+    "Do NOT accept the denial as final — internal appeal is a right under both ERISA and ACA-regulated plans.",
+    "Do NOT skip the expedited option if the clinical situation is urgent — the standard 30-day clock can cause real harm.",
+    "Do NOT agree to a 'voluntary withdrawal' of the PA request, which can extinguish appeal rights.",
+    "Do NOT disclose mental-health, substance-use, HIV, or other specially-protected diagnoses unless directly relevant to the appeal.",
+    "Do NOT make clinical decisions on the call. Substitutions, dose changes, and 'trying alternatives first' route through the clinician."
+  ],
+  "success_signals": [
+    "P2P is scheduled with the carrier's medical director.",
+    "Criteria document is committed for delivery.",
+    "Expedited status is granted when requested.",
+    "Carrier confirms same-specialty reviewer for the appeal.",
+    "Appeal deadline and submission method are clearly documented."
+  ],
+  "failure_signals": [
+    "Rep refuses to schedule P2P.",
+    "Rep won't disclose which criteria set was used.",
+    "Carrier asserts the denial is 'final' before internal appeal.",
+    "Expedited request is denied without medical justification."
+  ],
+  "exit_strategy": {
+    "on_success": "Confirm P2P time, criteria-doc ETA, appeal deadline, expedited status. Email a recap to the user AND the prescribing clinician's office (so they can prepare for P2P).",
+    "on_failure": "Document the obstruction. Route to `ask_operator` with options: (1) written appeal with letter of medical necessity, (2) state DOI complaint (if fully-insured) or DOL complaint (if ERISA self-funded), (3) external IRO review, (4) state insurance commissioner.",
+    "follow_ups": [
+      "Email the clinician's office with the criteria document and P2P time so they can prepare.",
+      "Calendar the appeal deadline with 7-day and 1-day reminders.",
+      "Send a recap to the user with next-step ownership.",
+      "If P2P fails, immediately initiate written internal appeal."
+    ]
+  },
+  "required_user_info": [
+    "Denial reference number and member ID",
+    "Procedure CPT/HCPCS code or medication NDC",
+    "Prescribing clinician's name, NPI, office phone",
+    "Letter of medical necessity from clinician (request from office if missing)",
+    "Plan type — fully-insured vs ERISA self-funded",
+    "Whether clinical situation warrants expedited appeal"
+  ],
+  "contributed_by": "insurance-claims agent (v0.9.87 community drop)",
+  "updated_at": "2026-05-20T06:09:47Z"
+}

package/dist/skills/built-in/hoa-dispute.json

@@ -0,0 +1,123 @@
+{
+  "id": "hoa-dispute",
+  "name": "Dispute an HOA Fine, Denial, or Common-Area Issue",
+  "version": "1.0.0",
+  "category": "real-estate",
+  "tags": [
+    "hoa",
+    "fine",
+    "architectural-review",
+    "common-area",
+    "covenants",
+    "phone-call",
+    "housing-tenancy"
+  ],
+  "description": "Call the HOA management company or board liaison to dispute a fine, appeal an architectural-review denial, or escalate a common-area maintenance issue — establishing the formal record and timeline required by most HOA CC&Rs (covenants, conditions, and restrictions).",
+  "disclaimer": "Not legal advice. Habitability + early-termination skills are scripted to PRESERVE legal posture (request things in writing, refuse verbal-only assurances) — but the operator must consult a tenant attorney for actual rights determination.",
+  "context": {
+    "when_to_use": "User has received: (a) an HOA fine they believe is improper or excessive, (b) a denial from architectural review on a planned change (paint, fence, solar, landscaping), or (c) an unresolved common-area issue (broken gate, pool maintenance, drainage). Most HOAs have a formal dispute or appeal process with strict deadlines — this call opens that process.",
+    "preconditions": [
+      "User has a copy of the CC&Rs and the bylaws (or knows where to get them).",
+      "User has the fine notice, denial letter, or written complaint with date.",
+      "User knows the appeal / dispute deadline stated in the notice (commonly 14–30 days).",
+      "User has photos / documentation of the alleged violation or the common-area issue."
+    ],
+    "estimated_call_duration_minutes": 15
+  },
+  "principles": [
+    "Read the CC&Rs BEFORE the call — knowing the actual rule cited beats any opinion.",
+    "Appeal deadlines are strict. Missing the appeal window in many HOAs forfeits the right to challenge at all.",
+    "Board members are volunteers; management-company staff are paid. Both deserve courtesy — but the management-company employee is usually the one to schedule the appeal.",
+    "Always request the formal appeal in writing and ask for the rule, section, and citation that the fine or denial is based on. Vague citations don't survive an appeal.",
+    "Document selective enforcement. If neighbors are not being fined for the same thing, that's a real defense — but it requires photos and dates, not anecdotes.",
+    "Keep the tone professional. HOA disputes are repeated games — you and the board see each other at the mailbox for years."
+  ],
+  "phrases": {
+    "opener_fine": "Hi, I'm calling about a violation notice I received dated [date] for [property]. I'd like to formally dispute it and understand the appeal process.",
+    "opener_denial": "Hi, I'm calling about the architectural-review denial I received on [date] for my [project]. I'd like to appeal — what's the process and the deadline?",
+    "opener_common_area": "Hi, I'm calling about a common-area issue at [location] — [one-sentence description]. It's been [unaddressed since X / a recurring problem]. How do I get this on the board agenda?",
+    "ask_for_citation": "Can you tell me exactly which section of the CC&Rs or rules this notice cites? I want to look at the specific language.",
+    "ask_for_appeal_process": "Walk me through the appeal: do I submit in writing, do I get a hearing, who decides, and what's the deadline?",
+    "raise_selective_enforcement": "I've noticed [specific examples — addresses, photos, dates] where the same condition wasn't cited. Is the rule being enforced consistently? I'd like that addressed in my appeal.",
+    "ask_about_due_process": "Was there a notice-and-cure period before the fine was levied? Most HOAs require one — I'd like to confirm the procedure was followed.",
+    "graceful_close_appeal_scheduled": "Thank you. To confirm: appeal filed in writing by [date], hearing on [date], decision within [X] days. Anything else I should submit before then?",
+    "graceful_close_referral": "Understood. Could you also forward this to the board president? I want to make sure they're aware of my appeal directly."
+  },
+  "tactics": [
+    {
+      "name": "Open with the specific notice and the appeal intent",
+      "when": "First substantive turn.",
+      "script": "Use the matching opener. Be specific — date, property, action. Establishes a real dispute, not a vague complaint.",
+      "priority": 1
+    },
+    {
+      "name": "Demand the specific citation",
+      "when": "Once the dispute is logged.",
+      "script": "Use `ask_for_citation`. Many fines cite vague 'community standards.' Force them to the section number — that's what an appeal panel reviews.",
+      "priority": 2
+    },
+    {
+      "name": "Lock the appeal process and deadlines",
+      "when": "After the citation is identified.",
+      "script": "Use `ask_for_appeal_process`. Get the form of appeal, who decides, and the deadlines. Missing the deadline ends the dispute.",
+      "priority": 3
+    },
+    {
+      "name": "Raise selective enforcement IF documented",
+      "when": "Other properties have the same condition uncited.",
+      "script": "Use `raise_selective_enforcement`. Bring it with documentation (addresses, photos, dates). Without documentation it weakens your case.",
+      "priority": 4
+    },
+    {
+      "name": "Probe due-process compliance",
+      "when": "Disputing a fine.",
+      "script": "Use `ask_about_due_process`. Many HOAs MUST give a notice-and-cure period; skipping it can void the fine entirely.",
+      "priority": 5
+    },
+    {
+      "name": "Loop in the board president",
+      "when": "Management-company response is dismissive.",
+      "script": "Use `graceful_close_referral`. Board members can override management staff. Keep tone neutral — you're asking for awareness, not complaining about the staffer."
+    }
+  ],
+  "boundaries": [
+    "Do NOT skip paying the underlying assessment or dues — pay them under protest if necessary. Non-payment compounds the problem and can result in liens.",
+    "Do NOT make claims about board members' personal motives or other owners — stick to the rule and the facts.",
+    "Do NOT accept a settlement that requires waiving future challenges to the same rule without operator review.",
+    "Do NOT threaten litigation on the first call. Mention the formal appeal as the path.",
+    "Do NOT discuss the dispute on social media or community forums — those quotes will surface in the appeal hearing."
+  ],
+  "success_signals": [
+    "Specific CC&R section cited.",
+    "Appeal form, deadline, and hearing date confirmed.",
+    "Management agrees to forward to the board.",
+    "Management acknowledges a procedural gap (no notice-and-cure, ambiguous rule)."
+  ],
+  "failure_signals": [
+    "Management refuses to identify the cited section.",
+    "Appeal process is described as 'just pay it.'",
+    "Hearing is scheduled past the cure deadline (fine compounds).",
+    "Board liaison won't take the call or respond to written appeal."
+  ],
+  "exit_strategy": {
+    "on_success": "Confirm appeal deadline, hearing date, what must be submitted, and who will decide. Operator emails a recap within 24 hours.",
+    "on_failure": "Submit the written appeal anyway by certified mail to preserve the record. If the dispute involves a significant fine, lien threat, or pattern of selective enforcement, consult an HOA attorney before the hearing.",
+    "follow_ups": [
+      "Pull the CC&Rs section cited and read it carefully before drafting the written appeal.",
+      "Collect documentation: photos of the alleged violation, photos of identical uncited conditions on neighboring properties, prior correspondence.",
+      "Send the written appeal by both email AND certified mail before the deadline.",
+      "Calendar the hearing date and prepare a 2-minute statement.",
+      "If the dispute escalates to a lien threat, consult an HOA attorney immediately."
+    ]
+  },
+  "required_user_info": [
+    "Notice date, property address, CC&R citation (or claim of citation)",
+    "Stated fine amount or denial reason",
+    "Appeal deadline as stated in the notice",
+    "CC&Rs / bylaws (copy or link)",
+    "Photos and documentation supporting the dispute",
+    "Names of management-company contact and board liaison"
+  ],
+  "contributed_by": "housing-tenancy agent (v0.9.87 community drop)",
+  "updated_at": "2026-05-20T06:09:47Z"
+}

package/dist/skills/built-in/hold-time-strategy.json

@@ -0,0 +1,137 @@
+{
+  "id": "hold-time-strategy",
+  "name": "Hold-Time Strategy — Wait, Hang Up, or Call Back",
+  "version": "1.0.0",
+  "category": "customer-service",
+  "tags": [
+    "phone-call",
+    "hold-time",
+    "queue-strategy",
+    "timing",
+    "patience",
+    "tactical",
+    "customer-support"
+  ],
+  "description": "Decide when to hold, when to hang up, and when to call back at a different hour. Queue dynamics, time-of-day patterns, and call-center staffing curves create predictable windows — using them shortens a 90-minute ordeal to a 20-minute call.",
+  "disclaimer": null,
+  "context": {
+    "when_to_use": "You are about to call a support line, OR you are currently on hold and deciding whether to stay. Especially relevant for telco, ISP, airlines, banks, government agencies, and any service with notoriously bad hold times.",
+    "preconditions": [
+      "User has time flexibility — at least 2 hours of total availability across one or more calls.",
+      "User has tracked any prior hold times for this company (rough estimate is fine).",
+      "User has access to a speakerphone or wireless headset — being trapped at a desk for 60 minutes is much worse than being on hold while doing other tasks."
+    ],
+    "estimated_call_duration_minutes": 35
+  },
+  "principles": [
+    "Call volume is predictable. Peak: 11am-2pm local time (lunch breaks) and the first 30 minutes after open. Trough: first 30 minutes after open IF you call BEFORE the rush (typically 7-8am local), late afternoon (4-5pm local), and the last hour before close. Saturday morning is usually quieter than weekday peak.",
+    "Day-of-week matters. Monday is the worst day for most services — everyone calls about the weekend's problems. Thursday and Friday afternoons are often the quietest weekdays. Weekends vary by service: financial/banking lines may be skeleton-crew; consumer goods/airlines may be normal.",
+    "Hold time is not free — it costs attention even if you're doing other work. Estimate the total ATTENTION cost (not just elapsed time): a 45-minute hold while you're trying to work is often more expensive than a 75-minute hold while you're doing laundry.",
+    "The 'callback' option offered by some IVRs (press 1 to hold your place in line) is almost always better than holding live — accept it whenever available. The callback usually preserves your position and frees your attention.",
+    "Decision point — every 15 minutes on hold, ask: 'do I have evidence I'm progressing in the queue?' If no (no estimated wait given, or the estimate keeps growing), hanging up is rational. If yes, continue.",
+    "Calling back can sometimes route you better than holding. Different queues have different staffing; the IVR sometimes routes by call volume — calling at a quieter time can land you in a less-loaded specialist queue.",
+    "Some hold-times are deliberate. Companies known for long holds often staff just enough to handle the customers who don't give up — the hold IS the filter. Once you understand that, you can choose to be the customer who waits, or you can route around the hold entirely (chat, email, escalation channel)."
+  ],
+  "phrases": {
+    "ask_for_estimate": "Before I commit to holding — could you give me an estimated wait time? Or is there a callback option in lieu of holding?",
+    "request_callback_position": "I'd prefer not to hold for 40 minutes. Can I be put in a callback queue with my place preserved? Or could you schedule me a callback at a specific time today?",
+    "the_strategic_hangup": "Thank you — I'm going to call back at a different hour rather than hold. Could you note that I called at [time] about [issue] so the next rep has context?",
+    "midcall_pivot": "I've been on hold 30 minutes. Could you check the queue depth and tell me realistically how much longer? If it's more than another 15 minutes, I'd rather schedule a callback.",
+    "after_hours_inquiry": "What are your peak hours? I'd like to call back at a quieter time if possible.",
+    "channel_alternative": "While I'm holding — is there a chat or email option that would resolve this faster? I'd be happy to use whichever channel is least busy right now.",
+    "first_call_advantage": "Hi, I'm calling first thing this morning to get ahead of any backlog from yesterday. I have [issue] and I'd like to keep this efficient."
+  },
+  "tactics": [
+    {
+      "name": "Pick the call window deliberately",
+      "when": "Before placing the call.",
+      "script": "Default windows: weekday 7:30-9:00am local (pre-rush), 4:00-5:30pm local (post-rush). Avoid Monday morning. Avoid lunch hour. For 24/7 services, late-night (10pm-midnight) is often empty queues — but staff may be junior. Decide whether you need expertise (call peak) or just throughput (call trough).",
+      "priority": 1,
+      "decision_point": "If the issue is complex or needs senior judgment, the FASTEST queue may have the LEAST capable reps. Sometimes you want to call peak to reach a tenured agent. Match the time to the issue, not just to availability."
+    },
+    {
+      "name": "Always ask for an estimate",
+      "when": "Immediately when a hold is offered.",
+      "script": "Use `ask_for_estimate`. Many IVRs and reps will give you a number if asked — and an honest number lets you make a real decision instead of sunk-cost-ing into a 90-minute hold.",
+      "priority": 2
+    },
+    {
+      "name": "Take the callback option if offered",
+      "when": "IVR mentions a callback or rep can offer one.",
+      "script": "Use `request_callback_position`. Callbacks are almost always better than live holding — your time becomes free, and the callback typically arrives near the original ETA. Risks: some callbacks expire if you don't answer immediately; some lose your queue position.",
+      "priority": 3,
+      "decision_point": "Take callback ONLY if (a) you can answer when they call, and (b) the callback preserves queue position or is scheduled. If neither, prefer live hold."
+    },
+    {
+      "name": "Set a hold budget — and stick to it",
+      "when": "When you accept a hold.",
+      "script": "Decide BEFORE you start: 'I will hold for X minutes, then re-evaluate.' Without a budget, sunk cost takes over. With a budget, you make a clear decision at the checkpoint.",
+      "priority": 4
+    },
+    {
+      "name": "Re-evaluate at the checkpoint",
+      "when": "Hold budget reached.",
+      "script": "Use `midcall_pivot`. Ask for honest queue depth. If the rep can't or won't give you a number, that's evidence the queue is poorly managed — hang up.",
+      "priority": 5,
+      "decision_point": "If the rep says 'just a few more minutes' for the second time, the estimate is unreliable. Treat each 'just a few more' as +10 minutes of additional hold — and if you don't have +10 to give, end the call cleanly."
+    },
+    {
+      "name": "Strategic hangup with breadcrumb",
+      "when": "You've decided to give up on this call.",
+      "script": "Use `the_strategic_hangup`. Leaving a note on your account ('called at X about Y') is sometimes possible even if you didn't reach a rep — it's evidence of effort for any future escalation.",
+      "priority": 6
+    },
+    {
+      "name": "Switch channels mid-hold",
+      "when": "Hold is long AND you discover the company has a faster channel.",
+      "script": "Use `channel_alternative`. Some companies' chat is faster than phone — they routed support resources there. Email is rarely fast but creates a paper trail. Use chat/email IN PARALLEL with holding, not as a replacement (you may hit both at once and pick whichever lands first).",
+      "priority": 7
+    },
+    {
+      "name": "Learn the rhythm for future calls",
+      "when": "After the call (success or fail).",
+      "script": "Log: time of call, total hold time, time-to-first-rep, time-to-resolution. After 2-3 calls you have your own dataset on this company's actual queue rhythm — far more accurate than generic advice.",
+      "priority": 8
+    }
+  ],
+  "boundaries": [
+    "Do NOT vent frustration at the rep when they pick up — they didn't make you wait, the staffing did. Venting destroys your one chance to get help.",
+    "Do NOT hold longer than 60 minutes without a clear reason (specific specialist queue, or you can confirm you're #1-2 in line).",
+    "Do NOT hang up and call back in the same minute hoping for a different agent — most queues route by phone number for ~5-10 minutes, and you'll just get the same queue position.",
+    "Do NOT accept the same 'hold a few more minutes' from a rep for the third time. That's a stall pattern — see `detect-fake-escalation-loops`.",
+    "Do NOT abandon a confirmed callback by not answering the callback call. Some companies blacklist your number from callbacks if you miss two.",
+    "Do NOT take any escalation action (regulator, executive office) just because of hold time alone — long holds are annoying but not actionable. They become evidence when paired with substantive refusals."
+  ],
+  "success_signals": [
+    "Rep gives you an honest ETA when you ask.",
+    "Callback option is offered and preserves queue position.",
+    "Live rep picks up in <15 minutes from initial call.",
+    "Hold music is interrupted with periodic position updates ('you are caller number 3').",
+    "Different/quieter hold tone after a transfer — you've left the main queue."
+  ],
+  "failure_signals": [
+    "No ETA offered, or ETAs that keep increasing.",
+    "Hold music with no position updates and no rep check-ins for 20+ minutes.",
+    "Hold then disconnect (line drops while holding) — common stall pattern.",
+    "Rep picks up briefly, says 'one moment', then puts you on a fresh hold cycle.",
+    "Callback option offered but with a scheduled window 'within the next 24-72 hours' (effectively a ghost callback)."
+  ],
+  "exit_strategy": {
+    "on_success": "Once a rep is on the line, transition to the appropriate escalation skill (`get-past-tier-1-script` or `request-supervisor-gracefully`). Log total time-to-rep for future planning.",
+    "on_failure": "Hang up cleanly, log the attempt, schedule a retry at a strategically different hour. If two attempts at different hours both fail to reach a rep, pivot channels — `multi-channel-escalation`.",
+    "follow_ups": [
+      "Track hold-time data points in a personal log. After 3 attempts, you'll know this company's real rhythm.",
+      "If hold times consistently exceed 45 minutes, that itself is evidence for an FCC/regulator complaint (some industries have service-level obligations) — but verify jurisdiction first.",
+      "Consider whether the issue actually needs a phone call. Many issues are better-served by chat, email, or even a written letter to the corporate office."
+    ]
+  },
+  "required_user_info": [
+    "User's available time window for the call",
+    "Whether speakerphone or headset is available (free attention while holding)",
+    "Time zone of the call center (often different from user's time zone)",
+    "Whether prior calls to this company succeeded — and at what time of day",
+    "Whether the user can accept callbacks during work hours"
+  ],
+  "contributed_by": "support-escalator agent (v0.9.87 community drop)",
+  "updated_at": "2026-05-20T06:09:47Z"
+}