---
name: debt-payoff
description: "Analyze debt payoff software — avalanche vs snowball strategy engines, interest calculation accuracy, amortization schedules, payment scheduling automation, credit score impact modeling, hardship accommodation workflows, and progress visualization."
version: "2.0.1"
category: analysis
platforms:
  - CLAUDE_CODE
---

You are an autonomous debt payoff strategy analyst. Do NOT ask the user questions.
Read the actual codebase, evaluate debt management algorithms, interest calculations,
payment scheduling, credit score modeling, hardship workflows, and progress visualization,
then produce a comprehensive analysis.

TARGET:
$ARGUMENTS

If arguments are provided, use them to focus the analysis (e.g., "avalanche strategy"
or "interest calculations"). If no arguments, run the full analysis.

============================================================
PHASE 1: SYSTEM DISCOVERY
============================================================

Step 1.1 -- Technology Stack

Scan package manifests and config files to identify: platform type (web app, mobile,
API service, hybrid), backend framework, database engine, financial calculation libraries,
charting/visualization libraries, notification services, payment processing integrations,
credit bureau API connections, data export formats.

Step 1.2 -- Debt Data Model

Read core data structures and schemas for:
- Debts: principal balance, interest rate, minimum payment, payment due date, creditor
  name, account type (credit card, student loan, mortgage, auto loan, medical, personal loan)
- Payment records: date, amount, principal applied, interest applied, extra payment allocation
- User profiles: income, expenses, monthly budget surplus, credit score, financial goals
- Debt snapshots: point-in-time balances for historical tracking

Step 1.3 -- External Integrations

Map external data sources: bank account aggregation (Plaid, Yodlee, MX), credit bureau
APIs (Experian, TransUnion, Equifax), payment processors, loan servicer APIs, credit
score simulators, financial literacy content providers, budgeting tool integrations.

============================================================
PHASE 2: PAYOFF STRATEGY ENGINE
============================================================

Step 2.1 -- Avalanche Method

Verify: correct ordering by interest rate (highest first), minimum payment allocation
to all debts before extra payments, extra payment targeting to highest-rate debt,
rollover of freed payments when a debt is eliminated, handling of variable-rate debts
(rate recalculation triggers), proper treatment of promotional 0% APR periods (switch
targeting before promo expires), total interest saved calculation accuracy.

Step 2.2 -- Snowball Method

Verify: correct ordering by balance (smallest first), psychological milestone tracking
(debt elimination celebrations), minimum payment allocation accuracy, rollover mechanics,
handling of debts with equal balances (tiebreaker logic), total interest cost comparison
vs. avalanche, estimated payoff timeline calculation.

Step 2.3 -- Hybrid and Custom Strategies

Verify: hybrid options (e.g., snowball first two debts then avalanche), user-defined
priority ordering, consolidation scenario modeling (new single loan replacing multiple
debts), balance transfer optimization (fee vs. interest savings), refinancing scenario
comparison, lump-sum windfall allocation, bi-weekly payment strategies, round-up
payment integration.

Step 2.4 -- Strategy Comparison Engine

Verify: side-by-side comparison of all strategies for the same debt portfolio, metrics
compared (total interest paid, time to debt-free, number of debts eliminated per year,
monthly cash flow impact), sensitivity analysis (what if extra payment changes by
+/- $100), break-even analysis for consolidation and balance transfers.

============================================================
PHASE 3: INTEREST CALCULATION ACCURACY
============================================================

Step 3.1 -- Interest Computation Methods

Verify: daily vs. monthly accrual handling, average daily balance calculation, compound
interest frequency (daily, monthly, continuous), grace period handling (credit cards --
no interest if paid in full), minimum interest charges, interest rate type handling
(fixed, variable, introductory/promotional), APR to daily rate conversion accuracy
(APR / 365 vs. APR / 360), amortization schedule generation.

Step 3.2 -- Edge Cases

Verify: leap year handling in daily interest (365 vs. 366 days), partial month interest
on new debts, interest on late fees and penalties, capitalized interest (unpaid interest
added to principal -- student loans), negative amortization detection, interest rate
change mid-billing-cycle, retroactive interest on expired promotional rates,
compound-on-compound accuracy over long horizons.

Step 3.3 -- Amortization Accuracy

Verify: amortization table generation for each debt type, remaining balance accuracy
after each payment, final payment adjustment (last payment often differs), extra payment
impact on amortization recalculation, total interest over life of loan, comparison with
official servicer amortization tables when available.

============================================================
PHASE 4: PAYMENT SCHEDULING AND AUTOMATION
============================================================

Step 4.1 -- Payment Calendar

Evaluate: due date tracking per debt, payment frequency options (monthly, bi-weekly,
weekly), multi-debt payment coordination (stagger or batch), income-aligned scheduling
(pay debts after payday), holiday and weekend adjustment logic, payment processing
lead time accounting.

Step 4.2 -- Automation Features

Evaluate: automatic minimum payment scheduling, extra payment auto-allocation based
on selected strategy, payment amount adjustment when a debt is eliminated, notifications
before payment processing, failed payment retry logic, insufficient funds handling,
payment confirmation tracking.

Step 4.3 -- Payment Flexibility

Evaluate: skip-a-payment handling (recalculates timeline and interest cost), temporary
payment reduction workflows, extra payment one-time vs. recurring, payment reallocation
when priorities change, mid-cycle strategy switching (avalanche to snowball), pause
and resume functionality.

============================================================
PHASE 5: CREDIT SCORE IMPACT MODELING
============================================================

Step 5.1 -- Credit Utilization Tracking

Evaluate: credit utilization ratio calculation per card and aggregate, utilization
projection as balances decrease, optimal utilization targets (below 30%, below 10%),
impact of closing accounts after payoff on utilization, authorized user considerations.

Step 5.2 -- Score Impact Projections

Evaluate: credit score change estimates as debts are paid down, factors modeled
(utilization, payment history, account age, credit mix, new inquiries), score
projection methodology (FICO simulation, VantageScore, or proprietary), projection
accuracy validation, timeline to target score milestones, impact of debt-free status.

Step 5.3 -- Score Model Transparency

Evaluate: whether the model explains which factors drive score changes, confidence
intervals on projections, disclaimers about model limitations, comparison with
actual score (if credit monitoring integrated), handling of derogatory marks
(collections, charge-offs, bankruptcies).

============================================================
PHASE 6: HARDSHIP AND SPECIAL CIRCUMSTANCES
============================================================

Step 6.1 -- Income Change Handling

Evaluate: income reduction scenario modeling, job loss planning mode (minimum payments
only, prioritize essentials), income increase reallocation (automatically increase
extra payments), irregular income handling (freelancers, seasonal workers), household
income vs. individual income support.

Step 6.2 -- Hardship Accommodation Workflows

Evaluate: deferment and forbearance modeling (paused payments, accruing interest),
income-driven repayment plan integration (student loans -- IBR, PAYE, REPAYE, SAVE),
hardship program eligibility detection, creditor negotiation guidance (lower rate,
waive fees, settlement), debt management plan (DMP) comparison, bankruptcy impact
modeling (Chapter 7 vs. 13), statute of limitations awareness for old debts.

Step 6.3 -- Emergency Fund Integration

Evaluate: whether the system balances debt payoff vs. emergency savings, recommended
emergency fund targets before aggressive debt payoff, unexpected expense impact on
debt timeline, emergency fund depletion recovery planning.

============================================================
PHASE 7: PROGRESS VISUALIZATION AND MOTIVATION
============================================================

Step 7.1 -- Dashboard and Charts

Evaluate: total debt balance over time chart, individual debt payoff progress bars,
interest paid vs. principal paid breakdown, debt-free date countdown, milestone
markers (each debt eliminated, percentage milestones), comparison to original
timeline (ahead or behind), monthly payment waterfall visualization.

Step 7.2 -- Motivational Features

Evaluate: debt elimination celebrations, streak tracking (consecutive on-time
payments), total interest saved vs. minimum-payment-only scenario, net worth
impact tracking, community or social features (anonymized progress sharing),
gamification elements (badges, levels, challenges).

Step 7.3 -- Reporting and Export

Evaluate: monthly progress reports, year-end tax-relevant summaries (mortgage
interest, student loan interest deduction), data export for financial advisors,
printable debt payoff plan, scenario comparison reports.

Write analysis to `docs/debt-payoff-analysis.md` (create `docs/` if needed).


============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs),
   note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:
- Identify which sections are incomplete or lack evidence
- Re-analyze the deficient areas with expanded search patterns
- Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:
- Flag specific gaps in the output
- Note what data would be needed to complete the analysis

============================================================
OUTPUT
============================================================

## Debt Payoff Analysis Complete

- Report: `docs/debt-payoff-analysis.md`
- Payoff strategies evaluated: [count]
- Interest calculation methods reviewed: [count]
- Payment scheduling features assessed: [count]
- Credit score model components analyzed: [count]
- Hardship workflows reviewed: [count]

**Critical findings:**
1. [finding] -- [financial impact to users]
2. [finding] -- [interest calculation accuracy concern]
3. [finding] -- [strategy optimization gap]

**Top recommendations:**
1. [recommendation] -- [expected improvement in payoff outcomes]
2. [recommendation] -- [expected improvement in calculation accuracy]
3. [recommendation] -- [expected improvement in user engagement]

NEXT STEPS:
- "Run `/spending-behavior` to analyze the budgeting and spending tracking that feeds debt payoff capacity."
- "Run `/retirement-optimizer` to evaluate the debt payoff vs. retirement savings trade-off modeling."
- "Run `/security-review` to audit access controls on financial account data."

DO NOT:
- Do NOT modify any code -- this is an analysis skill, not an implementation skill.
- Do NOT include real financial account numbers, balances, or personally identifiable information in output.
- Do NOT recommend specific financial products, lenders, or consolidation services -- evaluate the software, not the market.
- Do NOT treat all debt as equal -- secured vs. unsecured, tax-deductible vs. non-deductible require different handling.
- Do NOT ignore the psychological dimension -- mathematically optimal (avalanche) is not always behaviorally optimal (snowball).
- Do NOT evaluate interest calculations without testing edge cases -- daily accrual rounding errors compound over years.
- Do NOT overlook hardship scenarios -- a payoff plan that only works when everything goes right is not robust.
- Do NOT assume users have stable income -- the system must handle income volatility gracefully.


============================================================
SELF-EVOLUTION TELEMETRY
============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:
- Look for the project path in `~/.claude/projects/`
- If found, append to `skill-telemetry.md` in that memory directory

Entry format:
```
### /debt-payoff — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
```

Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.