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:

   bashCopy code
   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.

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.

Chart families

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

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:

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.

jsoncCopy code
{
  "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

bashCopy code
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

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.