Update to Cashback Card

{
  "name": "find-best-cashback",
  "description": "Work out which credit card in someone's wallet earns the most on a purchase at a named store - Shell, Target, Walmart, Costco, Amazon, Swiggy, Tesco, a restaurant, a supermarket. Use when the user names a merchant and asks which card to use, what earns the most cashback or rewards there, how a store is likely to code, why a card did not earn a bonus rate, or which new card would be best for a merchant they shop at often. Covers the US, India and the UK.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 201
    },
    {
      "relative_path": "data/cards-gb.json",
      "size_in_bytes": 6107
    },
    {
      "relative_path": "data/cards-in.json",
      "size_in_bytes": 15044
    },
    {
      "relative_path": "data/cards-us.json",
      "size_in_bytes": 20283
    },
    {
      "relative_path": "data/merchants.json",
      "size_in_bytes": 25583
    },
    {
      "relative_path": "references/data-schema.md",
      "size_in_bytes": 6365
    },
    {
      "relative_path": "references/merchant-coding.md",
      "size_in_bytes": 5314
    },
    {
      "relative_path": "scripts/rank_cards.py",
      "size_in_bytes": 33003
    },
    {
      "relative_path": "scripts/test_rank_cards.py",
      "size_in_bytes": 20604
    }
  ],
  "skill_md_contents": "---\r\nname: find-best-cashback\r\ndescription: Work out which credit card in someone's wallet earns the most on a purchase at a named store - Shell, Target, Walmart, Costco, Amazon, Swiggy, Tesco, a restaurant, a supermarket. Use when the user names a merchant and asks which card to use, what earns the most cashback or rewards there, how a store is likely to code, why a card did not earn a bonus rate, or which new card would be best for a merchant they shop at often. Covers the US, India and the UK.\r\n---\r\n\r\n# Find Best Cashback\r\n\r\nAnswer one question precisely: **for this purchase, at this merchant, in this country, which card in this wallet nets the most money?**\r\n\r\nThe hard part is not arithmetic. It is that a card's headline rate frequently does not apply — because the merchant codes as a superstore, because a cap is already used up, because the category was never activated, or because the points are worth less than a cent. This skill exists to catch those cases.\r\n\r\n## The one rule that matters\r\n\r\n**Never state a reward rate from memory.** Every rate you quote comes from one of three places, and you must say which:\r\n\r\n| Source | How to label it |\r\n| --- | --- |\r\n| Live issuer page you just read | \"verified today at [link]\" |\r\n| Bundled catalog in `data/` | \"catalog snapshot from *as_of*, worth confirming\" |\r\n| The user told you | \"per the terms you gave me\" |\r\n\r\nIf a number decides the recommendation and you could not verify it, say so in the answer. Do not launder a stale rate into a confident sentence.\r\n\r\n## Step 1 - Get the four inputs\r\n\r\nYou need: **merchant**, **country**, **cards held**, and — only when it changes the answer — **amount** and **channel**.\r\n\r\n- Country: infer from context if the signal is strong (₹ or a named Indian merchant → India). Otherwise ask.\r\n- Cards: check for a saved wallet first (see *Wallet* below). If none exists, ask for **card product names only**.\r\n- Amount: ask only when a cap, a fixed-value offer, a minimum spend, or a fee could change the winner. For \"which card at Shell?\" a representative amount is fine — say which you assumed.\r\n- Channel: ask when the merchant codes differently by channel and the difference flips the winner. `--explain-merchant` tells you when that is true.\r\n\r\nAsk at most one consolidated question. Never request a card number, CVV, expiry, PIN, login, or statement. If the user pastes one, tell them to rotate nothing but redact it, and continue from the product name alone.\r\n\r\n## Step 2 - Resolve how the merchant codes\r\n\r\n```bash\r\npython scripts/rank_cards.py --explain-merchant walmart --country US\r\n```\r\n\r\nThis returns the spend categories, likely MCCs, a confidence level, and the known traps for that merchant. Read the caveats — they are the substance of a good answer.\r\n\r\nIf the merchant is not in the table, research it or ask the user how similar purchases have posted before. Do not guess a category from the brand name alone.\r\n\r\nMerchant category codes are set by the merchant's acquiring bank, not by the card issuer. A franchise location, a separate fuel forecourt, an in-app payment, or a third-party delivery order can all code differently from the flagship store. Say \"likely to code as\", never \"codes as\".\r\n\r\n## Step 3 - Score the wallet\r\n\r\nBuild a request and run the engine. Do not do this arithmetic in your head — caps, slabs, point values and fees interact in ways that are easy to get wrong.\r\n\r\n```bash\r\npython scripts/rank_cards.py request.json\r\n```\r\n\r\n```json\r\n{\r\n  \"purchase\": {\r\n    \"merchant\": \"shell\", \"channel\": \"pump\", \"amount\": 60,\r\n    \"country\": \"US\", \"currency\": \"USD\"\r\n  },\r\n  \"wallet\": [\r\n    \"amex-bcp\",\r\n    {\"id\": \"chase-freedom-flex\", \"activated\": true,\r\n     \"cap_used\": {\"chase-rotating\": 1200}},\r\n    {\"id\": \"discover-it\", \"offers\": [\r\n      {\"label\": \"10% back up to $15\", \"type\": \"percent\", \"value\": 10, \"cap\": 15}]}\r\n  ]\r\n}\r\n```\r\n\r\nRun `--help` for the full schema and `--list-cards US` for the available ids. A card the user holds that is not in the catalog is reported as `unknown` rather than scored — research its terms and pass them inline as a `card` object, or ask the user.\r\n\r\nThe engine deliberately refuses to invent anything. What it hands back:\r\n\r\n- `net_reward` — bonus earning + base earning + stacked offers − fees\r\n- `applied_rule` and `rules_rejected` — *why* each card landed where it did\r\n- `cap_binding` — the bonus rate ran out partway through this purchase\r\n- `earning_blocked` — the card earns nothing here (Indian fuel, unaccepted network)\r\n- `confidence` — the weakest link across merchant coding, rule certainty and data age\r\n\r\nPass `cap_used`, `activated` and `offers` whenever the user has told you about them. Assuming an unactivated rotating category is live, or that a monthly cap is untouched, is the most common way this answer goes wrong.\r\n\r\n## Step 4 - Verify before you commit\r\n\r\nVerify live when the recommendation is decided by a rate whose catalog confidence is `low` or `medium`, when the data is stale, when the user is about to make a large purchase, or when they ask you to be certain.\r\n\r\nPrefer the issuer's own benefits page, rewards terms, or the offer's terms. Use blogs and forums to *find* a candidate or to understand ambiguous coding — never as the final authority on a rate. Record what you checked and when.\r\n\r\nNever sign in, activate an offer, apply for a card, or change an account. Tell the user what to click; let them click it.\r\n\r\n## Step 5 - Answer\r\n\r\nLead with the verdict, in one line:\r\n\r\n> **Use the Blue Cash Preferred — about 3% back, ≈$1.80 on a $60 fill-up.**\r\n\r\nThen, briefly:\r\n\r\n- **Why it wins** — the rule that applied, in plain words.\r\n- **Runner-up** and what it would have earned, so the user can judge whether it is worth caring.\r\n- **What would change this** — the cap, activation, channel, or coding risk that could flip it. Only list ones that realistically could.\r\n- **Confidence and date** — where the numbers came from and when they were checked.\r\n\r\nKeep it to a short paragraph and a few bullets. A wallet-sized answer beats a table of every card.\r\n\r\n### Say what you actually know\r\n\r\n- Rates and money: \"about 3%\", \"roughly $1.80\" — the underlying rate is exact, the coding is not.\r\n- Coding: \"likely codes as a gas station\", \"Supercenters are normally excluded from grocery categories\".\r\n- Points: always state the assumed value. \"4x Membership Rewards, worth about $3.60 if you transfer to airline partners — closer to $2 as a statement credit.\"\r\n- Ties under a cent: say they are tied and break it on redemption friction, not on the decimal.\r\n- Never say a card is \"the best card\" without a scope. It is best *for this purchase, at this merchant, in this country, among these cards*.\r\n\r\n### Things that are easy to get wrong\r\n\r\n- A card that misses the bonus category still earns its base rate. It is not disqualified.\r\n- Instant checkout discounts (Target Circle Card) are not the same as accrued cashback, and annual redemption certificates (Costco) are not spendable today. Flag the difference.\r\n- An annual fee belongs to the card, not to one purchase. Never amortise it into a single transaction — but do include it when comparing a card the user might newly open.\r\n- In India, most cards earn **zero** on fuel and instead waive a 1% surcharge within a monthly cap. The right answer at a petrol pump is usually \"the one that waives the surcharge\", not \"the one with the best rate\".\r\n- Welcome bonuses are not ongoing cashback. Keep them in a separate sentence if you mention them at all.\r\n\r\n## Market-wide mode\r\n\r\nOnly when the user asks for a *new* card — \"what card should I get for groceries?\" — widen to the whole catalog plus live research. In that mode include the annual fee, a realistic break-even at the user's stated spend, and any membership or eligibility constraint. Say plainly when the honest answer is \"your current card is fine; a new one would not pay for itself\".\r\n\r\nYou are not a licensed financial adviser. Comparing published reward terms is fine. Telling someone whether to open a credit line, carry a balance, or restructure their finances is not — say so and stop.\r\n\r\n## Wallet\r\n\r\nIf a saved wallet exists at `~/.cashback-wallet.json`, read it instead of asking. See the `manage-wallet` skill for the format and for adding, updating, or clearing cards. Never write card numbers to it — product ids only.\r\n\r\n## References\r\n\r\n- [merchant-coding.md](references/merchant-coding.md) — how specific store types behave and why\r\n- [data-schema.md](references/data-schema.md) — the catalog format, for adding a card or merchant\r\n"
}