---
name: optima-slt-deck-builder
description: Generates Optima Living JV partner monthly board decks (PowerPoint plus Excel companion) from source data. Supported partners: Welltower, Yarrow, Wisteria, Charis. ALWAYS use when Scott or the SLT says "build the [partner] deck", "generate the [partner] [Month] [Year] report", "run the deck skill", "produce the monthly board deck", or any variation of assembling a JV partner monthly board report. Also trigger when partner source data files are uploaded, or on "build the SLT deck" without a partner named (skill will ask). Ingests Yardi financials and occupancy, Welcome Home CRM, Google Ads, Dayforce HR, capex tracker, and operational highlights, then produces a partner-specific deck and foot-and-tied Excel companion matching that partner's approved master template. Replaces the prior welltower-deck-builder skill.
---

# Optima SLT Deck Builder

## Purpose

Produces an Optima Living JV partner monthly board deck end-to-end from source data files. The output is a partner-specific PowerPoint deck (24 slides by default) plus a companion Excel financial package, brand-faithful to the approved master template for that partner and tied numerically to source data.

This is the Phase 0 prototype that proves the dual-path delivery framework laid out in the JV Partner Board Deck Automation PRD. It runs as a Claude skill. Phase 1 ports the same logic into a Lovable web app for production rollout to the SLT and contributor base.

## Supported partners

| Partner    | Default communities                                                                          | Master template                       | Config                          | Voice anchors                          |
|------------|----------------------------------------------------------------------------------------------|---------------------------------------|---------------------------------|----------------------------------------|
| Welltower  | Aspen Ridge, Inglewood, Meadowlands, Parkwood Place, The Kensington Victoria (plus 6 coming) | `templates/welltower_master.pptx`     | `configs/welltower.json`        | `reference/voice_anchors_welltower.md` |
| Yarrow     | Confirm before generating                                                                    | `templates/yarrow_master.pptx`        | `configs/yarrow.json`           | `reference/voice_anchors_yarrow.md`    |
| Wisteria   | Confirm before generating                                                                    | `templates/wisteria_master.pptx`      | `configs/wisteria.json`         | `reference/voice_anchors_wisteria.md`  |
| Charis     | Confirm before generating                                                                    | `templates/charis_master.pptx`        | `configs/charis.json`           | `reference/voice_anchors_charis.md`    |

Each partner has its own template, config, and voice anchors. The skill never crosses partner boundaries.

## When to invoke

Trigger immediately on any of:

- "Build the [partner] deck"
- "Generate the [partner] [Month] [Year] report"
- "Run the SLT deck skill"
- "Produce the [partner] monthly"
- A folder of partner source data files appears in the session uploads area

If invoked without a partner named, ask the user which partner. If invoked without source files, ask the user to upload them and provide the input checklist (see `README_INPUTS.md` in this skill folder).

## End-to-end workflow

Follow these steps in order. Do not skip steps. Do not invent data.

### Step 1: Confirm scope

Confirm with the user:

1. **Partner** (Welltower, Yarrow, Wisteria, or Charis). Required. If not stated, ask.
2. **Reporting period** (e.g. April 2026).
3. **Communities in scope** (default from the supported partners table above). For Welltower as of May 2026, six additional communities are coming online — confirm before generating. For Yarrow, Wisteria, and Charis, always confirm communities before generating.
4. **Fresh draft or iteration** on a prior draft (if iteration, ask which prior draft to start from).
5. **Source files location** (default: `/uploads/{partner}-{period}/`, e.g. `/uploads/welltower-april-2026/`).

### Step 2: Validate inputs

Read the input manifest from `README_INPUTS.md` in this skill folder. For each required input:

1. Verify the file exists in the partner-specific source folder.
2. Verify the file matches the expected format (tab names, column headers, row count expectations).
3. If any required input is missing or malformed, stop immediately, list what is missing, and ask the user how to proceed (use a placeholder, skip the section, or wait for the file).

Do not silently proceed past a missing input. Do not invent data to fill gaps.

**Partner isolation rule:** the skill reads source files only from the named partner's folder. It never reads files from another partner's folder in the same run. This rule is enforced by the input validation step, not by trust.

### Step 3: Parse source data into the canonical intermediate JSON

For each input file, parse and normalize into the canonical schema defined in `reference/data_contracts.md`. Write the consolidated intermediate JSON to `/outputs/{partner}-{period}-data.json`.

This intermediate JSON is the **single source of truth** for every number on every slide. Foot-and-tie discipline is structural: if a number is on a slide, it came from this JSON.

### Step 4: Generate narrative content

For each slide that requires AI-drafted narrative:

1. Read the relevant slice of the intermediate JSON.
2. Read the voice anchors for the active partner (e.g. `reference/voice_anchors_welltower.md`).
3. Generate narrative bullets in the appropriate register (operational, financial, or capex).
4. Apply the variance commentary threshold: comment on any line item with greater than 5 percent variance to budget; do not comment on items with less than 5 percent variance.
5. Apply the confidentiality rule: never reference any other partner in this partner's deck. A Welltower deck never names Yarrow, Wisteria, or Charis, and vice versa.

Write all generated narrative back into the intermediate JSON under each section's `narrative` field.

### Step 5: Render the deck

Invoke the build script:

```bash
python3 scripts/build_deck.py \
  --partner {partner} \
  --config configs/{partner}.json \
  --data /outputs/{partner}-{period}-data.json \
  --period "{Month} {Year}" \
  --output /outputs/{Partner}_Monthly_Report_{period}.pptx \
  --excel /outputs/{Partner}_Monthly_Report_{period}.xlsx
```

The build script reads the partner's master template (e.g. `templates/welltower_master.pptx`) for brand fidelity and renders all configured slides plus the Excel companion.

### Step 6: Validate the output

Run the validator:

```bash
python3 scripts/validate_output.py \
  --partner {partner} \
  --data /outputs/{partner}-{period}-data.json \
  --pptx /outputs/{Partner}_Monthly_Report_{period}.pptx \
  --excel /outputs/{Partner}_Monthly_Report_{period}.xlsx \
  --report /outputs/{Partner}_Monthly_Report_{period}_audit.md
```

Validation checks:

1. Foot-and-tie: every number on every slide ties to the intermediate JSON.
2. Narrative-data consistency: every number quoted in narrative bullets matches the same number in the table on that slide.
3. Excel companion ties to the deck.
4. No leftover placeholder text ("To be updated", "TBD", "Lorem", etc.).
5. Brand template fidelity (slide count matches partner config, dimensions = 13.33 x 7.5, font as configured per partner).
6. **Cross-partner contamination check:** no mention of any other partner's name in narrative, table headers, or footer text.

If any check fails, surface the failure to the user before declaring success.

### Step 7: Report and ship

When the deck is complete, report to the user:

1. Output paths for the .pptx and .xlsx files.
2. Total runtime.
3. Validation summary (pass / fail per check).
4. Any sections where AI-drafted narrative may need human review (flagged in the audit report).
5. The `computer://` link to view each output.

Always finish with a concise summary, not a verbose recap. The user knows what they asked for.

## Files in this skill

- `SKILL.md` — this file. Skill entry point.
- `README_INPUTS.md` — Scott-facing checklist of required input files and their formats (shared across partners).
- `configs/{partner}.json` — partner configuration (communities, render mode, overlays, cadence, slide count).
- `reference/slide_spec.md` — slide-by-slide structural specification, with per-partner overrides where they exist.
- `reference/data_contracts.md` — canonical data schema for every section (shared across partners).
- `reference/voice_anchors_{partner}.md` — verbatim narrative passages from real approved decks for that partner, used for few-shot voice anchoring.
- `scripts/build_deck.py` — the python-pptx renderer. Partner-aware via `--partner` flag.
- `scripts/validate_output.py` — the post-render audit. Partner-aware via `--partner` flag.
- `templates/{partner}_master.pptx` — extracted Optima master template for each partner (must be added once per partner, see Considerations doc).
- `CONSIDERATIONS.md` — strategic considerations for SLT review.

## Discipline

Four rules govern every run:

1. **Numbers come from data files. Never from the model.** If a number is not in the intermediate JSON, it does not appear on a slide.
2. **Voice comes from anchors. Never from generic patterns.** Every narrative bullet is anchored on real approved commentary for *that partner*, not on a generic financial-report register and not on another partner's voice.
3. **Confidentiality is structural.** A partner run never reads files from, references, or names another partner. The rule is enforced by input validation and the cross-partner contamination check.
4. **Brand fidelity is per-partner.** Each partner has its own master template, font conventions, and slide structure. Never substitute one partner's template for another.

## What to do when something goes wrong

- **Partner not named:** stop, ask which of Welltower, Yarrow, Wisteria, or Charis.
- **Missing input:** stop, list what is missing, ask the user.
- **Malformed input:** stop, show the user the row or column that does not match the expected schema, ask how to proceed.
- **Voice drifts (output sounds generic, or sounds like another partner):** add the latest approved deck's commentary to `reference/voice_anchors_{partner}.md`, regenerate.
- **Foot-and-tie fails:** show the user which number on which slide does not tie to the JSON, ask whether to fix in source data or override.
- **Brand template missing:** the first run for a partner requires `templates/{partner}_master.pptx` to be extracted from the most recent approved deck for that partner. See `CONSIDERATIONS.md` section "Master template extraction".
- **Cross-partner contamination detected in validation:** stop, surface the offending text, fix the narrative, regenerate.

## Hyperscale, do not replace

The skill does the assembly. The SLT does the judgement. The narrative is AI-drafted to 80 percent and then the human takes it home. Every approved deck for any partner feeds back into that partner's voice anchors for the next cycle.
