Benefits Decoder

SKILL.md

---
name: benefits-decoder
description: "Decode an employment benefits package into what it's actually worth and where the fine print bites. Use when someone asks 'is this offer good', 'decode my benefits package', 'what does my equity actually mean', or 'what should I ask HR before signing'. Produces a benefit-by-benefit decode with real dollar values, ranked red flags (vesting cliffs, clawbacks, 'discretionary' bonuses, unlimited-PTO economics), and the questions to ask HR before signing."
homepage: https://mohitagw15856.github.io/pm-claude-skills/skill/benefits-decoder.html
metadata:
  {
    "openclaw": { "emoji": "🧠" }
  }
---

# 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.