mbb-decks

MBB Decks

Generate consulting-grade .pptx decks from a JSON spec. Encodes the MBB house-style rules: action-title storyline, six-section structure, MECE bullets, citation discipline, and a navy-and-white editorial visual system.

When to use

• User asks for an MBB deck, McKinsey-style deck, consulting deck, board pre-read, executive readout, market entry deck, due diligence deck, recommendation deck, or strategy presentation.
• User provides analysis that needs to be turned into slides for a non-technical executive audience.
• User wants a real .pptx file, not a Markdown outline.

Workflow: ghost deck first, expand second

Do NOT skip the ghost-deck step. It is the single biggest quality lever.

0. Verify renderer dependencies (first run only). Before producing any deck, confirm Python 3.9+ and python-pptx are installed by running:

   python3 -c "import pptx; print(f'python-pptx {pptx.__version__} on Python {__import__(\"sys\").version.split()[0]}')"
   

   If this prints a version, skip to step 1. If it errors with ModuleNotFoundError: No module named 'pptx', tell the user:

   The renderer needs python-pptx. Run pip install python-pptx in your terminal, then say "ready" and I'll continue. Wait for the user to confirm before proceeding. The build script also fails gracefully with the same install message if you skip this check, but checking up front gives a cleaner experience.

1. Ghost deck. Produce only the action titles for every slide (cover, executive summary headline, agenda items, every content slide's action title, recommendation headline). Read them top to bottom as a paragraph. They must form one coherent argument: situation → complication → resolution, or claim → evidence → recommendation.
2. Confirm with the user. Show the ghost deck. Ask: "Does this storyline land? Anything to add, cut, or reorder before I expand?" Wait for confirmation.
3. Expand. Fill in bullets, charts, footnotes, sources. Keep each slide MECE under its action title.
4. Render. Write the JSON spec to disk and call scripts/build_deck.py.

Deck structure (six sections)

Hard cap: 15 slides for sections 1 to 5. Appendix is unbounded.

#	Section	Notes
1	Cover	Title, subtitle, author, organization. Blank theme.
2	Executive summary	One headline that answers "so what." Three to five MECE bullets.
3	Agenda	Two to four sections. Section titles match the dividers.
4	Sections	Each begins with a divider slide (number + title). Two to four content slides per section.
5	Recommendation	Headline + action table (Owner / Action / Outcome). Action table is mandatory.
6	Appendix	Optional. Backup detail and supporting analysis. Same content slide format.

Action title rules

Every slide except cover, dividers, and appendix divider has an action title. The action title carries the meaning. The body proves it.

• One full sentence, 10 to 15 words. Subject + verb + claim.
• Specific. "Vietnam middle-class spending grows 7% CAGR through 2030" beats "Market is attractive."
• Stand-alone. A reader skimming only the action titles must understand the argument.
• Causal where possible. "X drives Y" beats "X and Y."
• No questions, no labels. "Market sizing" is a label, not an action title. Replace with the finding.

Read all action titles in sequence before writing any body content. If the sequence does not tell a coherent story, fix the storyline before expanding.

MECE bullets

Each slide has 3 to 5 bullets max. They must be:

• Mutually exclusive. No overlap.
• Collectively exhaustive. No obvious gap under the action title.
• Parallel structure. Same grammatical pattern across bullets on a slide.
• Concrete. Numbers, dates, named entities. "Three local partners screened" beats "Several partners considered."

Visual system

Defaults are encoded in scripts/build_deck.py. Do not override unless the user explicitly asks.

Element	Specification
Background	White #FFFFFF
Headlines	Georgia, deep navy #051C2C
Body text	Calibri, near-black #1A1A1A
Accent	Electric blue #2251FF, used sparingly for rules and section numbers
Gridlines, dividers	Light grey #E5E7EB
Footnotes, sources, page numbers	Calibri 8pt, mid-grey #949BA8
Slide size	16:9, 13.333" × 7.5"
Margins	0.5" left and right
Page number	Lower right, format Page X / Y
Date in footer	Never
Icons	Never, unless user explicitly requests

Chart families

Pick the chart that matches the claim in the action title.

Action title verb	Chart family
"Grows," "declines," "trended"	Column or line
"Composed of," "share of"	100% stacked column or pie (pie used sparingly)
"Higher than," "ranks first"	Bar (horizontal) sorted by value
"Drives," "explains"	Waterfall or stacked bar
"Correlates with"	Scatter
"Builds from X to Y"	Waterfall

The script currently renders column-clustered charts cleanly. For other chart types, fall back to bullets and describe the data in prose, then add the chart in PowerPoint manually OR extend the script.

Citation format

• Inline marker in body text: [1], [2], etc., when a specific number or claim needs attribution.
• Source line at the bottom of the slide: Source: [text](url); [text](url). Use markdown-style [text](url) syntax so each source is rendered as a clickable hyperlink in the .pptx. Multiple sources separated by semicolons. Plain text without (url) still works for sources that have no public URL.
• Footnote line above the source: explanatory note about a number (e.g., "Excludes Singapore"). Distinct from source.
• No source line if the slide makes no specific data claim.

Data sourcing rules (critical)

The skill is only as credible as its numbers. These rules apply to every chart, every bullet, every claim with a number in it.

Always use the current year

Today's date is available in your runtime context. Use it.

• For historical data: cite the most recent available release. If a 2026 dataset exists, do not cite the 2023 version.
• For forward-looking projections: forecast labels should start from the current year forward. If today is in 2026, forward years are 2026E, 2027E, 2028E. Never label a past year as E (estimate).
• For "as of" qualifiers in footnotes: say "as of Q[current quarter] [current year]", not a stale date.

Use only authoritative, recognized sources

A short non-exhaustive list of sources Claude should reach for, by domain:

Domain	Authoritative sources
Macro and trade	World Bank, IMF, OECD, BIS, UN ComTrade, WTO
Cloud and AI infrastructure	Synergy Research Group, IDC, Dell'Oro Group, Gartner, JLL Data Center Outlook, Structure Research
Energy and climate	IEA, BloombergNEF, EIA, Lazard LCOE, NREL ATB, Wood Mackenzie
Financial markets	Bloomberg, S&P Global, Refinitiv (LSEG), FactSet, Capital IQ, PitchBook, Preqin
Consulting/strategy reports	McKinsey Global Institute, BCG, Bain (publicly cited), Oliver Wyman
Consumer	Euromonitor, Nielsen, Kantar, eMarketer, Statista
Public companies	Company 10-K, 10-Q, S-1, earnings transcripts (SEC EDGAR)
Regulatory and policy	Federal Reserve, BLS, BEA, ECB, EU Commission, regulator filings

Do NOT use: random blog posts, AI-generated summaries, paywalled content without a verifiable cite, or "Statista projections" as the only source for a numeric claim.

Every source needs a clickable URL when one exists

Format: Source: [BloombergNEF Energy Transition Investment Trends, 2025](https://about.bnef.com/energy-transition-investment/); [IEA World Energy Outlook, 2024](https://www.iea.org/reports/world-energy-outlook-2024)

The build script automatically:

• Renders each [text](url) segment as a hyperlink in the .pptx.
• Sends a HEAD request to each URL at render time. If the URL returns a 4xx error, the link is dropped silently and only the plain text is rendered. The reader does not see a broken link.
• Leaves the link in place for non-4xx outcomes (network timeout, DNS error, blocked HEAD), since we cannot definitively call those broken.

If you cannot find a public URL for a specific report, leave the source as plain text. Do not invent URLs.

Pairing chart with commentary

Never ship a chart slide as just a chart. Every chart slide should carry its own commentary panel on the same slide so the reader gets the picture and the takeaway in one view. If the bullets describing a chart end up on the next slide, merge them.

Two layouts:

• commentary_position: "right" (default). Chart takes left 62%, "KEY TAKEAWAYS" panel on the right with three to four bullets. Use for most chart slides.
• commentary_position: "below". Chart full-width on top (~2.8" tall), commentary in a 2-column row below. Use when the chart needs more horizontal room (5+ categories with multiple series), or when there are 4+ takeaway bullets.

Logos as bullet markers

Wherever a commentary or two-column bullet focuses on a single named entity (company, regulator, sovereign fund), use the entity's logo as the bullet marker instead of an abstract icon or a plain dot. The skill auto-downloads logos from logo.dev (a public token ships with the skill; override with LOGODEV_TOKEN for a private quota) and caches them in assets/logos/. If logo.dev does not yet have a brand mark for the domain it returns HTTP 202 and the bullet falls back to a plain • marker rather than a placeholder.

A bullet entry can be:

• A plain string → renders with • marker.
• { "icon": "→", "text": "..." } → renders the glyph in navy as the marker.
• { "logo": "microsoft.com", "text": "..." } → renders the company logo as the marker. Auto-downloaded on first render and cached.
• { "logo": "...", "icon": "...", "text": "..." } → logo wins.

If a bullet covers a concept rather than an entity (a region, a principle), use icon, not logo. If it names multiple companies, split the bullet so each has one anchor entity.

JSON spec

The script reads a JSON file with this shape. See examples/market-entry/input.json and examples/data-center-landscape/input.json for complete worked examples.

{
  "meta": { "title": "...", "subtitle": "...", "author": "...", "organization": "..." },
  "executive_summary": {
    "headline": "Full-sentence claim, 15 to 25 words",
    "bullets": ["...", "...", "..."]
  },
  "agenda": [
    { "title": "Section title", "subtitle": "Optional subtitle" }
  ],
  "sections": [
    {
      "title": "Matches an agenda title",
      "slides": [
        {
          "action_title": "Full sentence, 10 to 15 words",
          "content_type": "bullets",       // or "bar_chart" or "two_column"

          // for content_type "bullets"
          "bullets": [
            "Plain bullet text",
            { "icon": "$", "text": "Bullet with abstract icon marker" },
            { "logo": "microsoft.com", "text": "Bullet with company logo marker" }
          ],

          // for content_type "bar_chart"
          "chart": {
            "categories": ["A", "B", "C"],
            "series": [{ "name": "...", "values": [1.0, 2.0, 3.0] }],
            "unit": "USD millions"
          },
          "commentary": [                  // optional; pairs with chart
            { "logo": "aws.amazon.com", "text": "AWS-specific takeaway" },
            { "logo": "microsoft.com", "text": "Azure-specific takeaway" },
            { "icon": "◆", "text": "General takeaway not tied to one company" }
          ],
          "commentary_position": "right",  // or "below"; default "right"

          // for content_type "two_column"
          "left_header": "...",
          "left":  [ "plain", { "icon": "$", "text": "..." }, { "logo": "...", "text": "..." } ],
          "right_header": "...",
          "right": [ /* same shape as left */ ],

          "footnote": "Optional. Auto-prefixed with '*'. Body or chart label should carry a matching '*' marker.",
          "source": "Optional. Format: '[Org], [Publication], [Year]; [Org 2], [Year]'"
        }
      ]
    }
  ],
  "recommendations": {
    "headline": "Approve / proceed / invest claim",
    "actions": [
      { "owner": "CFO", "action": "Specific action by date", "outcome": "What it produces" }
    ]
  },
  "appendix": [
    // Same shape as section slides
  ]
}

Calling the build script

python scripts/build_deck.py <input.json> <output.pptx>

The script validates the slide count and prints a warning if the main deck exceeds 15 slides.

Common mistakes

Mistake	Fix
Action title is a label ("Market sizing")	Rewrite as a sentence with a verb and claim
Action titles do not connect into a story	Reorder or rewrite. Read them all aloud as one paragraph.
More than five bullets per slide	Cut to three or split the slide
Bullets repeat the action title	Bullets must add evidence, not restate the claim
Chart slide with no commentary	Add a commentary panel on the same slide; never let bullets describing a chart spill onto the next slide
Chart is decorative, not load-bearing	Replace with the chart that proves the action title
No source on a data slide	Add one. Every numeric claim needs attribution.
Decorative icons sprinkled into body text	Remove. Use icons or logos only as bullet markers, never as page decoration
Bullet names a company but uses an abstract icon	Replace with {"logo": "<domain>", "text": "..."}; the logo becomes the marker
Mixing logo markers and navy-circle icons in the same panel	Drop the circle background on icon glyphs (the script does this automatically)
Em dashes	Replace with periods or commas. House style is no em dashes.
Date in footer	Remove. House style omits date.
Slide count exceeds 15 in main deck	Move detail to appendix.

Red flags that mean stop and restart

• "I'll write the slides first and figure out the story after." Stop. Ghost deck first.
• "The action title is too long, I'll shorten it." Check it is still a complete claim. If a label is shorter, that is not the right tradeoff.
• "Three bullets is not enough, I have more to say." Split into two slides or move detail to appendix.
• "I'll put the chart on one slide and the bullets describing it on the next." Stop. Merge them. Add a commentary panel on the same slide.
• "I'll add a few icons to make it visual." Use logos for bullets that name a company. Use abstract icons only for concept bullets. Never sprinkle decorative icons.