The Executive Briefing Generator

What you’re building

It’s the first Monday of the month. Your VP has the standing procurement review at 2 PM. She wants three things: a one-page scorecard for each project, a portfolio risk summary, and a narrative briefing she can forward to the SVP of Construction. You know how this usually goes. You spend six hours pulling data from your submittal tracker, budget spreadsheets, delivery schedule, and lead time log, wrestling it into PowerPoint, and quietly hating every minute of it. Then she reads the first slide, asks a question you already answered on slide 14, and the meeting runs 20 minutes over.

This tool does the entire thing in one command. The six-hour death march becomes a 15-second terminal run. You get those six hours back, and your VP gets a briefing that actually answers her questions up front instead of burying them in slide transitions.

💬The executive translation layer

Here’s the thing about VPs: they don’t care about the details of your submittal lifecycle states or your waterfall chart methodology. They care about three questions: “Are we on time?”, “Are we on budget?”, and “What should I be worried about?” This tool translates your detailed procurement data into those three answers. It’s like when someone in the group asks about a bottle — nobody wants a lecture on the mashbill and barrel entry proof. They want to know “is it good?” and “should I grab one?” Same energy.

By the end of this lesson you will have a Node.js CLI tool that reads data from your other procurement tools’ output files, generates project-level scorecards with RAG status, builds a risk heat map, and produces a narrative briefing document. It writes the memo your VP actually wants to read — not the 47-slide PowerPoint you were going to build, but a clean summary that says “here’s what’s on fire, here’s what’s fine, here’s what you need to decide.”

ℹSoftware pattern: Multi-source synthesis with automated narrative generation

Multiple data sources → aggregation → scoring → visualization → narrative summary. This pattern works for any executive reporting: program status reviews, quarterly business reviews, board reports, investor updates. Anywhere you need to synthesize detailed operational data into a strategic summary.

The showcase

Here’s what rolls out of this thing when you run it:

Input: JSON/CSV output files from the submittal tracker, budget hound, lead time watchboard, and delivery war room — the tools you already built
Project scorecards: One-page per project with RAG indicators for schedule, budget, submittals, and deliveries. Your VP sees Red/Amber/Green before she reads a single word. That’s the point.
Risk heat map: ASCII grid mapping procurement risks by probability (likely/possible/unlikely) and impact (high/medium/low). No more guessing which fire to put out first.
Narrative briefing: Multi-paragraph executive summary with project highlights, risk callouts, and recommended actions. Written in the tone your VP expects — professional, direct, no bullshit filler.
Output: Markdown document formatted for PDF conversion or email distribution. Copy, paste, send. Done before lunch.

The prompt

Build a Node.js CLI tool called executive-briefing that generates monthly
procurement portfolio reports for VP-level review.

PROJECT STRUCTURE:
executive-briefing/
  package.json
  src/
    index.js          (CLI entry point using Commander.js)
    aggregator.js     (data aggregation from multiple tool outputs)
    scorecard.js      (project scorecard with RAG status generator)
    heatmap.js        (risk heat map builder)
    narrative.js      (executive narrative generator)
    formatter.js      (Markdown output formatter)
  data/
    sv9/              (output files from other tools for SV9)
      budget.json
      submittals.json
      leadtimes.json
      deliveries.json
    ch2/
      budget.json
      submittals.json
      leadtimes.json
      deliveries.json
    den3/
      budget.json
      submittals.json
      leadtimes.json
      deliveries.json

REQUIREMENTS:

1. CLI INTERFACE (src/index.js)
   Subcommands:
     node src/index.js briefing [--project <code>]    (full executive briefing)
     node src/index.js scorecard [--project <code>]   (project scorecards only)
     node src/index.js risks [--project <code>]       (risk heat map only)
     node src/index.js highlights                     (key highlights and actions only)
   Options:
     --data-dir <path> (directory with project data, default: ./data)
     --output <path> (output directory, default: ./output)
     --period <month> (reporting period, default: current month)

2. DATA FILES (data/*/json)
   Create sample JSON files for each project simulating output from other tools.

   budget.json: { project, total_budget, committed, actual, change_orders,
     variance_pct, health, top_variances: [{item, amount, reason}] }

   submittals.json: { project, total, approved, in_review, pending, rejected,
     overdue_count, overdue_tier3: [{id, equipment, vendor, days_overdue}] }

   leadtimes.json: { project, total_items, green, yellow, red, black,
     critical_items: [{id, equipment, days_remaining, order_by_date}] }

   deliveries.json: { project, upcoming_30days, conflicts,
     next_delivery: {date, equipment, vendor}, confirmed_count, pending_count }

3. PROJECT SCORECARDS (src/scorecard.js)
   For each project, generate a scorecard with RAG status for four dimensions:

   a. SCHEDULE: Based on lead time data
      - Green: all items green/yellow, no items past order-by date
      - Amber: 1-2 items in red, no items in black
      - Red: any items in black (past order-by date)

   b. BUDGET: Based on budget data
      - Green: portfolio variance < 5%
      - Amber: variance 5-10%
      - Red: variance > 10%

   c. SUBMITTALS: Based on submittal data
      - Green: no Tier 3 overdue items, <10% of submittals overdue
      - Amber: 1-2 Tier 3 overdue, or 10-20% overdue
      - Red: 3+ Tier 3 overdue, or >20% overdue

   d. DELIVERIES: Based on delivery data
      - Green: all deliveries in next 30 days confirmed, no conflicts
      - Amber: 1-2 unconfirmed or 1 conflict
      - Red: 3+ unconfirmed or 2+ conflicts

   Scorecard format: project name, overall RAG (worst of four dimensions),
   then each dimension with its RAG and a one-line summary.

4. RISK HEAT MAP (src/heatmap.js)
   Build an ASCII heat map grid:
   - X-axis: Impact (Low, Medium, High)
   - Y-axis: Probability (Unlikely, Possible, Likely)
   - Each cell contains a list of risks that fall in that category
   - Color-code cells: green (low probability + low impact),
     yellow (medium), red (high probability or high impact)

   Auto-generate risks from the data:
   - Budget overrun >10% → Likely + High Impact
   - Submittal Tier 3 overdue → Likely + Medium Impact
   - Lead time black status → Possible + High Impact
   - Delivery conflict → Possible + Medium Impact
   - Multiple change orders → Possible + Low Impact

5. NARRATIVE GENERATOR (src/narrative.js)
   Generate an executive briefing document with:
   - Title: "OFCI Procurement Portfolio Briefing — [Month Year]"
   - Executive summary: 3-4 sentences covering overall portfolio health
   - Portfolio overview: table of all projects with overall RAG status
   - Per-project sections: scorecard + key highlights + action items
   - Risk summary: heat map + top 5 risks with mitigation actions
   - Upcoming milestones: key dates in the next 30 days
   - Recommended actions: prioritized list of decisions needed from VP

   Tone: professional but direct. No jargon that needs explanation.
   Format: Markdown with headers, tables, bold for emphasis, bullet lists.

DEPENDENCIES: commander, chalk, cli-table3

SAMPLE RUN:
node src/index.js briefing
# Generates full portfolio executive briefing

node src/index.js scorecard --project SV9
# Shows SV9 scorecard only

node src/index.js risks
# Shows portfolio risk heat map

node src/index.js highlights
# Shows just the highlights and action items

What you get

Fire it up

cd executive-briefing
npm install
node src/index.js briefing
node src/index.js scorecard
node src/index.js risks

The briefing command generates a complete Markdown document ready for PDF conversion or email. That thing that used to take you six hours and three coffees? It’s a terminal command now. The scorecard shows RAG status for each project — your VP’s favorite language. The risks command shows the portfolio risk heat map, which is what you pull up when someone asks “what should I be worried about?” and you don’t want to answer from memory.

If something is off

Problem	Follow-up prompt
JSON files not loading	`The aggregator can't read the data files. Make sure it looks for .json files in each project subdirectory under --data-dir. Use path.join(dataDir, projectCode, 'budget.json') etc. If a file doesn't exist, skip that data source and note it as "data unavailable" in the scorecard.`
RAG status is always green	`All dimensions show green regardless of the data. Check the threshold logic: budget variance_pct should be compared as a number (not string), overdue_count should trigger amber at >10% of total, and lead time red/black counts should be checked against zero. Print the raw values alongside the RAG status for debugging.`
Narrative is too generic	`The narrative reads like a template with placeholder text. It should reference specific project names, dollar amounts, equipment types, and dates from the actual data files. Replace generic phrases like "some items are overdue" with specific statements like "SV9 has 3 Tier 3 overdue submittals: Eaton switchgear (22 days), Trane chiller (16 days), and Vertiv UPS (18 days)."`

🔧

When Things Go Wrong

Use the Symptom → Evidence → Request pattern: describe what you see, paste the error, then ask for a fix.

Symptom

The risk heat map has all risks in the same cell

Evidence

Every auto-generated risk appears in the 'Likely + High Impact' cell, making the heat map useless for prioritization

What to ask the AI

"The risk classification logic needs calibration. Map risks to cells based on the actual data severity: budget overrun >10% = Likely+High, 5-10% = Possible+Medium, <5% = Unlikely+Low. Submittal Tier 3 with >20 days overdue = Likely+High, 15-20 days = Possible+Medium. Lead time black = Likely+High, red = Possible+Medium. The goal is distribution across the grid so the VP can see which risks are truly critical vs. which are watchlist items."

Symptom

The scorecard overall RAG doesn't match the worst dimension

Evidence

SV9 shows Schedule=Red, Budget=Green, Submittals=Amber, Deliveries=Green, but the overall status shows Amber instead of Red

What to ask the AI

"The overall project RAG should be the worst (most severe) of the four dimensions. If any dimension is Red, overall is Red. If none are Red but any are Amber, overall is Amber. Only show Green if all four dimensions are Green. Fix the logic in scorecard.js to use Math.max on a severity scale (green=0, amber=1, red=2) and map back to the RAG string."

How it works (the 2-minute explanation)

The whole thing is basically a pipeline. Data goes in one end, a VP-ready briefing comes out the other. Here’s what happens in between:

Aggregator pulls in JSON data files from each project’s subdirectory. Each file is the output of one of your other procurement tools — the budget hound, submittal tracker, lead time watchboard, delivery war room. If you already ran those tools, you already have the data. If not, the sample files simulate it.
Scorecard generator is where the magic happens for your VP. It applies threshold rules to four dimensions — schedule, budget, submittals, deliveries — and slaps a Red/Amber/Green status on each one. The overall project RAG is the worst of the four, because that’s how risk works: being under budget doesn’t matter if your switchgear missed its order-by date three weeks ago.
Risk heat map auto-generates risks from the actual data and plots them on a 3x3 grid by probability and impact. No more quarterly risk register updates where someone copies last quarter’s entries and changes the date. These risks are real, they’re current, and they’re derived from what’s actually happening on your projects.
Narrative generator takes all of the above and writes the memo. Not a data dump — an actual briefing with an executive summary, per-project sections, and a prioritized list of decisions your VP needs to make. You know, the thing that used to take you six hours to write manually while questioning your career choices.

Customize it

These are the extensions that turn a good tool into a great one. Pick whichever one would make your Monday less painful.

Add trend comparison

Add a --compare flag that loads the previous month's briefing output (from
output/briefing-YYYY-MM.json) and shows trend arrows on each scorecard
dimension: ↑ improving, → stable, ↓ declining. The executive summary should
call out any dimensions that changed RAG status since last month.

Add action item tracking

Add an "actions" subcommand that extracts recommended actions from the briefing
and writes them to output/actions.json with fields: action, project, owner,
priority, due_date, status. Add "actions update <id> --status done" to mark
items complete. The next briefing should reference outstanding actions from
the previous month.

Key takeaways

RAG status is executive shorthand, and your VP already speaks it — Red/Amber/Green communicates project health faster than any spreadsheet you’ve ever built. She sees the colors before she reads the words. Stop writing paragraphs when a dot will do.
Auto-generated risks from real data destroy manual risk registers — be honest, when’s the last time someone actually updated the risk register? This tool generates risks from today’s actual data, not from whatever someone copy-pasted three months ago.
The narrative bridges data and decisions — numbers tell your VP what happened. Narrative tells her what to do about it. This tool gives her both, and you didn’t have to spend your Sunday night writing it.
One command replaces six hours of your life — 6 hours of manual compilation reduced to 15 seconds. That’s 72 hours per year. Almost two full work weeks that you get back for actual procurement work. Or bourbon. We don’t judge.

KNOWLEDGE CHECK

Your executive briefing shows SV9 with an overall Red status driven by Schedule (Red — two items past order-by date) while Budget is Green and Submittals are Amber. Your VP asks: 'If we're under budget, why is this project red?' What's the best explanation?

What’s next

In the final lesson, you build The OFCI Command Center — a web dashboard that integrates all seven tools into a single operational hub. One Express.js server, one browser tab, one “Monday Morning Run” button that refreshes everything and tells you exactly what needs your attention this week. Every tool you’ve built becomes a module in your personal procurement operating system. It’s the difference between having seven useful scripts scattered across your machine and having a platform. And you’re going to build it from one prompt.