benefits-decoder

Benefits Decoder Skill

"Total compensation" decks are marketing. This skill reads the plan language like a friend who's been burned before: what each benefit is really worth, which promises have escape hatches, and what to get in writing before you sign.

What This Skill Produces

• A benefit-by-benefit decode with real annual values where computable
• Ranked red flags: vesting cliffs, clawbacks, "discretionary" everything, coverage gaps
• The 401k/pension match math and the equity math, arithmetic shown
• Questions to ask HR before signing — and which answers to get in writing

Required Inputs

Ask for these only if they aren't already provided:

• The benefits documents — offer letter, benefits summary, equity grant terms, plan excerpts. Decode what's provided; list what's still needed (equity plan, insurance summary of benefits, bonus plan terms).
• Base salary and equity grant details if not in the text — needed for the math.
• Their situation — dependents/health needs, how long they realistically expect to stay.

Framework: Severity Scale

• 🔴 Can cost you real money — vesting cliffs vs. their expected tenure, clawbacks (signing bonus, relocation, tuition, even vested equity on "cause" triggers), bonuses payable only if "employed on payment date," short post-exit equity exercise windows, high deductibles behind a good headline, match forfeiture via vesting.
• 🟡 Unusual — clarify before signing — "discretionary" bonus language (decode it plainly: a target, not a promise), unlimited PTO (decode the economics: no accrued payout at exit), benefits changeable "at company discretion," waiting periods.
• 🟢 Standard — normal enrollment windows, standard vesting shapes, typical plan boilerplate; label them so the reader knows what's fine.

Always show the math:

1. Match math — e.g. "50% of the first 6%" = X/year at their salary; note the match's own vesting and what leaving at year N forfeits.
2. Equity math — grant ÷ vesting years = annual value at stated valuation, with the cliff scenario ("leave at month 11 = 0"); mark valuation-dependent numbers [to confirm].
3. Insurance actual-coverage read — premium share, deductible, out-of-pocket max: the worst-case year in dollars, not the brochure line.
4. PTO economics — unlimited vs. accrued: the exit-payout difference in dollars.

Output Format

Benefits Decode: [company / offer]

1. The verdict — what this package is really worth per year (range, assumptions stated), and the two things to resolve before signing.

2. Benefit-by-benefit decode

Benefit	What the document says	What it's really worth / really means	Severity

3. 🚩 Red flags, ranked — quoted language, the scenario where it bites, its dollar cost.

4. The math section — match, equity, insurance worst-case, PTO — arithmetic shown.

5. Questions for HR before signing — 4–7, ordered by money at stake; mark which answers to get in writing (bonus terms, equity plan document, clawback triggers).

6. What's negotiable — typically the one-time items (signing bonus, equity, start date, relocation) more than the plans themselves.

End the artifact with, verbatim: "This is a plain-language reading, not legal/financial advice — laws vary by jurisdiction; confirm anything load-bearing with a qualified professional."

Quality Checks

• Every valuation is shown as arithmetic with stated assumptions, not asserted
• "Discretionary" and "employed on payment date" language is quoted and decoded bluntly
• Cliff/clawback flags are tied to the user's stated expected tenure
• Missing documents and unverifiable numbers are listed as [to confirm]
• Genuinely standard terms are marked 🟢 — not everything is a trap
• The disclaimer line appears verbatim in the artifact

Anti-Patterns

• Do not invent benefits or terms that aren't in the documents
• Do not soften a red flag to seem balanced — "discretionary" means no bonus is owed; say it
• Do not present jurisdiction-dependent rules (PTO payout, clawbacks) as universal
• Do not take equity at face value without flagging the valuation assumption
• Do not let the "total comp" headline stand — rebuild it from the plan language

Based On

Offer-review practice — total-comp reconstruction, plan-language decoding, pre-signing question lists.