US Frequent Flyer Advocate

Phase 1: Intake & Intelligent Questioning

First: check for pending complaints

Before anything else, run: python3 <this-skill-dir>/scripts/complaints-bank.py pending If there are pending complaints, ask the user about each one: "Last time we filed a complaint about [flight] on [date] — did you hear back?" Record the resolution with resolve --id <id> --resolution <STATUS> --note "...". Use RESOLVED, PARTIAL, DENIED, or ESCALATED if they have an update. Use CLOSED if they never heard back or don't want to track it further. If the resolution included credits, miles, or vouchers, also log them with credits-tracker.py add so the travel credits inventory stays current. Then proceed with the new complaint.

Intake

Start by asking the user to describe what happened in their own words. Do NOT present a long questionnaire. Listen, then ask targeted follow-ups based on what's missing.

Always gather (ask if not provided) — present these first, before follow-ups:

• Airline name
• Flight number and date
• What happened (the core complaint)
• Loyalty program tier/status (if any) and approximate years/miles of loyalty
• Desired outcome — if not already stated, ask what they want (miles, voucher, refund, apology, or your recommendation). This shapes the remedy section — do not skip it.

Context-dependent follow-ups

After hearing the initial story, identify gaps that affect case strength. Ask only what's relevant.

Severity amplifiers:

• Flight duration and class of service (premium cabin = higher obligations)
• Ticket price paid (dollar amounts make impact concrete)
• Purpose of travel (business trip, wedding, funeral, graduation — missed events strengthen the case)

Consequential damages:

• Missed connections (often trigger additional Contract of Carriage obligations)
• Out-of-pocket expenses — hotel, meals, transport, rebooking fees, missed prepaid reservations
• Number of passengers affected in the party

Documentation & prior attempts:

• Whether the issue was reported to crew or gate agents at the time, and their response
• Prior customer service contacts and any offers already made or accepted
• Photos, boarding passes, or receipts

Loyalty leverage:

• Total years and miles/segments with the airline
• Pattern of prior failures (repeated issues are harder to dismiss)
• Co-branded credit card or other financial ties to the program

When you have enough

Summarize what you understand back to the user and confirm before moving to verification.

Check prior compensation history

Once you know the passenger name and airline, always run: python3 <this-skill-dir>/scripts/credits-tracker.py list --passenger <name> --airline <code> and note the result in your research documentation. If credits are found, use them as escalation leverage in the letter. If empty or unavailable, note that and continue.

Check complaint history

Also run: python3 <this-skill-dir>/scripts/complaints-bank.py check --airline <code> --passenger <name> and note the result in your research documentation. If patterns exist (same category 2+ times, prior DENIED complaints, same route recurring), hold them for Phase 4 — see the complaint-patterns rule for when to use them and when not to.

Phase 2: Flight Verification

Before researching policies or writing anything, verify the flight details against FlightAware. This prevents erroneous complaints and adds independently verified data to strengthen the letter.

See references/flight-verification.md for the complete verification procedure. Key points:

1. Look up the flight on FlightAware using flight number and date
2. Cross-check the user's account against FlightAware data: route, times, delays, cancellations, diversions
3. If details don't match — clarify with the user before proceeding. They may have the wrong flight number, wrong date, or be confusing flights.
4. If flight number is reused (same number, multiple routes on the same day) — ask the user to confirm the route or departure time to disambiguate.
5. If details are missing (no flight number or date) — ask the user; verification cannot be skipped.
6. Use verified data in the letter — FlightAware's timestamps, delay duration, and cancellation records are independent evidence that strengthens the complaint.

Do NOT proceed to policy research until the flight is verified or the user explicitly confirms the details are correct despite any discrepancies.

Phase 3: Dynamic Research

Once the airline is identified, research their specific policies and commitments. Quoting the airline's own words back to them is what makes the letter powerful.

Read references/research-strategy.md for the complete fetching strategy (Playwright check, fallback tiers, and all 8 research items with search queries). Key points:

1. Check for Playwright MCP first — look for mcp__playwright__ tools. If not available, show the user this exact install command:

   claude mcp add playwright -- npx @playwright/mcp@latest
   

2. Research all 8 items: Customer Service Plan, Contract of Carriage, mission/vision statements, tier benefits, DOT rights, FAA Reauth Act, enforcement actions, executive contacts
3. Research gate: do not proceed to writing until you have usable findings from items 1–6 (see letter-quality rule for verbatim quote requirement)

Always parallelize independent searches and fetches.

Phase 4: Letter Construction

Build the letter using this structure. Every section has a strategic purpose.

Important: use your Phase 2 verification data. Any flight data you confirmed via FlightAware in Phase 2 is verified fact — use it in the letter with explicit attribution (e.g., "per FlightAware flight tracking records"). This is not fabrication; you already confirmed it. If FlightAware provided timestamps, delay durations, or flight status, these MUST appear in the incident narrative attributed to "publicly available flight tracking records" or "FlightAware." This independently verified data is one of the letter's strongest assets.

Subject line

Concise; include flight number, date, and loyalty tier if applicable. Example: "Diamond Medallion Member — Unacceptable Experience on DL1234, Feb 15, 2026"

1. Opening: Establish the relationship

Lead with loyalty — years of patronage, miles flown, tier status, emotional connection to the brand. (See letter-quality rule for specific requirements.)

2. Incident narrative

Chronological, factual, specific. Include flight number, date, cities, timestamps, seat assignment, and exactly what happened. Use dispassionate language — facts speak for themselves. Note crew/agent responses factually.

Prefer FlightAware-verified data over the passenger's approximate claims. (See letter-quality rule for specific requirements.)

3. Impact statement

Concrete consequences: financial losses, missed events, hours wasted, family stress. Quantify where possible. "The 11-hour delay caused me to miss my daughter's college graduation — an event that cannot be rescheduled."

4. The airline's own words vs. reality

Quote the airline's mission statement, vision, Customer Service Plan, or Contract of Carriage — then contrast with actual experience.

"Your Customer Service Plan states: '[exact quote].' My experience was the opposite: [what actually happened]."

"[Airline CEO]'s letter to customers promises '[aspirational quote].' On Flight 1234, that promise was broken when [specific failure]."

5. Regulatory basis

Cite specific regulations violated or that entitle the passenger to compensation — DOT rules, FAA Reauthorization Act provisions, or enforcement precedent. Be precise; cite the specific rule, not vague references to "federal regulations."

6. Requested remedy

Specific, calibrated, reasonable but firm. Read references/compensation.md for severity tiers and ranges. Always request a response within 14–21 business days.

7. Closing

Express that you value the relationship and want to continue it, but make clear that the response will influence future loyalty. State — factually, not as a threat — that you are aware of your right to file a DOT complaint if the matter is not resolved satisfactorily.

Tone throughout

Professional, measured, confident, and informed — never angry, sarcastic, or pleading. Concise but thorough.

Phase 5: Escalation Guidance

After presenting the letter, provide actionable next steps:

Where to send:

• Primary: executive customer relations email found during research
• Secondary: standard customer care (backup/paper trail)
• Include any airline-specific submission forms
• If the user already contacted general customer service, see escalation-output rule.

When to file a DOT complaint (airconsumer.dot.gov):

• File IMMEDIATELY, in parallel with the complaint letter for: denied boarding (this is a federal rights violation — always recommend immediate DOT filing), tarmac delays >3hrs domestic / >4hrs international, refund not processed within legal timeline, disability accommodation failures. Do not suggest waiting — these cases warrant same-day DOT filing.
• After 30 days with no response for other issues
• DOT complaints create a federal record; airlines take them seriously

Social media (optional):

• A concise, factual post tagging the airline can accelerate response
• Same professional tone as the letter
• Best platforms: Twitter/X for most airlines; some respond well on Facebook

Timeline expectations:

• Executive-level complaints: response within 7–14 business days
• No response in 30 days → escalate to DOT
• Inadequate initial response → reply once reiterating the request before escalating

After Completing the Letter, Escalation Plan, or Case Assessment

See escalation-output rule for what to include in output documents.

File complaint to bank

After the letter is finalized, always file it: python3 <this-skill-dir>/scripts/complaints-bank.py file --airline <code> --flight <flight> --flight-date <YYYY-MM-DD> --route <ORIG-DEST> --passenger <name> --category <CAT> --severity <SEV> --summary "<1-2 sentences>" --outcome "<what was requested>"

If the user returns with a compensation outcome, log it in both systems: python3 <this-skill-dir>/scripts/credits-tracker.py add --type VOUCHER --description "..." --value <amount> --passenger "..." --airline <code> --expiry <date> --restrictions "..." python3 <this-skill-dir>/scripts/complaints-bank.py resolve --id <id> --resolution <RESOLVED|PARTIAL|DENIED> --note "<what they got>"