Budget Wizard

Triggered when user wants to create, build, plan, or review a budget. Matches: "create a budget", "help me with a budget", "build a budget", "monthly budget", "project budget", "department budget", "event budget", "financial plan", "expense tracker", "budget spreadsheet", "budget template", "how much am I spending", "plan my expenses", "cost breakdown", "budget dashboard", "financial dashboard", "interactive budget", "visualize my budget". Also trigger for any request involving spreadsheets with financial calculations, revenue projections, or cost-benefit analysis. Do NOT use for analyzing past expense data without creating a new budget (use report-writer), creating budget slides for a presentation (use presentation skill — budget-wizard can supply the numbers but slide layout belongs there), writing a cost-benefit analysis document (use report-writer), or tracking time or creating timesheets (not a budget task).

Step 3: Currency

Check Personal Preferences for currency. If not set:

AskUserQuestion: "What currency?"
Options: ["ILS (₪)", "USD ($)", "EUR (€)", "Custom"]

Step 4: Categories

Present pre-populated categories based on budget type. User can add, remove, or modify.

Personal / Household:

• Income: Salary, Freelance, Investments, Other
• Housing: Rent/Mortgage, Utilities, Insurance, Maintenance
• Transportation: Car payment, Fuel, Public transit, Parking
• Food: Groceries, Dining out, Delivery
• Health: Insurance, Medical, Fitness
• Personal: Clothing, Entertainment, Subscriptions
• Savings: Emergency fund, Retirement, Goals
• Other: Gifts, Education, Miscellaneous

Project:

• Personnel: Team salaries, Contractors, Freelancers
• Technology: Software licenses, Infrastructure, Tools
• Marketing: Advertising, Content, Events
• Operations: Office, Travel, Equipment
• Contingency: Buffer (typically 10-15%)

Event:

• Venue: Space rental, Setup, Cleanup
• Catering: Food, Beverages, Service staff
• Marketing: Invitations, Promotion, Signage
• Entertainment: Speakers, Performers, AV equipment
• Logistics: Transportation, Accommodation, Insurance
• Contingency: Unexpected costs

Department / Team:

• Salaries: Base, Bonuses, Benefits
• Operations: Office supplies, Software, Equipment
• Travel: Flights, Hotels, Meals
• Training: Courses, Conferences, Books
• Marketing: Campaigns, Tools, Events
• Miscellaneous: Contingency, Buffer

AskUserQuestion: "Here are the suggested categories for a [type] budget. What would you like to do?"
Options: ["Use these categories", "Add more categories", "Remove some categories", "Start from scratch"]

Step 5: Enter Amounts

For each category, ask for the budgeted amount. Group related items:

AskUserQuestion: "Let's fill in the amounts. Which section should we start with?"
Options: ["[Category 1]", "[Category 2]", "[Category 3]", "Enter all at once — I'll list them"]

For each category, ask for subcategory amounts. Calculate subtotals automatically.

Step 6: Review and Generate

Present the complete budget using template.md format:

• All categories with amounts
• Subtotals per category
• Percentage of total for each line item
• Grand total
• Surplus/Deficit (for Personal: Income - Expenses; for Project/Event: Budget - Estimated Cost)

AskUserQuestion: "Here's your budget summary. What would you like to do?"
Options: ["Looks good — generate final version", "Adjust amounts", "Add a category", "Remove a category", "Start over"]

Step 7: Output

Generate two outputs:

1. Markdown table — Clean, readable budget for preview and documentation
2. CSV format — Ready to paste into Excel or Google Sheets

AskUserQuestion: "Budget is ready! How would you like the output?"
Options: [
  "Show both markdown and CSV",
  "Save as file to ~/Tandem/documents/",
  "Just show the markdown preview",
  "Just the CSV for spreadsheet import",
  "Interactive HTML dashboard (open in browser)"
]

If saving as file, use naming convention: budget-[type]-[YYYY-MM].md and budget-[type]-[YYYY-MM].csv

Calculations

For every budget, automatically compute:

• Subtotals per category (sum of subcategories)
• Grand total (sum of all categories)
• % of total for each line item (amount / grand total * 100)
• Surplus/Deficit (income - expenses, or budget - cost)
• Round percentages to 1 decimal place
• Format currency with thousands separator appropriate to locale

See references/formula-guide.md for Excel formulas to include in CSV output.

Interactive HTML Dashboard Mode

When HTML dashboard output is selected, generate a single self-contained HTML file with an Apple Swiss design aesthetic — interactive sliders, charts, and projections.

Required Features

1. Top stat cards (4 across): Income, Expenses, Savings, Savings Rate — each with icon, value, and subtitle
2. Slider panel: Sliders for income and each expense category. All sliders fire update() on input for real-time updates
3. Donut chart: Expense breakdown + savings as largest slice. Center text shows savings rate %. Uses Chart.js doughnut
4. Legend: Color-coded list with category names, amounts, and percentages
5. 12-month projection chart: Line chart with 3 scenario toggle buttons:
   • "Just Saving" (0% return)
   • "High-Yield Savings" (4.5% APY)
   • "Invested" (7% annual return)
6. Milestones: Progress bars toward financial goals (Emergency Fund 3mo/6mo, custom targets). Each shows ETA
7. Benchmark comparisons: User's spending vs standard guidelines (50/30/20 rule). Visual bar with guideline marker
8. Insight box: Dynamic text that changes based on savings rate (<20%, 20-50%, 50%+, negative)

Design System (Apple Swiss)

Technical Requirements

• Single self-contained HTML file with inline CSS and JS
• Chart.js 4.4.1 from CDN: https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.min.js
• Google Fonts (Instrument Sans + Newsreader) with system font fallback
• All sliders update all charts, stats, and projections in real-time
• Responsive layout (works on tablet and desktop)
• No dark mode — keep it light and clean

Math Verification Checklist

Before delivering the dashboard:

• Income - expenses = savings (always)
• Donut chart percentages total 100%
• Projection chart uses correct compound interest: balance * (1 + rate/12) per month
• Milestone ETAs calculated correctly from monthly savings
• All sliders update everything in real-time

HTML File Output

Save as budget-dashboard-[type]-[YYYY-MM].html in ~/Tandem/documents/.

Include a small footer disclaimer: "This is a planning tool, not financial advice."

Rules

• Never give specific investment advice
• Double-check all math — budget totals must add up
• Handle financial details with care — do not store in memory
• Round to whole dollars/currency units

Proactivity — Next Steps

After budget creation, suggest 1-2 of these:

• "Want me to save this budget and set a monthly review reminder?"
• "Should I create a comparison template to track actual vs. budgeted spending?"
• "Want me to remember your budget categories for next time?"
• "Need help creating a presentation of this budget for stakeholders?"

Memory

Memory is user-triggered only. Offer to remember:

• Preferred budget categories and typical amounts
• Currency and locale preferences
• Budget review schedule

Output Format

Follow template.md for markdown format. See examples/personal-budget.md and examples/project-budget.md for complete examples. See references/formula-guide.md for Excel formula reference. For HTML dashboard mode, see the Interactive HTML Dashboard Mode section above.

Hebrew RTL Note

When outputting in Hebrew:

• Currency symbol (₪) appears after the number in Hebrew convention
• Table headers in Hebrew
• Right-to-left table alignment

Error Handling

• User unsure about amounts: "No worries — we can use estimates now and refine later. What's your rough estimate for [category]?"
• Negative surplus: Flag clearly: "Note: This budget shows a deficit of [amount]. You may want to adjust expenses or increase income to balance it."
• Missing categories: "Your [type] budget typically includes [missing category]. Want to add it?"

Activity Logging

After completing the workflow, append an entry to ~/Tandem/stats.json:

{
  "type": "document",
  "action": "created",
  "count": 1,
  "timeSavedMinutes": 30,
  "description": "Created budget: Q2 Marketing Budget",
  "timestamp": "<current ISO 8601>",
  "file": {
    "name": "Q2-Budget.csv",
    "path": "~/Tandem/documents/Q2-Budget.csv"
  }
}

Include a file object with the name and full path of the created budget/spreadsheet.

If ~/Tandem/stats.json does not exist, create it as [<entry>]. If it exists, read it, parse the JSON array, append the new entry, and write it back.

Dashboard Sync

After appending to stats.json, follow the /sync workflow from tandem-skills/core/sync/SKILL.md to rebuild ~/Tandem/dashboard.html with updated statistics. This keeps the dashboard current after every skill run. If /sync fails (e.g., dashboard.html does not exist yet), continue — the main skill workflow must complete successfully regardless of sync outcome.