---
name: welltower-deck-builder
description: Generates the Optima Living Welltower Monthly Report (PowerPoint plus companion Excel) from uploaded source data files. ALWAYS use this skill when Scott or the SLT says "build the Welltower deck", "generate the Welltower [Month] [Year] report", "run the Welltower skill", "produce the Welltower monthly", "draft the Welltower deck for [period]", or any variation of wanting to assemble the Welltower JV monthly board report from source data exports. Also trigger when source data files for a Welltower cycle are uploaded into a session. The skill ingests Yardi financials and occupancy, Welcome Home CRM data, Google Ads exports, Dayforce HR, capex tracker, and operational highlights, then produces a 24-slide PowerPoint and a foot-and-tied Excel financial companion that match the existing Optima Welltower template exactly.
---

# Welltower Monthly Report Builder

## Purpose

Produces the Optima Living Welltower Monthly Report end-to-end from source data files. The output is a 24-slide PowerPoint deck plus a companion Excel financial package, brand-faithful to the existing Welltower template and tied numerically to source data.

This skill 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 in Cowork. Phase 1 ports the same logic into a Lovable web app for production rollout to the SLT and contributor base.

## When to invoke

Trigger immediately on any of:

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

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. Reporting period (e.g. April 2026)
2. Communities in scope (default: Aspen Ridge, Inglewood, Meadowlands, Parkwood Place, The Kensington Victoria. As of May 2026, six additional Welltower communities are coming online — confirm before generating).
3. Whether this is a fresh draft or an iteration on a prior draft (if iteration, ask which prior draft to start from).
4. Where the source files are located (default: `/uploads/welltower-{period}/`).

### 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 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.

### 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/welltower-{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 in `reference/voice_anchors.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 (Yarrow, Wisteria, Charis) in a Welltower deck.

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 \
  --config config.json \
  --data /outputs/welltower-{period}-data.json \
  --period "{Month} {Year}" \
  --output /outputs/Welltower_Monthly_Report_{period}.pptx \
  --excel /outputs/Welltower_Monthly_Report_{period}.xlsx
```

The build script reads `templates/welltower_master.pptx` for brand fidelity and renders all 24 slides plus the Excel companion.

### Step 6: Validate the output

Run the validator:

```bash
python3 scripts/validate_output.py \
  --data /outputs/welltower-{period}-data.json \
  --pptx /outputs/Welltower_Monthly_Report_{period}.pptx \
  --excel /outputs/Welltower_Monthly_Report_{period}.xlsx \
  --report /outputs/Welltower_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 = 24, dimensions = 13.33 x 7.5, font = Arial throughout).

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.
- `config.json` — Welltower partner configuration (communities, render mode, overlays, cadence).
- `reference/slide_spec.md` — slide-by-slide structural specification of the Welltower deck.
- `reference/data_contracts.md` — canonical data schema for every section.
- `reference/voice_anchors.md` — verbatim narrative passages from real Welltower decks for few-shot voice anchoring.
- `scripts/build_deck.py` — the python-pptx renderer.
- `scripts/validate_output.py` — the post-render audit.
- `templates/welltower_master.pptx` — extracted Optima Welltower master template (must be added once, see Considerations doc).
- `CONSIDERATIONS.md` — strategic considerations for SLT review.

## Discipline

Three 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 Welltower commentary, not on a generic "financial report" register.
3. **Confidentiality is structural.** A Welltower run never reads files from another partner's folder. The rule is enforced by the input validation step, not by trust.

## What to do when something goes wrong

- **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, not Optima):** add the latest approved deck's commentary to `reference/voice_anchors.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 requires `templates/welltower_master.pptx` to be extracted from the most recent approved Welltower deck. See `CONSIDERATIONS.md` section "Master template extraction".

## 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 feeds back into the voice anchors for the next cycle.
