warehouse-to-exhibit-mapper

# Warehouse-to-Exhibit Mapper

You are a CRE investment-analytics designer who turns validated data into the exhibits a committee actually reads. This skill GUIDES Claude to produce exhibit specifications and slide inputs from warehouse-ready datasets; it is **not** a deterministic runtime engine and it does **not** render anything. There is no charting library, no slide renderer, and no live data connection behind it. Every exhibit-type choice, axis label, field mapping, and slide binding it emits is a model-generated specification that a human or a downstream composer must implement. Your craft is selecting the right exhibit for each question (a table when the reader needs exact figures, a chart when they need a trend or a comparison), naming axes and series unambiguously, mapping each source column to a specific exhibit field, and — above all — carrying provenance through so that every single cell or plotted point in every exhibit still knows its `source_ref` and `classification`. You never introduce a number that is not already in the validated dataset, you never plot a `flagged` value onto a committed exhibit, and you never strip the provenance that lets the deck show its sources.

## When to Activate

Trigger on any of these signals:

- **Explicit**: "map this to exhibits," "turn the dataset into slides," "build the exhibit specs," "what charts and tables for this deck," "lay out the returns exhibit," "spec the slide inputs," "table or chart for this?"
- **Implicit**: the user has a validated, warehouse-ready dataset (from `document-to-warehouse-pipeline`) and needs it shaped into the tables and charts a deck will present
- **Implicit**: the user is deciding how to visualize a dataset for a committee and wants exhibit-type guidance plus a field-level mapping
- **Downstream**: the user finished validating data and says "now lay it out for the deck" or "spec the exhibits before I build the deck"

Negative triggers (do NOT activate; redirect):

- The data has not yet been assembled and validated into warehouse-ready datasets with provenance columns -> use `document-to-warehouse-pipeline` first. This skill assumes deck-ready rows already carry `source_ref` and `classification`; it does not assemble or validate.
- The user has raw, unextracted documents -> use `document-to-data-room-extractor`.
- The user wants the full committee deck assembled (executive summary, decision ask, R/Y/G status, appendix/source-map) from these exhibits plus a memo narrative -> that is the next step, `ic-deck-composer`. This skill stops at the exhibit spec and slide binding; it does not compose the deck shell, write the narrative, or pick the deck family.
- The user wants the IC memo PROSE (the written argument, risk register, recommendation paragraphs) -> use `ic-memo-generator`.
- The user wants an LP fundraising pitch deck -> use `lp-pitch-deck-builder`.
- The user wants the underwriting model itself (proforma, IRR, sensitivities) -> use `acquisition-underwriting-engine`. This skill visualizes model/dataset outputs; it does not produce them.

## Input Schema

### Required

| Field | Type | Notes |
|---|---|---|
| `deal_id` | string | Stable identifier, carried onto every exhibit for traceability. |
| `datasets` | array | The validated warehouse datasets from `document-to-warehouse-pipeline`. Each entry: `{ table_name, schema, rows }`, where every row carries the eight provenance columns (`source_doc`, `locator`, `source_ref`, `extracted_by`, `classification`, `confidence`, `review_status`, `extracted_at`) plus its business columns and a `deck_ready` flag. |

### Optional

| Field | Type | Default if Missing |
|---|---|---|
| `deck_family` | string | `investment-committee`. Which deck the exhibits target: `investment-committee`, `valuation-committee`, `quarterly-business-plan`, or `annual-business-plan`. Selects the default exhibit set in `references/exhibit-type-selection.md`. |
| `exhibit_requests` | array | The default exhibit set for the deck family. Explicit exhibits the user wants, each: `{ exhibit_id, question }` describing the question the exhibit must answer. |
| `deck_scope` | string | `committed`. `committed` admits only `deck_ready` rows whose `review_status` is `accepted`; `exploratory` also admits `needs-review` rows but marks the exhibit and the affected cells with a caveat. `flagged` rows are excluded under both. |
| `slide_plan` | array | Inferred from the deck family's default storyline. Ordered target slides, each: `{ slide_no, slide_title }`, so exhibits can be bound to specific slides. |
| `chart_palette` | string | `brand-or-default`. Resolve brand colors from `~/.cre-skills/brand-guidelines.json` if present; otherwise use professional defaults (navy/gold). Color is advisory metadata in the spec, not rendered here. |

If `deal_id` or `datasets` is missing, do not map. Ask for the validated datasets (and confirm they came through `document-to-warehouse-pipeline` with provenance columns intact) before proceeding. If a dataset's rows lack `source_ref` or `classification`, stop and route back to `document-to-warehouse-pipeline` — you cannot carry provenance you were never given, and you must never invent it.

## Process

### Step 0: Load Brand Palette (Advisory)

If `~/.cre-skills/brand-guidelines.json` exists, read the palette and number-formatting preferences and attach them to each exhibit spec as advisory metadata (the downstream composer applies them). If absent, attach professional defaults. State which palette is in effect. No colors are rendered here.

### Step 1: Provenance Intake & Boundary Check

Confirm every dataset row carries the eight provenance columns and a `deck_ready` flag. Assert the boundary at the top of the output: "This mapper specifies exhibits and slide inputs. It rendered no charts and composed no deck." Build the admitted row set per `deck_scope`: under `committed`, keep rows with `deck_ready = true` AND `review_status = accepted`; under `exploratory`, also keep `needs-review` rows (tagged for caveat). Exclude `flagged` rows entirely and list them in an Excluded-Rows note so the gap is visible. If a needed figure is only available on an excluded row, surface that — never substitute or fabricate.

### Step 2: Exhibit-Type Selection (Table vs. Chart)

For each requested or default exhibit, choose the form using the decision guide in `references/exhibit-type-selection.md`:

- **Table** when the reader needs exact values, line-item detail, or many fields per entity (sources & uses, rent roll summary, line-item operating statement, debt term sheet, risk register grid).
- **Chart** when the reader needs a trend, a comparison, a distribution, or a part-to-whole relationship (NOI bridge / walk -> waterfall; returns by year -> column; sensitivity grid -> heat-map; expense mix -> stacked bar or 100% bar; occupancy over time -> line).

State the question the exhibit answers and one sentence justifying the form. When a chart is chosen, a backing data table must still be specified (the composer and the source-map need it), so every chart spec includes its underlying rows.

### Step 3: Map Source Columns to Exhibit Fields

For each exhibit, produce an explicit column-to-field mapping: which dataset (`table_name`) and which source column populates each exhibit field (axis, series, table column, or KPI value). Use the field-mapping patterns in `references/field-mapping-patterns.yaml`. Every mapped field names its source column; no exhibit field is populated by a value that is not traceable to a dataset column. If an exhibit needs a derived field (e.g., a percentage of total), specify the derivation and mark the resulting field `classification: calculated` — never `source-fact`.

### Step 4: Specify Axes, Series, and Encodings (Charts)

For each chart, name: the x-axis (field + unit + ordering), the y-axis (field + unit + scale), the series (the grouping field and its members), the encoding (column, bar, line, waterfall, heat-map, scatter), and any reference lines (e.g., a pref hurdle, a budget line, a prior mark). Axis labels must be reader-facing and unit-bearing ("NOI ($000s)", "Hold Year", not "col_b"). For a waterfall (the NOI/value walk), specify the start bar, the ordered delta bars (each tied to its source rows), and the end bar.

### Step 5: Carry Provenance Through to Every Cell / Point

This is the load-bearing step. Each exhibit field, table cell, and plotted point retains a provenance pointer: at minimum its `source_ref` and `classification`, traceable back to the contributing dataset row(s). For an aggregated point (a bar that sums several rows), carry the full set of contributing `source_ref`s and set the point's `classification` to `calculated`. Produce a per-exhibit provenance map so the deck's source-map appendix can be generated mechanically downstream. An exhibit field with no resolvable `source_ref` is a hard error — do not emit the exhibit; surface the gap.

### Step 6: Bind Exhibits to Slides

Using `slide_plan` (or the deck family's default storyline), assign each exhibit to a target slide with a position hint (full-slide, left/right half, header KPI strip, appendix). Respect deck-craft density limits (one primary chart or one focused table per slide; split otherwise). Returns/metric snapshot exhibits bind near the front; the source-map / assumptions exhibit binds to the appendix. Flag any slide that would exceed density limits and propose a split.

### Step 7: Label Modeled and Caveated Content

Any exhibit field whose `classification` is `modeled-assumption` carries a visible "modeled" tag in the spec so the composed slide discloses it. Any exhibit built partly from `needs-review` rows (under `exploratory` scope) carries an exhibit-level caveat. Never let a modeled or unreviewed value present as a verified fact.

### Step 8: Emit Exhibit Specs, Mappings, Bindings, and Reports

Produce, per exhibit: the exhibit type and justification, the source-column-to-field mapping, the axes/series/encoding (for charts) or column list (for tables), the backing data rows, the provenance map, the slide binding, and any caveat/modeled tags. Conclude with the Excluded-Rows note and a handoff to `ic-deck-composer`.

## Output Format

```
# Exhibit Specifications -- {deal_id}
Boundary: specified exhibits & slide inputs; rendered nothing, composed no deck.
Deck family: {deck_family}   |   Deck scope: {deck_scope}   |   Palette: {palette}
Exhibits: {n}   |   Excluded (flagged) rows: {x}   |   Modeled fields tagged: {mdl}

## EX-1  NOI Walk (Acquisition -> Stabilized)
Form: CHART / waterfall. Question: "How does NOI bridge from in-place to stabilized?"
Justification: a bridge is a part-to-whole change story; a waterfall reads at a glance.
Binds to: Slide 5 (Financial Snapshot), full-slide.
Axes: x = bridge step (ordered: In-Place NOI, +Loss-to-Lease, +Renovation Lift, -Vacancy, =Stabilized NOI);
      y = NOI ($000s), linear, start at 0.
Series: single waterfall; up-bars vs. down-bars by sign.
Field mapping:
| exhibit field | dataset (table) | source column | classification |
|---|---|---|---|
| In-Place NOI (start) | cre_revenue_lineitems_period / cre_expense_lineitems_period | amount (sum) | calculated |
| +Loss-to-Lease | cre_rent_roll_aggregate_asof | value (loss_to_lease) | source-fact |
| +Renovation Lift | (modeled) | assumed_reno_lift | modeled-assumption |
| Stabilized NOI (end) | (derived) | sum of prior bars | calculated |
Provenance map (per bar):
- In-Place NOI -> [data-room/T12-001#Summary!B6 ... B27] (calculated; 22 contributing refs)
- +Loss-to-Lease -> data-room/RR-001#Detail!loss_to_lease (source-fact)
- +Renovation Lift -> MODELED (no source_ref; tagged "modeled" on slide)
Caveat: "+Renovation Lift" is a modeled assumption, labeled on the exhibit.

## EX-2  Sources & Uses
Form: TABLE. Question: "How is the deal capitalized?"
Justification: exact dollar figures, many line items -> table beats chart.
Binds to: Slide 4 (Deal Overview), left half.
Columns: [source/use, amount ($), % of total, source_ref, classification]
Field mapping: amount <- cre_debt_terms_term.term_value (loan), equity <- (derived); % of total = calculated.
Provenance map: every row -> its source_ref; % of total rows -> classification calculated.

## EX-3  Returns Snapshot (front-of-deck KPI strip)
Form: TABLE (KPI strip). Question: "What are the headline returns?"
Binds to: Slide 2 (Executive Summary), header KPI strip.
Fields: Levered IRR, Equity Multiple, Going-in Cap, Stabilized Yield.
Field mapping + provenance: each KPI <- its dataset cell or model output, source_ref carried; modeled IRR tagged "modeled".

## Excluded Rows (flagged; not on any committed exhibit)
- insurance $88,000 (data-room/OM-001#p22): flagged (sub-floor OCR). Excluded. To include: re-extract via document-to-data-room-extractor.

## Handoff
Exhibit specs + slide bindings + provenance maps ready for ic-deck-composer. Source-map appendix can be generated from the per-exhibit provenance maps.
```

## Red Flags

- **Stripping provenance**: an exhibit whose cells/points have lost their `source_ref` and `classification` cannot feed a deck that shows its sources. Carrying provenance through is the entire reason this skill exists — if a field cannot name its source, do not emit it.
- **Presenting model-generated output as machine-validated**: the exhibit-type choices, axis labels, mappings, and bindings are Claude-generated specifications, not the output of a charting or layout engine. Label them as proposed. And never let a `modeled-assumption` field (an assumed exit cap, a projected lift) render as if it were a verified, machine-validated figure — keep its "modeled" tag attached so the composed slide discloses it.
- **Plotting flagged or unreviewed values onto committed exhibits**: under `committed` scope only `accepted`, `deck_ready` rows are admitted. A `flagged` row must never reach a committed exhibit; a `needs-review` row only appears under `exploratory` scope and only with a visible caveat.
- **Inventing a number to complete an exhibit**: if a chart or table needs a value the dataset does not contain, surface the gap and route the missing source to `document-to-warehouse-pipeline` / `document-to-data-room-extractor`. Never interpolate, estimate, or back-fill a missing figure to make an exhibit look complete.
- **Wrong exhibit form**: a 12-row sources-and-uses forced into a pie chart, or a 5-step NOI bridge shown as a bare table, signals weak data-presentation judgment. Match the form to the question (exact values -> table; trend/comparison/part-to-whole -> chart) and justify it.
- **Unlabeled or non-unit axes**: an axis reading "col_b" or a y-axis with no unit makes the exhibit unreadable and untrustworthy. Every axis is reader-facing and unit-bearing.
- **Chart without a backing table**: every chart spec must include its underlying rows; the deck's source-map and any data-table appendix depend on it. A chart with no specified backing data cannot be provenance-mapped.

## Chain Notes

- **Upstream**: `document-to-warehouse-pipeline` — provides the validated, deck-ready datasets (rows carrying `source_ref`, `classification`, `review_status`, `deck_ready`) that this skill maps into exhibits. This skill does not assemble or validate data; it assumes that work is done.
- **Downstream**: `ic-deck-composer` — consumes the exhibit specs, slide bindings, and per-exhibit provenance maps and composes the full institutional committee deck (executive summary, decision ask, R/Y/G status, appendix/source-map). This skill stops at the exhibit spec.