Set Checklist Tracker

---
name: set-checklist-tracker
description: Tracks progress on a trading card or sports card set by comparing a set checklist with the cards the user owns. Gives completion by subset and parallel, a want list of missing cards, spares to trade, and problems to check (wrong numbers, name mismatches, cards from another set, unknown parallels). Handles Pokémon and TCG numbering like 025/165, card numbers with prefixes, reverse holos and other parallels, and multiple rows for the same card. Use when the user says things like "what am I missing from this set", "make my want list", "how close am I to completing the set", "track my master set", "which cards are duplicates", "what can I trade", or shares a checklist and a collection list. It needs a checklist file from the user (or one built with them); it does not download checklists.
---

# Set Checklist Tracker

Compare a set checklist with the user's cards and give them three lists they can act on: what's missing, what's spare, and what looks wrong.

Rules:

1. **The checklist is the user's.** Use a checklist they supply or one you build together from a source they name. Never fill in a set's card list from memory. Names, numbers and parallels from memory are often wrong.
2. **Never change their files.** Reports go to the chat or to new files.
3. **Flag, don't fix.** If a card doesn't match, list it. Don't guess what they meant.

## Bundled files

| File | When to use it |
|---|---|
| `scripts/checklist.mjs` | Step 3. Compares the two CSVs and prints the report. With `--out-dir` it also writes `want-list.csv` and `trade-list.csv` (never overwrites). Node.js 18+. |
| `references/checklist-sources.md` | Step 1. Where checklists come from, the columns to use, master sets versus base sets, and sports and TCG numbering quirks. |
| `examples/` | An invented 20-card set ("Tidepool Legends") with reverse holos and secret rares, a messy owned list, both reports, the CSV outputs, a walk-through and test runs. |

## Step 1: Get the checklist

Ask what they're tracking:
- **The base set**, any version counting.
- **A master set**: every parallel, such as reverse holos.
- **One subset or insert.**

Then get a checklist CSV with at least `number` and `name`. Add `parallel`, `subset` and `rarity` columns when relevant.

- If they have a PDF, a web page or a pasted list, turn it into a CSV with them. Write it to a new file (for example `<set>-checklist.csv`) and ask them to confirm the card count against the source.
- For a master set, list each parallel as its own row (number, name, parallel).
- See `references/checklist-sources.md` for sources and numbering quirks.

## Step 2: Get their cards

Ask for a CSV with at least `number`. `name`, `parallel`, `qty`, `set` and `condition` help. If they paste a list, build the CSV and keep their wording; the script handles "#7", "007/020" and "7" as the same number.

If several sets are mixed in one file, include a `set` column and pass `--set-name`, so other sets are left out of the counts.

## Step 3: Run

```
node <skill-folder>/scripts/checklist.mjs <checklist.csv> <owned.csv> --set-name "<set>" [--parallel-map "rev holo=reverse holo,rh=reverse holo"] [--ignore-parallel] [--out-dir <folder>]
```

- Run once and read "Check these". If owned parallels aren't recognised (for example "RH", "rev holo"), add a `--parallel-map` and run again.
- `--ignore-parallel` counts any version of a card number as owned. Use it for base-set progress.
- `--out-dir` writes `want-list.csv` and `trade-list.csv`, which are ready to share or print.

Without Node.js, compare small lists by hand (under about 100 cards). Say the script wasn't run.

## Step 4: Report back

1. **Completion**: the headline figure, then each subset and parallel if there's more than one.
2. **Want list**: the missing cards. For long lists, group by subset or rarity and offer the CSV.
3. **Spares**: duplicates with spare counts, the starting point for trades.
4. **Check these**, each with what to do:
   - **Name mismatches** (counted as owned): a typo is harmless. A different card (for example a card filed under the wrong number) means the count is wrong. Use the hint column.
   - **Not on the checklist**: wrong number, unknown parallel name, or a card from a different set or year.
   - **Other sets** that were left out, and **unreadable quantities** that were counted as 1.
5. **Files written**, if `--out-dir` was used.

Offer next steps: a printable want list for a card show, a trade list post, or a re-run after they update their list.

## Rules

- Report the counts the script gives. Don't recount by hand.
- Don't say a set is complete unless the report says so, and remind the user it's complete against *their* checklist.
- Don't put prices on the want or trade list unless the user supplies them.