The Executive Briefing Generator
Last reviewed
AdvancedWhat you'll learn
~50 min- Aggregate data from multiple procurement tools into a unified portfolio view
- Generate project scorecards with RAG (Red/Amber/Green) status indicators
- Build risk heat maps showing probability vs. impact for procurement risks
- Produce AI-generated narrative briefings with executive-ready formatting
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.
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.”
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 summaries of the submittal tracker, budget hound, lead time watchboard, and delivery war room — the tools you already built. Sample files ship with it; for real data, ask each of those tools for a
--jsonexport (they print tables and write Markdown, HTML or ICS today) - 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.
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/07-executive-briefing && cd ~/ofci-playbook/07-executive-briefingIn Windows PowerShell:
mkdir ~/ofci-playbook/07-executive-briefing; cd ~/ofci-playbook/07-executive-briefingOr 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 RAG scorecard thresholds and risk heat map rules before writing code.
The conversation
Say what you want
Ask for the executive briefing tool in plain English:
I prepare monthly procurement reviews. Help me build a tool called executive-briefing that aggregates project JSON summaries into RAG scorecards, an ASCII risk heat map, and a narrative briefing. Ask me what you need first.Answer its questions
Guide the agent’s questions with the reporting structure your VP expects:
| If it asks | You might say |
|---|---|
| What JSON files should each project folder contain? | budget.json, submittals.json, leadtimes.json, and deliveries.json under data/sv9/, data/ch2/, and data/den3/. |
| How are the four RAG scorecard dimensions scored? | Score schedule, budget, submittals, and deliveries as Green, Amber, or Red, with overall RAG set to the worst dimension. |
| How should the risk heat map work? | Plot a 3x3 ASCII grid of Probability (Unlikely, Possible, Likely) by Impact (Low, Medium, High) derived from project data. |
| What should the executive narrative include? | Executive summary, portfolio RAG table, per-project sections, top 5 risks with mitigations, upcoming 30-day milestones, and VP decisions needed. |
| Which subcommands should the CLI support? | briefing, scorecard, risks, and highlights, with optional —project, —period, —data-dir, and —output flags. |
ℹReference notes to hand the agent (or check against)click to expand
Sample JSON schemas for data/sv9/, data/ch2/, and data/den3/:
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 }
Project scorecard RAG rules (overall project RAG is the worst of the four dimensions):
- Schedule (from
leadtimes.json): Green = all items green/yellow, none past order-by; Amber = 1-2 items red, none black; Red = any item in black (past order-by date). - Budget (from
budget.json): Green = variance< 5%; Amber =5-10%; Red => 10%. - Submittals (from
submittals.json): Green = no Tier 3 overdue and< 10%overdue; Amber = 1-2 Tier 3 overdue or10-20%overdue; Red = 3+ Tier 3 overdue or> 20%overdue. - Deliveries (from
deliveries.json): Green = all next-30-day deliveries confirmed and no conflicts; Amber = 1-2 unconfirmed or 1 conflict; Red = 3+ unconfirmed or 2+ conflicts.
Risk heat map mappings (3x3 grid of Probability x Impact):
- 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
For packages, use commander, cli-table3, and chalk@4 (chalk 5 and later are ES-module-only and break require()).
Read the plan
Before approving the agent’s plan, check four details:
- Worst-dimension overall RAG: Each project’s overall RAG indicator equals the most severe of its Schedule, Budget, Submittals, and Deliveries dimensions (any Red dimension makes the project Red).
- Graceful missing-file handling: The aggregator reads
budget.json,submittals.json,leadtimes.json, anddeliveries.jsonfrom each project subdirectory and marks any absent file as unavailable rather than crashing. - Data-driven 3x3 risk heat map: Risks are classified into the Unlikely/Possible/Likely by Low/Medium/High grid from actual project metrics, not hardcoded placeholder strings.
- Specific narrative briefing: The generated Markdown briefing names specific projects, dollar amounts, equipment items, and overdue counts, and ends with prioritized decisions for the VP.
If the plan averages the four RAG dimensions instead of taking the worst one, steer it first:
Set each project's overall RAG status to the worst of its four dimensions, so any Red dimension makes the project Red.Approve the plan once all four items are in place, 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 scorecards and risk heat map, and generate the executive briefing:
Install what the tool needs, run the scorecard, risks, and briefing commands across SV9, CH2, and DEN3, and show me the executive briefing.If you prefer running the commands in a terminal yourself:
cd executive-briefingnpm installnode src/index.js briefingnode src/index.js scorecardnode src/index.js risksThe 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 one 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. Look for budget.json, submittals.json, leadtimes.json, and deliveries.json inside each project folder under --data-dir, and mark any missing file as "data unavailable" in the scorecard without crashing. |
| RAG status is always green | All dimensions show green regardless of the data. Compare budget variance_pct as a number, trigger amber when overdue_count exceeds 10% of total, check lead-time red and black counts against zero, and print the raw numbers alongside each RAG status. |
| Narrative is too generic | The narrative reads like a generic template. Reference the specific project codes, dollar amounts, equipment types, and overdue counts from the loaded data, such as naming the exact Tier 3 overdue submittals and their days past due. |
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)
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 summarizes one of your other procurement tools — the budget hound, submittal tracker, lead time watchboard, delivery war room. Those tools don’t write JSON as built, so the sample files simulate it until you add a
--jsonexport to each one (a one-line follow-up prompt in that tool’s folder). - 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 JSON, adds trend arrows (improving, stable, declining) to each scorecard dimension, and calls out any RAG status changes in the executive summary.Add action item tracking
Add an actions subcommand that extracts recommended actions into output/actions.json with project, owner, priority, due_date, and status, plus actions update <id> --status done so the next briefing tracks outstanding items.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.
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 through a short plan-mode conversation.