# Welltower Data Contracts

The skill's intermediate JSON is the single source of truth. Every number on every slide is read from this JSON. The JSON is composed by parsing each input file in `/uploads/welltower-{period}/` and normalizing into the schema below.

This document is the authoritative reference. If a field appears here but is missing from the input, the skill stops and asks. If a field appears in the input but not here, the skill ignores it.

## Top-level shape

```json
{
  "meta": {
    "partner": "welltower",
    "period": "2026-04",
    "period_label": "April 2026",
    "generated_at": "2026-05-05T14:00:00Z",
    "source_folder": "/uploads/welltower-2026-04/",
    "skill_version": "1.0",
    "communities_in_scope": ["aspen_ridge", "inglewood", "meadowlands", "parkwood_place", "kensington_victoria"]
  },
  "operations": { ... },
  "hr": { ... },
  "occupancy": { ... },
  "vacancy": { ... },
  "futures": { ... },
  "projections": { ... },
  "sales": { ... },
  "marketing": { ... },
  "google_ads": { ... },
  "financials": { ... },
  "capex": { ... },
  "narrative": { ... },
  "validation": { ... }
}
```

## operations

```json
"operations": {
  "aspen_ridge": {
    "raw_input": "...source markdown verbatim...",
    "narrative": [ "Bullet 1", "Bullet 2", "Bullet 3" ],
    "water_incident": null
  },
  "inglewood": { ... },
  ...
}
```

`narrative` is filled by the skill in Step 4 (AI-drafted). `raw_input` is the unmodified source for traceability.

## hr.labour_relations

```json
"hr": {
  "labour_relations": [
    {
      "community": "Aspen Ridge",
      "date": "2026-04-12",
      "topic": "Grievance — meal break scheduling",
      "status": "In progress",
      "owner": "HR / GM",
      "notes": "Initial meeting held 2026-04-15. Follow-up scheduled."
    }
  ]
}
```

Empty list is valid.

## hr.leadership

```json
"hr": {
  "leadership": [
    {
      "community": "Aspen Ridge",
      "gm_name": "Justine Patricio",
      "gm_status": "Active",
      "slt_filled": true,
      "vacancies": 0,
      "turnover_pct_annualized": 14.2
    }
  ]
}
```

One row per community.

## occupancy.communities

```json
"occupancy": {
  "communities": [
    {
      "community": "Aspen Ridge",
      "total_suites": 124,
      "by_care_level": {
        "AL": { "count": 60, "occ_pct": 96.0 },
        "MC": { "count": 24, "occ_pct": 100.0 },
        "IL": { "count": 40, "occ_pct": 92.5 },
        "SL_Funded": { "count": 0, "occ_pct": null }
      },
      "budget_occ_pct": 95.0,
      "actual_occ_pct": 95.6,
      "variance_pct": 0.6,
      "trailing_1mo_pct": 95.1,
      "trailing_3mo_pct": 94.8,
      "trailing_12mo_pct": 93.2,
      "net_future_activity": "+3 net moves projected"
    }
  ]
}
```

## vacancy

```json
"vacancy": [
  {
    "community": "Aspen Ridge",
    "total_suites": 124,
    "vacant": 6,
    "studio": 1,
    "one_bed": 3,
    "one_bed_den": 1,
    "two_bed": 1
  }
]
```

## futures

```json
"futures": {
  "by_community_and_month": {
    "aspen_ridge": {
      "2026-05": 4,
      "2026-06": 2,
      "2026-07": 1
    }
  },
  "by_community_total": {
    "aspen_ridge": 7,
    "inglewood": 5,
    ...
  },
  "portfolio_total": 23
}
```

## projections

```json
"projections": [
  {
    "community": "Aspen Ridge",
    "current_period": { "occ_pct": 95.6, "suite_count": 118 },
    "month_plus_1": { "occ_pct": 96.2, "suite_count": 119 },
    "month_plus_2": { "occ_pct": 96.8, "suite_count": 120 },
    "month_plus_3": { "occ_pct": 97.0, "suite_count": 120 }
  }
]
```

## sales

```json
"sales": {
  "current_month": [
    {
      "community": "Aspen Ridge",
      "leads": 18,
      "tours": 9,
      "move_ins": 3,
      "move_outs": 2,
      "pmi_pct": 16.7
    }
  ],
  "trailing_3_months": [ ... ],
  "previous_3_months": [ ... ]
}
```

## marketing

```json
"marketing": {
  "creative": [
    { "path": "/uploads/welltower-2026-04/09_marketing_creative/aspen-ridge_passports-to-paradise_facebook.png", "community": "Aspen Ridge", "campaign": "Passports to Paradise", "format": "Facebook" }
  ],
  "initiatives": {
    "raw_input": "...source markdown verbatim...",
    "narrative": "AI-rewritten initiatives paragraph in Optima register.",
    "tactical_bullets": [ "Bullet 1", "Bullet 2", "Bullet 3" ]
  },
  "metrics": {
    "by_community": [
      {
        "community": "Aspen Ridge",
        "leads": 18,
        "by_source": { "web": 8, "phone": 4, "walk_in": 3, "referral": 2, "other": 1 }
      }
    ]
  }
}
```

## google_ads

```json
"google_ads": [
  {
    "community": "Aspen Ridge",
    "spend_cad": 1450.00,
    "clicks": 312,
    "leads": 14,
    "cpl_cad": 103.57,
    "conversion_pct": 4.5
  }
]
```

## financials

```json
"financials": {
  "month": {
    "revenue": { "actual": 1234567, "budget": 1230000, "variance": 4567, "variance_pct": 0.4 },
    "salaries_benefits": { ... },
    "operating_expenses": { ... },
    "property_expenses": { ... },
    "noi": { ... }
  },
  "ytd": { ... same shape ... },
  "site_level_month": {
    "aspen_ridge": {
      "revenue": { "actual": ..., "budget": ..., "variance": ... },
      ...
    }
  },
  "site_level_ytd": { ... }
}
```

All financial values in Canadian dollars. Welltower reads in USD analytically but the deck reports in CAD with explicit currency notation on the financial slides.

## capex

```json
"capex": {
  "categories": {
    "maintenance": { "budget": 250000, "ytd_spend": 187000, "items": [ ... ] },
    "improvement": { ... },
    "wt_managed": { ... },
    "opt_managed": { ... }
  },
  "projects": [
    {
      "name": "Boiler replacement — Aspen Ridge",
      "community": "Aspen Ridge",
      "category": "wt_managed",
      "budget": 95000,
      "ytd_spend": 89000,
      "po_status": "PO issued, work in progress",
      "pct_complete": 80,
      "notes": "On track. Completion expected mid-May 2026."
    }
  ]
}
```

## narrative

The skill writes here in Step 4. Every AI-drafted bullet on every slide is captured here for traceability.

```json
"narrative": {
  "operations": {
    "aspen_ridge": [ "AI-drafted bullet 1.", "AI-drafted bullet 2." ]
  },
  "marketing_initiatives_paragraph": "...",
  "marketing_initiatives_tactical": [ ... ],
  "financials_month_commentary": [ ... ],
  "financials_ytd_commentary": [ ... ],
  "capex_highlights": [ ... ]
}
```

## validation

The skill writes here in Step 6. Every check that ran, with pass/fail.

```json
"validation": {
  "foot_and_tie": { "status": "pass", "checks_run": 47, "failures": [] },
  "narrative_data_consistency": { "status": "pass", "checks_run": 12, "failures": [] },
  "excel_companion_tie": { "status": "pass" },
  "no_placeholders": { "status": "pass" },
  "brand_template_fidelity": { "status": "pass", "slide_count": 24, "dimensions": "13.33x7.5", "font": "Arial" }
}
```
