Cashback Card

View saved version →

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

# Find Best Cashback

Answer one question precisely: **for this purchase, at this merchant, in this country, which card in this wallet nets the most money?**

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

## The one rule that matters

**Never state a reward rate from memory.** Every rate you quote comes from one of three places, and you must say which:

| Source | How to label it |
| --- | --- |
| Live issuer page you just read | "verified today at [link]" |
| Bundled catalog in `data/` | "catalog snapshot from *as_of*, worth confirming" |
| The user told you | "per the terms you gave me" |

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

## Step 1 - Get the four inputs

You need: **merchant**, **country**, **cards held**, and — only when it changes the answer — **amount** and **channel**.

- Country: infer from context if the signal is strong (₹ or a named Indian merchant → India). Otherwise ask.
- Cards: check for a saved wallet first (see *Wallet* below). If none exists, ask for **card product names only**.
- 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.
- Channel: ask when the merchant codes differently by channel and the difference flips the winner. `--explain-merchant` tells you when that is true.

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

## Step 2 - Resolve how the merchant codes

```bash
python scripts/rank_cards.py --explain-merchant walmart --country US
```

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

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

Merchant 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".

## Step 3 - Score the wallet

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

```bash
python scripts/rank_cards.py request.json
```

```json
{
  "purchase": {
    "merchant": "shell", "channel": "pump", "amount": 60,
    "country": "US", "currency": "USD"
  },
  "wallet": [
    "amex-bcp",
    {"id": "chase-freedom-flex", "activated": true,
     "cap_used": {"chase-rotating": 1200}},
    {"id": "discover-it", "offers": [
      {"label": "10% back up to $15", "type": "percent", "value": 10, "cap": 15}]}
  ]
}
```

Run `--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.

The engine deliberately refuses to invent anything. What it hands back:

- `net_reward` — bonus earning + base earning + stacked offers − fees
- `applied_rule` and `rules_rejected` — *why* each card landed where it did
- `cap_binding` — the bonus rate ran out partway through this purchase
- `earning_blocked` — the card earns nothing here (Indian fuel, unaccepted network)
- `confidence` — the weakest link across merchant coding, rule certainty and data age

Pass `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.

## Step 4 - Verify before you commit

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

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

Never sign in, activate an offer, apply for a card, or change an account. Tell the user what to click; let them click it.

## Step 5 - Answer

Lead with the verdict, in one line:

> **Use the Blue Cash Preferred — about 3% back, ≈$1.80 on a $60 fill-up.**

Then, briefly:

- **Why it wins** — the rule that applied, in plain words.
- **Runner-up** and what it would have earned, so the user can judge whether it is worth caring.
- **What would change this** — the cap, activation, channel, or coding risk that could flip it. Only list ones that realistically could.
- **Confidence and date** — where the numbers came from and when they were checked.

Keep it to a short paragraph and a few bullets. A wallet-sized answer beats a table of every card.

### Say what you actually know

- Rates and money: "about 3%", "roughly $1.80" — the underlying rate is exact, the coding is not.
- Coding: "likely codes as a gas station", "Supercenters are normally excluded from grocery categories".
- 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."
- Ties under a cent: say they are tied and break it on redemption friction, not on the decimal.
- 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*.

### Things that are easy to get wrong

- A card that misses the bonus category still earns its base rate. It is not disqualified.
- 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.
- 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.
- 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".
- Welcome bonuses are not ongoing cashback. Keep them in a separate sentence if you mention them at all.

## Market-wide mode

Only 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".

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

## Wallet

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

## References

- [merchant-coding.md](references/merchant-coding.md) — how specific store types behave and why
- [data-schema.md](references/data-schema.md) — the catalog format, for adding a card or merchant

Referenced files: 9

View saved version →

---
name: manage-wallet
description: Save, update, list or clear the set of credit cards a user holds, so card recommendations do not have to ask every time. Use when the user says which cards they have, asks to remember or forget a card, wants to see their saved cards, or reports that a spending cap or rotating category has changed.
---

# Manage Wallet

Keep a small local file of which cards the user holds, so `find-best-cashback` can answer "which card at Shell?" without re-asking.

## What goes in the file

Product identities and reward-relevant state. Nothing else.

Store: card ids, the user's country, chosen categories, activation status, and cap usage they have told you about.

**Never store**: card numbers, CVV, expiry dates, PINs, names as they appear on the card, credit limits, balances, statement PDFs, or login credentials. This file is plain text on disk. If the user offers a card number, tell them you do not need it and that the product name is enough.

## Location

`~/.cashback-wallet.json` — expand `~` yourself; the engine does not.

## Format

```json
{
  "version": 1,
  "country": "US",
  "updated": "2026-07-25",
  "cards": [
    {"id": "amex-bcp", "nickname": "the blue one"},
    {"id": "chase-freedom-flex", "activated": true,
     "cap_used": {"chase-rotating": 1200},
     "note": "Q3 rotating category is gas stations"},
    {"id": "boa-customized-cash", "chosen_category": "online_retail"}
  ]
}
```

Card ids come from the catalog:

```bash
python ../find-best-cashback/scripts/rank_cards.py --list-cards US
```

If the user names a card that is not in the catalog, still save it — record what they told you so it is not lost:

```json
{"id": "local-credit-union-visa", "in_catalog": false,
 "user_terms": "2% everywhere, no annual fee, told to me 2026-07-25"}
```

`find-best-cashback` will pass that through as an inline card definition rather than dropping it.

## Reading it

Read the file before asking the user which cards they hold. If it does not exist, ask once and offer to save the answer — do not save without being asked or agreeing first.

## Writing it

Rewrite the whole file; do not append. Always set `updated` to today.

Before overwriting an existing wallet, read it and confirm what changes: adding a card is safe to just do, but removing or replacing the list should be echoed back ("dropping the Discover it, keeping the other three — right?").

## Cap and activation state goes stale

`cap_used` and `activated` are true on the day they were written and drift immediately afterwards. When a saved value is more than a few weeks old, or when the calendar has crossed into a new quarter, treat it as unknown and re-ask rather than computing on it. A confidently wrong cap number produces a confidently wrong recommendation.

Rotating categories reset quarterly. A saved `activated: true` from last quarter means nothing this quarter.

## Clearing

If the user asks you to forget their cards, delete the file rather than emptying it, and confirm afterwards that it is gone.

Referenced files: 1