The Budget Hound

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.

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.

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 by <5%), Yellow (within +/-5%), Red (over budget by >5%). 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.

The prompt

Build a Node.js CLI tool called budget-hound that tracks and analyzes
procurement budgets across multiple data center construction projects.

PROJECT STRUCTURE:
budget-hound/
  package.json
  src/
    index.js          (CLI entry point using Commander.js)
    csv-loader.js     (budget CSV loading and normalization)
    variance.js       (variance calculation engine)
    waterfall.js      (ASCII waterfall chart renderer)
    narrative.js      (budget health narrative generator)
    formatter.js      (Markdown and terminal output formatting)
  data/
    sv9-budget.csv    (sample budget data)
    ch2-budget.csv
    den3-budget.csv

REQUIREMENTS:

1. CLI INTERFACE (src/index.js)
   Subcommands:
     node src/index.js summary [--project <code>]    (portfolio or project budget summary)
     node src/index.js variance [--project <code>]    (detailed variance analysis)
     node src/index.js waterfall [--project <code>]   (waterfall chart)
     node src/index.js report [--project <code>]      (full budget health report as Markdown)
   Options:
     --data-dir <path> (directory with budget CSVs, default: ./data)
     --output <path> (output directory, default: ./output)
     --threshold <pct> (variance alert threshold, default: 5)

2. CSV FORMAT (data/*.csv)
   Columns: equipment_id, project, equipment_type, description, vendor,
   budget_amount, committed_amount, actual_amount, change_orders,
   forecast_amount, notes

   Sample data per project (8-10 line items):
   - Mix of equipment types: generators, switchgear, chillers, CRAHs, UPS, PDUs
   - Some items under budget, some on track, some over budget
   - Change orders on 2-3 items per project
   - Realistic data center pricing (2500kW-class / enterprise-scale):
     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)

3. VARIANCE ENGINE (src/variance.js)
   Calculate per line item:
   - budget_variance: committed_amount - budget_amount (negative = under budget)
   - actual_variance: actual_amount - committed_amount
   - total_variance: (actual_amount + change_orders) - budget_amount
   - variance_pct: total_variance / budget_amount * 100
   - health: green (<-5% or within 5%), yellow (5-10% over), red (>10% over)

   Calculate per project:
   - Sum of all line items for each column
   - Project-level variance percentage
   - Contingency consumption (if tracked)

   Calculate portfolio level:
   - Sum across all projects
   - Portfolio variance percentage
   - Project-level comparison

4. WATERFALL CHART (src/waterfall.js)
   ASCII waterfall showing the budget flow for a project:
   - Start: Original Budget
   - Step 1: +/- Committed vs Budget (show the delta)
   - Step 2: +/- Change Orders
   - Step 3: +/- Actual vs Committed
   - End: Current Position
   Use bars that go right for increases and left for decreases.
   Color increases in red and decreases in green.
   Show dollar amounts and percentages on each bar.

5. NARRATIVE GENERATOR (src/narrative.js)
   Generate a budget health summary containing:
   - One-sentence overall status ("SV9 procurement is 3.2% over budget at $12.4M committed against $12.0M budget")
   - Top 3 variance drivers (which equipment items are causing the biggest over/under)
   - Change order impact summary
   - Risk flags for any items >10% over budget
   - Forecast commentary (if forecast differs from committed)
   - Recommendation (e.g., "Review switchgear pricing — $180K over budget due to copper price escalation. Consider value engineering on cable tray routing to offset.")

DEPENDENCIES: commander, csv-parse, chalk, cli-table3

SAMPLE RUN:
node src/index.js summary
# Shows portfolio-level budget summary across all projects

node src/index.js variance --project SV9
# Shows detailed variance table for SV9

node src/index.js waterfall --project SV9
# Shows ASCII waterfall chart for SV9 budget flow

node src/index.js report
# Generates full budget health report for all projects

What you get

Fire it up

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

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 a
snapshots/YYYY-MM-DD.json file. Add a "trend" subcommand that loads all
snapshots and shows how the portfolio variance has changed over time as
an ASCII line chart. This lets you see if you're trending toward or away
from budget as the projects progress.

Add contingency tracker

Add support for a contingency_amount column in the CSV. Track how much
of each project's contingency has been consumed by change orders and
overages. Show a "contingency health" indicator: percentage remaining
and projected depletion date based on current burn rate.

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.

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.