The Budget Hound
Last reviewed
IntermediateWhat you'll learn
~45 min- Import and normalize budget data from multiple project CSVs
- Calculate variances between budgeted, committed, and actual costs per equipment category
- Generate ASCII waterfall charts showing cost flow from budget to actuals
- Produce narrative budget health summaries with risk flags for financial reviews
What you’re building
It’s the last Thursday of the month. You know what that means. Finance pings you at 2:47 PM: “Can you send over the procurement budget status for all three projects by COB?” Sure. No problem. You’ll just open three different Excel files, manually compare budgeted amounts to committed POs to actual invoiced costs, figure out which line items are over budget, write up an explanation for each variance that doesn’t make you sound like you lost control of the money, and format it all into something your VP won’t immediately forward back with “can you add more detail?”
That used to eat your entire afternoon. Every month. Like clockwork, you’d lose two hours to a task that’s basically just math and storytelling — two things a computer should be doing for you.
Today it takes one command and 15 seconds.
Budget tracking is a lot like bourbon spending. You start with a plan (“I’m done buying for a while”). Then 203 drops Weller 12 with no call. Then someone texts you about an EHT SiB at 131. Then you’ve got 9 bottles in your trunk and you’re telling yourself “it’s an investment.” Paul has 400 bottles. Don’t be Paul. The Budget Hound is the tool that shows you exactly where the money went, why you’re over, and what you can tell your VP about it. No hiding, no spinning, just the numbers with a narrative that makes sense.
By the end of this lesson you’ll have a Node.js CLI tool that reads budget data from multiple project CSVs, does the variance math you’ve been half-assing in Excel for years, generates ASCII waterfall charts that actually make the money flow visible, and spits out a narrative budget health report you can hand directly to Finance with a straight face.
Budget CSV → normalization → variance calculation → waterfall visualization → narrative summary. This pattern works for any financial tracking: department budgets, project cost control, vendor spend analysis, personal finance. Anywhere you need to compare planned vs. actual spending and explain the gaps.
The showcase
Here’s what this thing does — think of it as the budget equivalent of those “before and after” home renovation photos, except the “before” is you squinting at three Excel tabs at 4:30 on a Thursday.
- Input: CSV per project with columns for equipment type, budgeted cost, committed (PO) cost, actual invoiced cost, and change orders. You know, all the numbers currently scattered across your inbox and SharePoint.
- Variance analysis: Budget vs. committed, committed vs. actual, total variance with percentage and direction. Three layers of “where the hell did the money go.”
- Waterfall chart: ASCII visualization showing how the budget flows from original amount through changes to final position. The chart your VP actually wants to see instead of page four of your spreadsheet.
- Health indicators: Green (under budget or within 5% over), Yellow (5-10% over budget), Red (>10% over budget). Instant triage so you know where to focus your energy and where to stop worrying.
- Narrative summary: Auto-generated explanation of major variances with context. Not “item is over budget.” More like “switchgear is $180K over budget due to copper price escalation” — the kind of sentence a human would actually write.
Before you start
If your agent is still open from the previous lesson, exit that session first (/exit or Ctrl+D). Create a clean folder for this lesson and open it:
mkdir -p ~/ofci-playbook/05-budget-hound && cd ~/ofci-playbook/05-budget-houndIn Windows PowerShell:
mkdir ~/ofci-playbook/05-budget-hound; cd ~/ofci-playbook/05-budget-houndOr open the folder directly in your desktop agent app. Start your agent the way Workbench Setup showed.
Switch to plan mode
Switch to Plan mode inside your session (Shift+Tab, /plan, or the mode picker) so the agent confirms your variance formulas and waterfall steps before writing code.
The conversation
Say what you want
Ask for the budget variance tool in plain English:
I track data center equipment budgets. Help me build a tool called budget-hound that calculates budget variances with change orders, draws ASCII waterfall charts, and writes narrative reports. Ask me what you need first.Answer its questions
Answer the agent’s questions with the domain rules for OFCI budget tracking:
| If it asks | You might say |
|---|---|
| How should line-item variances be calculated? | Compare committed vs budget, actual vs committed, and total variance including change orders against the original budget. |
| What are the budget health thresholds? | Green is under budget or within 5% over, yellow is 5-10% over, red is over 10%, configurable via —threshold. |
| What should the ASCII waterfall chart display? | Original budget, committed delta, change orders, actual vs committed delta, and current position, with increases red and decreases green. |
| Which projects and sample CSVs should it include? | Create sample CSVs in data/ for SV9, CH2, and DEN3 with 8 to 10 equipment lines each. |
| Which subcommands should the CLI support? | summary, variance, waterfall, and report, each supporting an optional —project filter. |
ℹReference notes to hand the agent (or check against)click to expand
Use these CSV columns across data/sv9-budget.csv, data/ch2-budget.csv, and data/den3-budget.csv:
equipment_id, project, equipment_type, description, vendor, budget_amount, committed_amount, actual_amount, change_orders, forecast_amount, notes
Illustrative sample prices for testing, not vendor quotes (replace them with your project’s quotes):
- Generators: $800K-$1.2M each
- Switchgear: $400K-$1.5M per lineup
- Chillers: $250K-$600K each
- CRAHs: $15K-$40K each (qty 20-40)
- UPS: $500K-$1M each
- PDUs: $3K-$8K each (qty 40-200)
Include a mix of under-budget, on-track, and over-budget items, with change orders on 2-3 items per project. For packages, use commander, csv-parse, cli-table3, and chalk@4 (chalk 5 and later are ES-module-only and break require()).
Read the plan
Before approving the plan, verify four details:
- Three-layer variance formulas: Line-item calculations include
budget_variance(committed_amount - budget_amount),actual_variance(actual_amount - committed_amount), andtotal_varianceincludingchange_ordersagainstbudget_amount. - Health thresholds: Items within
--threshold(default 5%) or under budget are green, 5-10% over are yellow, and>10%over are red. - Waterfall direction and colors: The ASCII waterfall traces Original Budget -> Committed vs Budget delta -> Change Orders -> Actual vs Committed delta -> Current Position, coloring cost increases red and savings green.
- Data-backed narrative: The narrative report cites specific dollar amounts, percentages, the top 3 variance drivers, change order impacts, and items over 10%.
If the plan ignores change orders in total variance or swaps the waterfall colors, correct it first:
Include change_orders in total_variance, and color cost increases red and cost decreases green on the waterfall chart.Approve the plan once all four checks pass, and ask the agent to save a Git checkpoint after the build succeeds.
What you get
Fire it up
Ask your agent to install what is needed, run the portfolio summary and SV9 waterfall chart, and generate the narrative report:
Install what the tool needs, run summary, variance, and waterfall for project SV9, and generate the full portfolio budget report.If you prefer running the commands in a terminal yourself:
cd budget-houndnpm installnode src/index.js summarynode src/index.js variance --project SV9node src/index.js waterfall --project SV9node src/index.js reportThe summary gives you the 30-second portfolio health check — the thing you glance at before you decide whether to panic. The variance command dives into individual line items so you can see exactly which piece of equipment is bleeding money and why. The waterfall is the one you’ll actually screenshot and paste into the email to your VP, because it tells the whole story in one visual. And report combines everything into a Markdown document that looks like you spent two hours on it instead of fifteen seconds.
If something is off
| Problem | Follow-up prompt |
|---|---|
| Variance percentages are NaN or Infinity | Some line items have $0 in budget_amount, causing division by zero. Show "N/A" for the variance percentage when budget_amount is 0 or missing, and make sure all dollar columns are read as numbers. |
| Waterfall chart bars go in wrong direction | The waterfall bars are showing increases as green and decreases as red, which is backwards for budget analysis -- being over budget should be red and under budget should be green, with bar widths proportional to dollar amounts. |
| All items show as “green” health | The health indicator isn't flagging overruns. Base health on total_variance including change orders: green if under budget or within --threshold (default 5%), yellow if 5-10% over, and red if over 10%. |
When Things Go Wrong
Use the Symptom → Evidence → Request pattern: describe what you see, paste the error, then ask for a fix.
How it works (the 2-minute explanation)
Here’s what’s happening under the hood, explained the way you’d explain it to a PM who keeps asking “but what does it actually do?”
- CSV loader reads your budget files, strips out the dollar signs and commas that make Excel feel so fancy, parses everything into actual numbers, and validates that nothing important is missing. It’s doing the tedious cleanup you usually do by hand when you copy-paste between workbooks.
- Variance engine does the math you’ve been doing on the back of your notepad during budget meetings. Three layers: what you said you’d spend vs. what you promised vendors you’d pay, what you promised vs. what you actually paid, and the real one — total variance including change orders. Because change orders are where budgets go to die, and any variance report that ignores them is lying to you.
- Waterfall chart traces the money visually so even someone who’s never opened a PO can follow it: you started here, commitments moved it this much, change orders moved it that much, actuals adjusted by this, and here’s where you stand. No more “can you walk me through this spreadsheet?” — the chart walks itself.
- Narrative generator turns the numbers into sentences a human would write. It identifies the three biggest variance drivers, flags anything over 10% that’ll make leadership nervous, and gives you a first draft that’s 80% done. You add your judgment and context, and now you’ve got a budget memo instead of a data dump.
Customize it
These are for when the basic tool is working and you want to push it further. Because once you see how fast this is, you’re going to want more.
Add trend tracking over time
Add a --snapshot flag that saves the current budget state to snapshots/YYYY-MM-DD.json, plus a trend subcommand that loads all snapshots and plots portfolio variance over time as an ASCII line chart.Add contingency tracker
Add support for a contingency_amount column in the CSV, track how much of each project's contingency is consumed by change orders and overages, and display remaining contingency percentage and projected depletion date.Key takeaways
- Three layers of variance tell three different stories — budget vs. committed vs. actual is not redundant. You might look great on commitments and be hemorrhaging money on actuals because of change orders nobody’s tracking. Any single comparison is a lie by omission.
- Waterfall charts are how you survive budget meetings — nobody wants to read your spreadsheet. Nobody. A waterfall shows “here’s where we started, here’s what moved, here’s where we are” and your VP actually understands it without asking you three clarifying questions.
- Auto-generated narratives give you your Friday afternoon back — the narrative doesn’t replace your brain, but it gives you a first draft that’s way better than staring at a blank email at 4 PM trying to explain why switchgear is $180K over. You edit and add context instead of starting from scratch.
- Portfolio-level views catch the patterns you’d miss project-by-project — if switchgear is over budget on two out of three builds, that’s not a project problem. That’s copper prices. That’s a market conversation with leadership, not a “what happened on SV9?” conversation. Big difference.
Your budget report shows SV9 chillers are 12% over budget: $600K budgeted, $672K committed (including a $48K change order for upgraded variable speed drives, and a $24K base price increase due to copper surcharges). The narrative flags this as 'red.' Your VP asks what to do. What's the best response?
What’s next
You’ve got the budget under control. You know where every dollar went and you can explain it without breaking a sweat. Great. But none of that matters if the $1.2M generator shows up at your site and there’s no crane, no rigging crew, and the GC poured concrete over your staging area.
Next up is The Delivery War Room — the tool that manages the logistics of actually getting all this equipment to your job sites without a catastrophe. Multi-project delivery calendars, conflict detection (two deliveries same day, one crane — do the math), delivery day checklists, and GC coordination. The budget data from this lesson feeds directly into delivery priority, because the equipment you’ve spent the most on gets the most attention on delivery day. You don’t wing it on a $1M generator arrival.