carta-budget-scenarios

What this skill does

[PATTERN carta-writing-style v0.0.2]
[PATTERN etiquette v0.0.6]
[PATTERN text v0.0.8]
[PATTERN tables v0.0.12]
[PATTERN carta-watermark v0.0.10]
[PATTERN base v0.1.0]

# Budget scenarios

What-if modelling on top of an existing budget. Five scenario references grouped into trim and growth, plus a shared helper:

**Trim:**

- [`references/headcount-reduction.md`](references/headcount-reduction.md) — reduce headcount by a target %.
- [`references/revenue-shock.md`](references/revenue-shock.md) — apply a haircut to revenue.
- [`references/cost-rebalance.md`](references/cost-rebalance.md) — open-ended, user states a cash goal.

**Growth:**

- [`references/new-fund-raise.md`](references/new-fund-raise.md) — model fee revenue uplift from closing a new fund.
- [`references/expansion-hire.md`](references/expansion-hire.md) — add N new FTEs at a stated comp band.

**Shared helper** (used by Step 4):

- [`references/get-actuals.md`](references/get-actuals.md) — canonical YTD-actuals query, so scenarios are grounded in real spend rather than just budget assumptions.

Growth references can stack with each other when the user mentions multiple
levers in one prompt (e.g. "raise a $500M fund AND hire 5 FTEs") — see the
"Stacking" section in each growth reference.

## UX Rules

Audience is an accountant in Excel. Plain English only. Never surface MCP
identifiers, DWH column names, UUIDs, raw JSON, SQL, or step labels.
Currency: `$X,XXX` positive, `($X,XXX)` negative, totals bolded.
Differences are absolute. Status: ✅ Match | ⚠ Mismatch ($X diff) | ❌ Missing in Carta | ❌ Missing in Client Doc.

**Closing summary link** is a workbook citation (`<citation:Sheet!Range>`) in
Claude for Excel mode, and a `file://` path in Claude Code / Cowork mode.

**Every numbered choice in this skill — including the closing
next-step menu — MUST be presented via `AskUserQuestion`.** Never
render options as a bare code-fenced markdown list. The
`AskUserQuestion` tool is in `allowed-tools`; use it. Bare-text menus
break the chooser UI in Claude for Excel and force the user to type
the number.

## When to use

Trim:

- "What if we cut headcount 10%?"
- "Model a 15% revenue shortfall"
- "Show me 3 trim options"
- "Propose 3 ways to preserve $500k of cash"
- "Compare two budget scenarios"
- "What happens if travel doubles?"

Growth:

- "What if we raise a new $500M fund?"
- "Model the P&L impact of Fund V closing in Q1"
- "Show revenue uplift from a $300M / $500M / $750M close"
- "Model hiring 5 FTEs in 2027"
- "Compare a 3 / 5 / 7 hire ramp"
- "How does next year's P&L look if we raise a new fund AND hire 5 FTEs?"

## DO NOT use this skill for

- **Building a new budget** — use `carta-create-budget`.
- **Refreshing actuals on an existing budget** — use `carta-budget-actuals`.
- **Pacing / variance / "how are we doing"** — use `carta-budget-vs-actuals`.
- **P&L / income statement requests** — use `carta-consolidating-pnl`.

---

## Step 0 — Carta MCP environment + resolve firm

1. Call `refresh_mcp_connectors`. Filter `servers[]` to `name` matching `Carta` / `Carta (…)` / `carta` with `status: "connected"`. Drop `failed`.
2. For each connected, probe both prefix forms in parallel: `mcp__claude_ai_Carta__welcome` and `mcp__carta__welcome`. First success = `<SERVER>`.
3. **Don't call any other `mcp__<SERVER>__*` tool before `welcome`** — every command is gated.

If none connected, list `failed` connectors and stop. If multiple, default to `Carta` (production).

**Resolve firm:** if user named one → `fetch(command="contexts:list", params={"firm_name": "<entity>"})` → disambiguate via `AskUserQuestion` if multiple → `set_context(firm_id=<uuid>)`.

**DWH param-name traps:** `dwh:execute:query` takes `sql:` not `query:`. `dwh:get:table_schema` takes `table_name:` not `table:`. `format` accepts `"ndjson"` / `"markdown"`, not `"csv"`.

If no firm was named, defer to Step 3.

## Step 0.5 — Detect runtime

Set `<RUNTIME>` to `excel-addin` (open workbook) or `local-file` (user-supplied path). If unclear, ask via `AskUserQuestion`.

## Step 1 — Where should the scenarios live

Branches by `<RUNTIME>`.

**If `<RUNTIME>` is `excel-addin`:**

**Empty-workbook shortcut**: if the active workbook has one sheet, `maxRows == 0`, no other tabs (typically a fresh `Book1.xlsx`/`Sheet1`), skip the chooser. Announce the rename in one sentence — *"I'll use the empty workbook you have open and rename `Sheet1` to `Scenarios`."* — then proceed. The chooser only exists to protect non-empty state.

> Where should the scenarios live?

- **"Add scenario columns next to the existing budget"** (recommended for ≤3 scenarios).
- **"Create a new `Scenarios` tab"** (recommended for >3 scenarios or wide pivots).
- **"Clone the workbook — leave the original untouched"**.

**If `<RUNTIME>` is `local-file`:**

> Where should the scenarios live?

- **"Add a `Scenarios` sheet to the same file"** (recommended).
- **"Write a separate `<budget>-scenarios.xlsx` file alongside the original"** (preserves the original).

Store `<DESTINATION>` (open workbook + tab in add-in mode, or `.xlsx`
path + sheet name in local-file mode).

## Step 2 — Intent routing

| Phrase | Reference |
|---|---|
| "cut headcount", "reduce salaries", "team reduction", "trim staffing", "headcount X%" | [`headcount-reduction.md`](references/headcount-reduction.md) |
| "revenue shortfall", "revenue haircut", "if revenue drops", "demand shock" | [`revenue-shock.md`](references/revenue-shock.md) |
| "preserve $X cash", "hit a cash target", "free up cash", "propose ways to reduce spend" | [`cost-rebalance.md`](references/cost-rebalance.md) |
| "raise a new fund", "Fund <N> closing", "new fund raise", "AUM uplift", "management fee impact of a new fund" | [`new-fund-raise.md`](references/new-fund-raise.md) |
| "hire N FTEs", "add headcount", "expand the team", "hire ramp", "model new hires" | [`expansion-hire.md`](references/expansion-hire.md) |

**Multi-lever prompts.** If the user names more than one of the above in a
single prompt (e.g. "raise a $500M fund AND hire 5 FTEs"), route to every
matching reference. Combine their outputs into composed scenarios — each
scenario column reflects the joint effect of all selected levers, and the
cash-impact summary breaks out each leg (e.g. `New-Fund Fees`, `New Personnel`,
`Net`). Do NOT run the references serially as separate outputs.

**Immediately call `read_skill` for every matched reference — do not reconstruct scenario logic from memory:**

| Reference matched | Call |
|---|---|
| headcount-reduction | `read_skill(file_path="references/headcount-reduction.md")` |
| revenue-shock | `read_skill(file_path="references/revenue-shock.md")` |
| cost-rebalance | `read_skill(file_path="references/cost-rebalance.md")` |
| new-fund-raise | `read_skill(file_path="references/new-fund-raise.md")` |
| expansion-hire | `read_skill(file_path="references/expansion-hire.md")` |

## Step 3 — Parameter gate (batched)

Reference-specific. Generally include:

- **Number of scenarios** (default 3).
- **Target %** or **target dollar amount**.
- **Scope** — all lines vs a section (e.g. only Personnel, only Operating Expenses).
- **Distribution rule** when applicable (across-the-board, junior-heavy, senior-heavy, etc.).

## Step 4 — Read the base budget + YTD actuals

**If `<RUNTIME>` is `excel-addin`:** use the add-in's read tools.

**If `<RUNTIME>` is `local-file`:**

```bash
uv run "${CLAUDE_PLUGIN_ROOT}/scripts/read_workbook.py" \
  "<BUDGET_PATH>" --sheet "<BUDGET_SHEET>"
```

Pull YTD actuals via
[`references/get-actuals.md`](references/get-actuals.md)
so scenarios are grounded in real spend rather than just budget
assumptions.

The helper runs the **ManCo pre-flight sanity check**. **Halt** if it fails.

**Always render the pre-flight outcome as user-visible prose, even when the dataset is clean.** The context engine may compress the underlying tool call into a snip summary, which means the user has no visibility into whether this safety gate