Applied The OFCI Playbook

The Budget Hound

Last reviewed

Intermediate

What 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.

💬Hunting the budget like hunting bourbon

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.

ℹSoftware pattern: Financial data pipeline with variance analysis

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:

Terminal window
mkdir -p ~/ofci-playbook/05-budget-hound && cd ~/ofci-playbook/05-budget-hound

In Windows PowerShell:

Terminal window
mkdir ~/ofci-playbook/05-budget-hound; cd ~/ofci-playbook/05-budget-hound

Or 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 asksYou 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:

  1. Three-layer variance formulas: Line-item calculations include budget_variance (committed_amount - budget_amount), actual_variance (actual_amount - committed_amount), and total_variance including change_orders against budget_amount.
  2. Health thresholds: Items within --threshold (default 5%) or under budget are green, 5-10% over are yellow, and >10% over are red.
  3. 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.
  4. 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:

Terminal window
cd budget-hound
npm install
node src/index.js summary
node src/index.js variance --project SV9
node src/index.js waterfall --project SV9
node src/index.js report

The 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

ProblemFollow-up prompt
Variance percentages are NaN or InfinitySome 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 directionThe 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” healthThe 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.

Symptom
Change orders aren't factored into the total variance
Evidence
An item with a $500K budget, $500K committed, $0 actual, but $50K in change orders shows as 0% variance instead of 10% over
What to ask the AI
"The total variance calculation needs to include change orders. The formula should be: total_variance = (committed_amount + change_orders) - budget_amount when actual_amount is 0 or null, or (actual_amount + change_orders) - budget_amount when actuals exist. Change orders are always additive to the current cost position."
Symptom
Portfolio summary doesn't match the sum of individual projects
Evidence
SV9 shows $12.1M total, CH2 shows $8.7M, DEN3 shows $10.4M, but the portfolio summary shows $28.5M instead of $31.2M
What to ask the AI
"The portfolio aggregation is dropping some line items during the sum. Make sure the CSV reader loads ALL rows from ALL project CSVs and that the variance engine sums every line item. Check for rows being silently dropped due to parsing errors (empty lines, header rows, missing fields). Add a count validation: total items = sum of items per project."
Symptom
The narrative is generic and doesn't reference actual data
Evidence
The budget health summary says 'The project is within budget' without mentioning specific dollar amounts, percentages, or equipment items
What to ask the AI
"The narrative generator needs to reference the actual calculated data. It should name the top 3 variance drivers by equipment type and dollar amount, state the exact portfolio and project-level percentages, and reference specific change orders. Template: '[Project] procurement is [X]% [over/under] budget at $[committed] against $[budget] original budget. The largest variance driver is [equipment] at $[amount] ([pct]%) [over/under], primarily due to [change_order_notes or vendor notes].'"

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?”

  1. 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.
  2. 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.
  3. 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.
  4. 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.

KNOWLEDGE CHECK

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.

intellimetrics · Arlington, VA
© 2026 intellimetrics.net
Search lessons