1
---
2
name: shared-expense-bill-splitter-and-settle-up-planner
3
description: Splits a CSV ledger of shared costs for a trip, flat or event - equal, shares, exact, percent and itemized bills with tax/tip pro rata, 'all except' exclusions, several payers, refunds, repayments and multiple currencies at agreed rates - in cents, then finds the provably fewest settle-up transfers (exact zero-sum subgroup search). Returns balances, a per-person audit and a chat message. Includes a stdlib Python planner with --self-test.
4
---
5
6
# Shared Expense Bill Splitter and Settle-Up Planner
7
8
You turn a messy list of shared spending into a fair, checkable split and the shortest possible list of payments. You keep the ledger as a CSV the group can edit in any spreadsheet, apply the split rule each line really needs (who was there, who ordered what, who stayed fewer nights), convert currencies at rates the group agrees on, and settle everyone with the fewest transfers. Every cent is accounted for, and anyone can trace their own number line by line.
9
10
## Files in this skill
11
12
- `scripts/settle_up.py` - reads the CSV ledger, splits each line in integer cents (largest-remainder rounding), computes paid/share/net per person, and searches all zero-sum subgroups to find the minimum number of transfers (exact up to 18 people with a balance, greedy beyond) (Python 3.8+ standard library only)
13
- `references/split-methods.md` - the CSV format, which split to use for which cost, itemized bills with tax and tip, exclusions, payers, refunds and repayments
14
- `references/settle-up-and-currency.md` - why the minimum can be below "people - 1", how the search works, rounding, exchange rates and card fees, payment etiquette
15
- `templates/settle-up-summary.md` - the summary to hand back and paste into the group chat
16
- `examples/lisbon-trip.csv` - 5 friends, 11 lines: shares by nights, an excluded person, an itemized dinner, a USD booking, premium seats, two payers, a refund, GBP snacks and a repayment already made
17
- `examples/lisbon-settle-output.md` - the real output of the planner on that ledger
18
- `examples/flat-october.csv` - 6 flatmates where the minimum (4 transfers) beats paying largest debt to largest credit (5)
19
20
## Workflow
21
22
### 1. Collect the ledger
23
Ask for every shared cost with: what, who paid (and how much each, if several people paid), the amount and currency, and who it was for. Ask the questions that change the split: Did anyone arrive late or leave early? Did anyone skip a meal or an activity? Was a dinner shared or ordered individually? Has anyone already paid someone back? Agree the base currency and the rates (one rate per currency for the whole trip unless the group wants card statement rates). Write it as the CSV in `references/split-methods.md`, with `# people:` so typos in names are caught.
24
25
### 2. Run the planner
26
```
27
python3 scripts/settle_up.py examples/lisbon-trip.csv
28
python3 scripts/settle_up.py flat.csv --base GBP --rates EUR=0.86 --detail Ben
29
python3 scripts/settle_up.py ledger.csv --json
30
python3 scripts/settle_up.py --self-test
31
```
32
Exit 0 = plan printed (read the Warnings section), 2 = the ledger has an error (sums that do not match, missing rate, unknown split or name) - fix the line it names. If you cannot run code, follow the same steps by hand: convert each line to base cents, split, sum paid minus share per person, then match debtors to creditors, looking first for people or small groups whose balances cancel exactly.
33
34
### 3. Check the result with the group
35
- The check line must read `nets add up to 0.00`; paid and shares must be equal.
36
- Read the balances aloud in plain words ("Ana paid 990.00, her share is 377.31 and Eli already gave her 100.00, so she gets back 512.69").
37
- Point out lines that drive the result and are easy to dispute (shares by nights, itemized meals, a refund, a repayment), and offer `--detail <name>` for anyone who wants their own breakdown.
38
- If someone prefers to pay someone else (or cannot pay a person directly), rerun after adding the agreed transfer as a `payment` line; the plan recomputes the rest.
39
40
### 4. Deliver
41
Fill `templates/settle-up-summary.md`: totals, the balances table, the numbered transfers, the assumptions (rates, who was excluded where, how tax/tip was spread), and the short group-chat message. Suggest marking each transfer as done by adding it to the ledger as a `payment` line, so a second run shows everyone at 0.00.
42
43
## Example result
44
On `examples/lisbon-trip.csv` (5 people, 1,583.07 EUR spent) Ana paid the apartment and the fado tickets and gets back 512.69 EUR; the plan is 4 transfers: Ben pays Ana 243.17, Dara pays Ana 140.94, Eli pays Ana 128.58 and Eli pays Cem 0.85 (Eli's earlier 100.00 repayment is already counted). On `examples/flat-october.csv` Bo and Finn cancel each other out, so 6 flatmates settle in 4 transfers where paying largest debt to largest credit would take 5.
45
46
## Rules
47
48
- Never invent amounts, rates or who took part; ask, or mark the line as an assumption in the summary.
49
- Use one agreed rate per currency and show it; do not mix live rates into a finished split.
50
- Keep all arithmetic in cents and show where rounding cents went (largest remainder, ties to the person listed first).
51
- Do not judge spending; flag only lines that look like duplicates, typos or missing participants.
52
- A repayment is a `payment` line, never a negative expense; a refund is a negative expense shared by the same people as the original cost.
53
- Present the plan as a proposal; the group can swap who pays whom as long as each person's net is unchanged.
54