debt_payoff_planning v1.0.0

name: "debt_payoff_planning" description: "Build a debt payoff plan that survives contact with a real budget: verify every balance, APR, and minimum from statements, run avalanche, snowball, and hybrid orders through a bundled calculator, pick the order with explicit decision rules, handle windfalls, transfers, and broken months, and keep the plan alive with a monthly check-in. Ships a tested payoff calculator (compare, plan, single-debt, and balance transfer checks), decision rules for triage and order choice, and worked plans at 2,850, 12,000, and 38,000 dollars of debt. Use when someone wants to pay off credit cards or multiple debts, asks whether snowball or avalanche is better, has a windfall to apply, is weighing a balance transfer or consolidation loan, or has a payoff plan that stalled."

Debt Payoff Planning

Purpose

A payoff plan is a verified list of debts, one fixed monthly budget, one order to attack them in, and a check-in rhythm that catches the plan when life knocks it sideways. This skill builds that plan with real math instead of method slogans.

Avalanche (highest APR first) costs the least interest. Snowball (smallest balance first) clears the first account sooner. Which one is right is a numbers question and a behavior question at the same time, so this skill computes both on the household's own debts and then chooses with stated rules. It covers unsecured and mixed household debt: cards, personal loans, medical bills, auto loans. It is general education, not personal financial advice, and it does not handle bankruptcy filings, tax disputes, or lawsuits. Those go to a licensed attorney or tax professional in the person's state.

Workflow

1. Build the register from statements, not memory.

• List every debt: creditor, balance, APR, minimum payment, due date. Pull each figure from a statement or the issuer's site dated within the last 30 days. Memory understates balances and forgets small debts, and a plan built on wrong inputs is wrong no matter how good the order is.
• Include debts people leave off on purpose: buy now pay later balances, medical bills on payment plans, money owed to family (listed with whatever terms were actually agreed), and anything in collections.
• Save the register as CSV in the format bin/payoff.py template prints, then run bin/payoff.py check debts.csv. Fix every error. Read every warning out loud in the plan: a minimum that does not cover the first month of interest means that balance grows at minimums only, and the issuer needs a call before anything else.

1. Triage before ordering.

• Pull out, in this order: past due debts, debts in collections or with court dates, secured debts tied to housing or transport to work, and debts owed to government or for support. Each gets its own next action in the plan. The payoff order only governs what is left. Full triage rules are in references/decision-rules.md.
• If total minimums alone are more than the household can pay, stop here. Skip to step 7, the cannot-pay branch. No order fixes a budget that does not cover minimums.

1. Set the monthly budget and the starter buffer.

• The budget is total minimums plus an extra the budget can actually carry every month, not in a good month. Find the extra from the spending record: subscriptions not used, category overruns, income that was going to savings past the buffer.
• Set a starter buffer before aggressive payoff: a cash amount, chosen by the household, that covers its most common shock (a car repair, a copay, a lost shift) so one bad week does not go straight back onto a card. State the amount and the reasoning. There is no universal right number, and any source that names one without asking about the household is selling something.
• Freeze new borrowing on the accounts in the plan. A plan that pays 600 dollars a month while 300 dollars of new charges land is a treadmill, and the register will show it at check-in.

1. Run the orders and pick one with the rules.

• Run bin/payoff.py compare debts.csv --extra <extra>. It prints months, total interest, and first clearance month for avalanche, snowball, hybrid, and minimums only.
• Apply the decision rules in references/decision-rules.md in order. Short version: avalanche if its first win lands within 3 months; the earlier first win if the interest gap is under 200 dollars; avalanche any single debt sitting 10 or more APR points above the rest with a large share of the balance; otherwise hybrid, which clears debts at or under 500 dollars first, then runs avalanche.
• Write down the chosen order as an actual list of debt names, with the modeled payoff month for each from bin/payoff.py plan debts.csv --extra <extra> --method <method>. A method name is not a plan. A dated list is.
• Ground the behavior side honestly: research on debt programs found that closing an account predicted finishing, whatever the size of the account closed (Gal and McShane, 2012, Journal of Marketing Research). Experiments also show people default to paying small debts first even when it costs them, and that watching interest pile up counters the pull (Amar and others, 2011, same journal). Present both findings at that strength. Neither one picks the order for a specific household. The calculator plus the rules do that.

1. Set the mechanics so the plan runs without willpower.

• Automate every minimum for one day after payday. Late fees and penalty APRs cost more than any order saves.
• Send the extra to the target debt as a separate, labelled payment. When a debt clears, move its full old payment to the next debt on the list within the same pay cycle. The roll is where the plan gains speed, and it only happens if the freed payment is redirected before it dissolves into spending.
• Apply windfalls by the rule in references/decision-rules.md: buffer first if it was spent, triage debts second, then the whole remainder onto the target debt. Never spread a windfall thinly across all debts.

1. Test transfers and consolidation with math, not offers.

• Balance transfer: run bin/payoff.py transfer --balance B --from-apr A --fee-percent F for the fee and rough break even, then run the plan both ways. The transfer must win on fee plus promo interest against the interest the current plan would pay over the same months, the balance must clear inside the promotion at the real budget, and the old card must stay at zero.
• Consolidation loan: it helps only when its rate beats the weighted average rate of the debts it replaces and its term is shorter than the current plan's payoff date. Compare total interest, never the monthly payment. A smaller payment over a longer term is usually a larger total cost wearing a friendlier face.
• Debt management plan through a nonprofit credit counseling agency: one payment to the agency, which pays enrolled creditors, usually in full, often at reduced rates or with fees waived, commonly over three to five years. This is the right referral when the household can pay but needs rate relief and structure more than it needs an order.
• Debt settlement is a different product, usually for-profit, and usually tells customers to stop paying creditors while saving for settlements. Interest and fees keep running, credit takes the hit, creditors can sue, and forgiven debt of 600 dollars or more is generally taxable income unless an exclusion applies. Say all of that before anyone signs. Under the FTC Telemarketing Sales Rule, a for-profit debt relief company selling by phone cannot collect any fee until it has actually renegotiated or settled a debt, the customer has agreed to the creditor's written terms, and the customer has made at least one payment under them. An upfront fee demand is a stop sign.

1. Use the cannot-pay branch when minimums do not fit.

• Call creditors before the first missed due date and ask about hardship programs, due date changes, and temporary rate cuts. Get any agreement in writing in the account messages.
• Refer to a nonprofit credit counseling agency for a budget review and a possible debt management plan. The first session is typically free or low cost, and a counselor will never tell the person to stop paying creditors.
• If the gap cannot close, say plainly that bankruptcy is a legal question for a licensed attorney in their state, and that federal law requires credit counseling before a filing anyway. Do not rank bankruptcy against payoff plans with the calculator.

1. Keep the plan alive with a check-in rhythm.

• Monthly, on a fixed day: update every balance in the register, confirm minimums are still set to autopay, confirm the extra went to the target, note any new charges, and record debts cleared to date against the modeled months. Twenty minutes is enough when the register exists.
• Quarterly: rerun compare on the current register. Rate changes, cleared debts, and income changes all move the right answer.
• Replan at once, not at the quarter, when: a payment is missed, income drops, a new debt appears, or an APR on a remaining debt moves 2 points or more. Broken month procedure is in references/decision-rules.md.

Output Contract

• Register table: every debt with balance, APR, minimum, and due date, each traced to a statement dated within 30 days, plus the check output from the calculator with warnings addressed.
• Budget line: total minimums, extra, total monthly budget, starter buffer amount with its reasoning, all as monthly dollar figures.
• Comparison table: months, total interest, and first clearance month for avalanche, snowball, hybrid, and minimums only, from the calculator on the real register. Never from memory or a generic example.
• The plan: chosen order as a dated list of debts with modeled payoff months, the decision rule that picked it, total interest, and the debt free month. Name the model limit in the plan itself: monthly interest model, good for comparing orders, not a statement prediction.
• Mechanics checklist: autopay status per debt, where the extra goes, what happens to each freed payment, and the windfall rule.
• Check-in block: monthly date, quarterly rerun date, and the four replan triggers.
• Caveat line, always: this is general education, not personal financial advice. A fiduciary advisor, nonprofit credit counselor, or attorney can advise on the specific household.

Operating Rules

1. Never invent a balance, rate, statistic, or payoff date. Every dollar figure in a plan comes from a statement the user supplied or from the bundled calculator run on stated inputs. Worked examples live in references/worked-plans.md and are labelled with their inputs so anyone can reproduce them.
2. Present the two research findings at their real strength. Closing accounts predicted finishing a program; it did not prove snowball beats avalanche for a given household. Do not upgrade either finding into a promise.
3. Minimums on every debt, every month, is a hard floor inside any order, except inside a written hardship or counseling arrangement the user chose with the risks stated. Never advise stopping payments to creditors as a tactic without the full settlement risk list from step 6.
4. Compare transfers and consolidation loans on total cost over the months the balance will actually survive. Never on monthly payment, never on the advertised rate alone, and never without the fee.
5. Do not promise credit score changes from any payoff order. Paying on time and shrinking balances are the controllable parts. Score outcomes depend on the whole credit file.
6. Keep the register private. It contains account level financial detail. Store it only where the user keeps financial records, and never post it, share it, or paste it into a public surface.
7. Watch the language. No shame framing, no "bad debt" moralizing at the person, no countdown pressure. The plan is a tool. People keep tools that respect them.

Tooling

• bin/payoff.py, run with python3. Monthly interest model: interest is balance times APR divided by 12. Real issuers charge daily on the average daily balance (daily rate is APR divided by 365), so use the tool to compare orders and estimate dates, not to predict a statement.
• template prints the register CSV header and example rows.
• check debts.csv validates the register and warns when a minimum does not cover the first month of interest.
• compare debts.csv --extra N prints months, interest, and first clearance for avalanche, snowball, hybrid, and minimums only.
• plan debts.csv --extra N --method M prints the full plan for one order, with --schedule adding a month by month CSV. Hybrid uses --hybrid-threshold D (default 500 dollars).
• single --balance B --apr A --payment P gives months and total interest for one debt at a fixed payment, and flags a payment that never clears the balance.
• transfer --balance B --from-apr A --fee-percent F [--to-apr P] gives the transfer fee and the rough break even against the rate gap.