---
name: template-pitch-deck
description: Pitch-deck generation exemplar — short/medium/long PDF+PPTX decks from one token-resolved, diligence-cited content source.
version: 1.0.0
author: docxology
license: MIT
tags: [exemplar, slides, reportlab, pptx, mermaid, pitch-deck]
---

# template-pitch-deck

Project-scoped skill for the in-repo exemplar at
`projects/templates/template_pitch_deck/`. Load this when working inside the project.

## When to Use

- Working inside the `template_pitch_deck` exemplar — running scripts, editing content, or regenerating outputs.
- Forking this exemplar as the starting scaffold for a new pitch/grant-report/stakeholder-update deck.
- Adding a new format-agnostic slide renderer to `infrastructure/rendering/` (e.g. this is the reference for `DeckContent`/`Slide`/`DeckTheme`).
- Validating that the exemplar's contracts (thin-orchestrator, token honesty, cliché lint, diligence citation coverage, no-mocks testing) still hold after changes.

## Quick Reference

```bash
# From the repository root
export PATH="$PWD/node_modules/.bin:$PATH"
uv run python projects/templates/template_pitch_deck/scripts/10_audit_deck_content.py
uv run python projects/templates/template_pitch_deck/scripts/15_generate_diagrams.py
uv run python projects/templates/template_pitch_deck/scripts/20_render_decks.py
uv run python projects/templates/template_pitch_deck/scripts/30_audit_diligence.py
uv run pytest projects/templates/template_pitch_deck/tests --cov=projects/templates/template_pitch_deck/src --cov-fail-under=90
uv run pytest tests/infra_tests/rendering/test_slide_deck.py tests/infra_tests/rendering/test_pptx_deck.py tests/infra_tests/rendering/test_mermaid_figure.py
```

PDF and PPTX are required project formats; the isolated project environment
installs `python-pptx` from this exemplar's own `pyproject.toml`. Mermaid
figures require the repository-pinned `node_modules/.bin/mmdc` on `PATH`.

## Pitfalls

- **Keep scripts thin.** Content/validation logic belongs in this project's `src/`; layout/drawing logic belongs in `infrastructure/rendering/{slide_deck,pptx_deck,mermaid_figure}.py` — never in `scripts/`.
- **No mocks.** All tests must use real YAML, real rendered files (read back with `pypdf`/`python-pptx`), real repo introspection.
- **Every fact-bearing slide needs a `source` citation.** `src/diligence_audit.py` fails the build otherwise (title-kind slides are exempt).
- **Never hand-type a fact.** All `PITCH_SUBJECT_*`/`EXEMPLAR_*` token values come from `src/deck_tokens.py::build_deck_tokens`, which reads them live from the repo — adding a new fact means adding a new live read, not a literal.
- **PDF/PPTX parity is load-bearing.** The two renderers must always produce identical slide counts, text, fitted title sizes, and planned body line breaks for the same `DeckContent`. The exact Helvetica fitter and content layout planner live in `slide_deck.py`; `pptx_deck.py` consumes their results rather than estimating again. A title below the legibility floor or body crossing the QR/footer protected band fails before either output is replaced.
- **Do not compress the public roster into other claims.** Medium and long each dedicate one cited slide to all live exemplar names and a following, identically cited slide to the concrete-instance and uniform-contract claims. Tests bind each authored deck to its declared budget while proving the split, source, and exact live roster dynamically from `PUBLIC_PROJECT_NAMES`.
- **Donut percentages require measured contrast.** Keep outside labels theme-black on the white canvas, but choose theme-black or theme-white for each percentage from the real wedge artist's alpha-composited color. The project helper fails closed below 4.5:1, and tests inspect real Matplotlib artists rather than mocks.
- **QR codes need a real `source_base_url`.** `Slide.qr_url` (drawn bottom-right, both renderers) is only populated when `manuscript/config.yaml`'s `deck.source_base_url` is non-empty — `attach_qr_urls` is a no-op otherwise. New infra capabilities (QR generation reuses `infrastructure.steganography.barcode_generators.generate_qr_code`) need their transitive dependency (`qrcode[pil]`) declared in THIS project's own `pyproject.toml`, not just the root repo's — see the isolated-venv pitfall below.
- **Isolated-venv dependency check is not a one-time step.** Every time new code imports a not-yet-used `infrastructure.*` capability, re-run `uv run python scripts/pipeline/stage_01_test.py --project templates/template_pitch_deck --project-only` (not a bare root-venv `pytest`) — it is the only thing that catches a transitive dependency (reportlab/pypdf/Pillow/qrcode so far) missing from this project's own `pyproject.toml`.
- **Outputs are disposable.** Never hand-edit `output/`; regenerate from `manuscript/` + `src/`. This includes `output/slides_standalone/*.md` — generated per-slide pages, not hand-authored.
- **Run from the repo root.** Commands assume the template monorepo root as working directory.

## Cross-refs

- Project contract: [`AGENTS.md`](../../../AGENTS.md)
- README: [`README.md`](../../../README.md)
- TODO: [`TODO.md`](../../../TODO.md)
- Rendering primitives: `infrastructure/rendering/slide_deck.py`, `pptx_deck.py`, `mermaid_figure.py`
- Exemplar roster: [`projects/AGENTS.md`](../../../../AGENTS.md)