Reckoner tracker

Reckoner — Money Tracker

This skill turns messy, multi-institution statements into one clean spreadsheet. The user pulls statements from several accounts (checking, credit cards, savings, brokerage) and wants them merged into a single tracker, then filed somewhere they keep their records.

The hard part is not the spreadsheet — the bundled build_tracker.py handles that deterministically. The hard part is reading messy statements correctly and classifying each line, especially telling real spending apart from money that is just moving between the user's own accounts. Get the classification right and the totals take care of themselves.

First: read the user's config

Personal settings live in config.json (the user copied it from config.example.json). Read it before classifying. It defines:

• categories — the spending buckets the Summary tab sums on.
• accounts — the account names to use in the account field.
• merchant_cues — optional hints mapping kinds of merchants to categories.
• currency, output_dir, monthly_plan, plan_notes.

First-run setup — interview, don't point at a file. If config.json does not exist, offer to set it up by asking a few quick questions, then write config.json for them (use config.example.json as the base):

1. What currency do you use? (symbol, e.g. $, £, €)
2. Which accounts should I track? (e.g. Checking, Credit Card, Savings, Investments)
3. Where should the spreadsheet be saved? (default ~/Documents/Reckoner)
4. The default spending categories are: Housing, Utilities, Groceries, Dining, Transport, Subscriptions, Health, Shopping, Entertainment, Travel, Other. Keep them, or change/add/remove any?
5. (Optional) A rough monthly plan — income and a few target amounts.

Ask one or two at a time, keep it light, and let them accept the defaults for anything. Write their answers into config.json and confirm. If they'd rather not set up now, fall back to the bundled defaults and tell them which were used.

Workflow

1. Gather the raw input. The user may give CSVs, PDFs, screenshots, or pasted text, one file per institution or several at once. Read all of them. If something is ambiguous (a cryptic merchant code, a transfer with no description), ask — a wrong guess pollutes the totals.

2. Normalise every transaction into this exact schema (one object per line):

   {"date":"2026-06-04","account":"Credit Card","description":"Joe's Diner",
    "category":"Dining","flow_type":"Spending","amount":-18.89,"notes":""}
   

   • amount: spending is NEGATIVE, money received is POSITIVE. This sign convention is what makes the spreadsheet formulas work — don't flip it.
   • date: ISO YYYY-MM-DD.
   • account: use one of the user's configured account names.
   • category: only set it for Spending rows (one of the configured buckets). Leave it blank for everything else.

3. Classify the flow_type — this is the crux. See the table below.

4. De-duplicate money movement. This is the single most important judgement. A statement shows the same dollars in several places: a credit-card purchase appears on the card statement, and the checking payment that pays off the card appears on the checking statement. The purchase is the spending; the card payment is not — counting both double-counts. Likewise a transfer to savings or a brokerage is not spending. Mark these as Card Payment / Internal so they're reported separately and kept out of the spending total.

5. Write the normalised list to a JSON file (the schema at the top of scripts/build_tracker.py), then run the bundled builder:

   python3 "${CLAUDE_SKILL_DIR}/scripts/build_tracker.py" <transactions.json>
   

   ${CLAUDE_SKILL_DIR} resolves to this skill's folder wherever it is installed. (If your agent doesn't set that variable, use the path to scripts/build_tracker.py inside this skill directory.) With no output path it writes to <output_dir>/<year>/<Month>_<Year>_Money_Tracker.xlsx (output_dir from config). The script builds all three sheets, the SUMIFS formulas, and the colour-coded sections — never hand-build the xlsx, and never hardcode the totals (they must be live formulas so the user can tweak a row and watch everything recompute).

6. Show the summary (total in, total spending, net, by-category) and the output path. If the reckoner-advisor skill is present, offer to review the month against the user's goals.

Flow types (the classification that matters)

flow_type	What it is	Sign	Counted as
Income	Payroll, tax credits, benefits	+	money in (earned)
Other In	Marketplace sales, deposit returns, paybacks that aren't income	+	money in (other)
Spending	A real purchase that reduces net worth	− (credits/refunds +)	spending, by category
Card Payment	Paying off a credit card from checking	−	money movement, NOT spending
Internal	Moving the user's own cash (to savings, to a brokerage; transfer in from savings)	− out / + in	money movement, NOT spending
Reimbursable	Money the user fronted for others and gets back — a wash	±	excluded from all totals
Expected	An IOU not yet received (a pending reimbursement, a repayment owed)	+	shown, NOT in totals

Why this matters: if a card payment or a savings transfer is mislabelled as Spending, the spending total inflates by thousands and the whole tracker lies. When in doubt about a transfer, ask whose account the money landed in — if it's still the user's, it's Internal, not spending.

Credits on a spending account (a refund, loyalty cashback) stay Spending with a positive amount — they correctly reduce that category's total.

Categorising spending

Use exactly the category strings from config.json (the Summary tab sums on them). Generalise to new merchants by what the purchase is, using the merchant_cues in config as hints, not a rigid lookup. If a purchase truly fits none, pick the closest and note it — don't invent a new category, or it won't roll up.

Edge cases worth handling

• Pending vs posted: include pending charges; put "Pending" in notes.
• Assumed amounts: if a recurring charge clearly will post but hasn't, you may estimate it and note "amount assumed".
• Split charges: if the user covered a group cost and others owe them, the gross is Spending and each repayment is Reimbursable (or net it and note the split).
• Brokerage / retirement contributions: Internal, negative (money leaving checking) — investing is not spending.
• An extra paycheque (some months have three biweekly pays): still Income.

Output format details

The exact sheet layout, formulas, fills, and number formats live in references/format-spec.md. You normally don't need to open it — the script encodes all of it — but read it if you need to change the template (add a category, a sheet, a flow type) or debug the output.