budgeting

Category: Data & AI | Uploader: hvkshetry | Downloads: 0 | Version: v1.0（Latest）

Personal budgeting and financial planning skill. Use when: (1) Analyzing spending patterns by category or time period, (2) Comparing budget vs actual spending, (3) Calculating savings rates, (4) Forecasting cash flow, (5) Planning tax-aware financial decisions. Tools: actual-mcp for budget/transaction data, ghostfolio-mcp for investment portfolio context. --- # Personal Budgeting ## Tool Mapping | Task | MCP Server | Key Tools | |------|-----------|-----------| | Transaction history, balances, budgets | actual-mcp | `get_transactions`, `get_accounts`, `get_budget_months` | | Category breakdowns | actual-mcp | `get_categories`, `get_category_groups` | | Investment balances and allocation | ghostfolio-mcp | `get_portfolio_summary`, `get_portfolio_positions` | | Net worth calculation | Both | Actual (cash/debt) + Ghostfolio (investments) | ## Spending Analysis ### Category Breakdown 1. Pull transactions for the target period using `get_transactions` with date range filters 2. Group by category — report both absolute amounts and percentage of total spend 3. Flag categories that exceed their budget allocation 4. Present results as a ranked table: Category | Budgeted | Actual | Variance | % of Total ### Month-over-Month Trends 1. Pull 3-6 months of transaction data 2. Compute per-category monthly totals 3. Calculate month-over-month change (absolute and percentage) 4. Flag categories with sustained increases (3+ consecutive months of growth) 5. Distinguish between recurring/fixed expenses (rent, insurance, subscriptions) and variable expenses (groceries, dining, entertainment) ### Anomaly Detection - Flag individual transactions > 2x the category's average transaction size - Flag categories where current month spend exceeds the trailing 3-month average by > 25% - Flag new payees not seen in prior months (potential new subscriptions) ## Budget vs Actual Variance Analysis ### Monthly Variance Report 1. Pull budget allocations via `get_budget_months` for the target month 2.

Changelog: Source: GitHub https://github.com/hvkshetry/StewardOS

Directory Structure

Current level: skills/budgeting/

📄 SKILL.md 7.8 KB

SKILL.md

---
name: budgeting
description: |
  Personal budgeting and financial planning skill. Use when: (1) Analyzing spending patterns
  by category or time period, (2) Comparing budget vs actual spending, (3) Calculating savings
  rates, (4) Forecasting cash flow, (5) Planning tax-aware financial decisions. Tools: actual-mcp
  for budget/transaction data, ghostfolio-mcp for investment portfolio context.
---

# Personal Budgeting

## Tool Mapping

| Task | MCP Server | Key Tools |
|------|-----------|-----------|
| Transaction history, balances, budgets | actual-mcp | `get_transactions`, `get_accounts`, `get_budget_months` |
| Category breakdowns | actual-mcp | `get_categories`, `get_category_groups` |
| Investment balances and allocation | ghostfolio-mcp | `get_portfolio_summary`, `get_portfolio_positions` |
| Net worth calculation | Both | Actual (cash/debt) + Ghostfolio (investments) |

## Spending Analysis

### Category Breakdown

1. Pull transactions for the target period using `get_transactions` with date range filters
2. Group by category — report both absolute amounts and percentage of total spend
3. Flag categories that exceed their budget allocation
4. Present results as a ranked table: Category | Budgeted | Actual | Variance | % of Total

### Month-over-Month Trends

1. Pull 3-6 months of transaction data
2. Compute per-category monthly totals
3. Calculate month-over-month change (absolute and percentage)
4. Flag categories with sustained increases (3+ consecutive months of growth)
5. Distinguish between recurring/fixed expenses (rent, insurance, subscriptions) and variable expenses (groceries, dining, entertainment)

### Anomaly Detection

- Flag individual transactions > 2x the category's average transaction size
- Flag categories where current month spend exceeds the trailing 3-month average by > 25%
- Flag new payees not seen in prior months (potential new subscriptions)

## Budget vs Actual Variance Analysis

### Monthly Variance Report

1. Pull budget allocations via `get_budget_months` for the target month
2. Pull actual spend by category for the same period
3. Compute variance: `actual - budgeted` (negative = under budget, positive = over budget)
4. Present as table: Category | Budget | Actual | Variance | Status (Over/Under/On Track)

### Status Thresholds

| Status | Condition |
|--------|-----------|
| On Track | Actual within +/- 5% of budget |
| Under Budget | Actual < 95% of budget |
| Over Budget | Actual > 105% of budget |
| Critical | Actual > 120% of budget |

### Year-to-Date Tracking

- Accumulate monthly variances to show YTD position per category
- Some categories (e.g., auto maintenance, medical) are lumpy — flag these and compare YTD to annual budget rather than monthly

## Savings Rate Calculation

### Formula

```
Gross Savings Rate = (Total Income - Total Expenses) / Total Income
Net Savings Rate   = (Total Income - Total Expenses - Taxes) / (Total Income - Taxes)
```

### Procedure

1. Pull all income transactions (identify income categories/accounts in Actual)
2. Pull all expense transactions
3. Exclude internal transfers (account-to-account moves) — these are not income or expenses
4. Calculate both gross and net rates
5. Track monthly trend and rolling 3-month average

### Investment Contribution Context

- Use ghostfolio-mcp to pull recent contributions to investment accounts
- Include these in the savings rate numerator if they are not already captured as "transfers" in Actual
- Report: Savings Rate (cash) vs Savings Rate (including investments)

## Cash Flow Forecasting

### Short-Term (Next 30-60 Days)

1. Start with current account balances from `get_accounts`
2. Identify recurring income (salary dates, rental income, dividends)
3. Identify recurring expenses (rent/mortgage, subscriptions, loan payments, insurance)
4. Subtract known upcoming one-time expenses (if any flagged by user)
5. Project daily balance and flag dates where balance drops below a user-defined threshold

### Procedure

1. Analyze 3-6 months of transaction history to identify recurring patterns
2. Categorize each recurring item: weekly, biweekly, monthly, quarterly, annual
3. Build a forward calendar of expected inflows and outflows
4. Present as a week-by-week projection table: Week | Expected In | Expected Out | Projected Balance

### Seasonal Adjustments

- Flag categories with known seasonal variation (utilities, holiday spending, insurance renewals)
- Use same-month-prior-year data when available for seasonal categories

## Tax-Aware Financial Planning

### Tax-Relevant Transaction Tagging

Ensure these categories are properly tracked in Actual for tax time:
- Business expenses (Schedule C — use `categorize_schedule_c_deductions` from household-tax-mcp)
- Health insurance premiums (self-employed deduction)
- Retirement contributions (SEP-IRA, Solo 401(k))
- Charitable donations (Schedule A itemized deductions)
- Home office expenses (simplified or actual method)
- Professional development and education
- Travel and business meals (50% deductible)

### Quarterly Estimated Tax Payments (1040-ES)

1. Pull YTD income from Actual (self-employment, W-2, investment income)
2. Pull capital gains/dividends from ghostfolio-mcp
3. Normalize facts to the reduced exact `household-tax` contract
4. Use `assess_exact_support` before any tax recommendation
5. If supported, use `compute_individual_return_exact`, `compare_individual_payment_strategies`, and `plan_individual_safe_harbor`
6. If unsupported, stop and report the gap rather than approximating

**Due dates:** Q1 Apr 15, Q2 Jun 15, Q3 Sep 15, Q4 Jan 15 (next year)

### Self-Employment Tax (Schedule SE)

Self-employment income is outside the reduced exact household-tax scope. For these cases:
- Social Security tax (12.4% up to wage base)
- Medicare tax (2.9% + 0.9% additional above $200k)
- Deductible half of SE tax (reduces AGI)
- do not use `household-tax` as an exact calculator; surface the unsupported scope explicitly

### Schedule C Deduction Categorization

Use `categorize_schedule_c_deductions` to map Actual Budget expense categories to Schedule C lines. Review unmapped categories quarterly to ensure all deductions are captured.

### Exact Tax Support

`household-tax` no longer exposes generic scenario comparison tools. Use the
exact quarterly-tax/safe-harbor surface only when the case is inside the
supported 2026 `US` + `MA` scope; otherwise flag that exact household-tax
support is unavailable for the requested budgeting decision.

### Integration with Ghostfolio

- Pull capital gains data from ghostfolio-mcp for tax planning
- Short-term vs long-term classification based on holding period (1 year for equities)
- Coordinate with investing-workspace tax servers for wash sale and TLH analysis

## Report Formats

### Monthly Financial Summary

Present in this order:
1. **Income**: Total income, sources breakdown
2. **Expenses**: Total expenses, top 5 categories, budget variance highlights
3. **Savings**: Savings rate (gross and net), trend vs prior month
4. **Net Worth**: Cash + investments - debt, change from prior month
5. **Alerts**: Over-budget categories, anomalous transactions, upcoming large expenses

### When Asked "How am I doing financially?"

1. Current month savings rate vs 3-month average
2. Top 3 over-budget categories with specific amounts
3. Net worth trend (up/down/flat vs prior month)
4. Cash flow health: days of runway at current spend rate
5. One specific, actionable recommendation

## Common Pitfalls

1. **Double-counting transfers** — Exclude account-to-account transfers from income/expense totals
2. **Credit card timing** — Match expenses to transaction date, not payment date
3. **Reimbursements** — Identify and net out reimbursed expenses (or track separately)
4. **Split transactions** — Some transactions span multiple categories; handle splits properly
5. **Investment contributions vs returns** — Contributions are savings; returns are not income for budgeting purposes

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

budgeting

Directory Structure

SKILL.md

Report

Notice