carta-fetch-budget

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]

# Fetch Carta budget

Pulls the budget for a management company directly from Carta via the
`fa:list:budgets` MCP command and lays it out as a single budget tab in
Excel. Only **management companies** carry budgets in Carta — funds and
SPVs do not — so the entity picker always lists the ManCo first.

## UX Rules

Inlined here because the Carta CLI session-start hook does not run inside
Claude for Excel. Audience is an accountant.

- **Plain English only.** Never surface MCP server identifiers, command
  names (`fa:list:budgets`), UUIDs, raw JSON, or gate labels.
- **Currency formatting:** positive `$X,XXX`, negatives `($X,XXX)`, totals
  bolded `**$X,XXX**`. Always `$`. The `[$$-en-US]` locale token in the workbook locks the display
  to USD regardless of the user's Excel locale.
- **Closing summary link** is a workbook citation
  (`<citation:Sheet!Range>`) in Claude for Excel mode, and a `file://`
  path in Claude Code / Cowork mode. Never both.
- **Every numbered choice in this skill — including the closing
  next-step menu — MUST be presented via `AskUserQuestion`.** Never
  render the options as a bare code-fenced markdown list. The
  `AskUserQuestion` tool is in `allowed-tools`; use it.

## When to use

Trigger this skill when the user asks for any of the following:

- "Pull `<ManCo>`'s `<year>` budget from Carta"
- "Fetch the budget for `<ManCo>` from Carta MCP"
- "Import our 2026 budget"
- "Sync the ManCo budget"
- "Bring Carta's budget into this sheet"
- Any request to get the *Carta-stored* budget into a workbook

## DO NOT use this skill for

- **Building a new budget from prior-year actuals** — use `carta-create-budget`.
- **Refreshing actuals against an existing budget** — use `carta-budget-actuals`.
- **Pacing / variance / "are we on track"** — use `carta-budget-vs-actuals`.
- **What-if scenarios** — use `carta-budget-scenarios`.
- **P&L / income statement** — use `carta-consolidating-pnl`. (If the user is
  building a P&L and wants the Budget columns filled with Carta data,
  `carta-consolidating-pnl` already integrates this skill's fetch logic in its
  Gate 9 — do not duplicate the workflow.)

---

## Gate 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": "<firm>"})` → disambiguate via `AskUserQuestion` if multiple → `set_context(firm_id=<uuid>)`. Prefer granular tools when exposed.

**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 Gate 2.

---

## Gate 0.5 — Detect runtime

This skill runs in **two runtimes**. Detect which one applies before
asking where to write:

1. **Claude for Excel** — the user is working inside the Excel add-in.
   Cell reads and writes happen through the add-in's runtime-injected
   workbook tools.
2. **Claude Code / Cowork (local file)** — the user is working at the
   command line or in Cowork against `.xlsx` files on disk.

See `carta-create-budget/SKILL.md` Gate 0.5 for the heuristic. If unclear, ask
via `AskUserQuestion`. Store `<RUNTIME>` (`excel-addin` or `local-file`).

---

## Gate 1 — Where to write

Branches by `<RUNTIME>`. Before showing any chooser, **scan the
destination for an existing budget tab** — if one is found, lead with
"update in place" instead of defaulting to a new tab.

### Budget-tab detection heuristic

A sheet counts as an "existing budget tab" when **either** is true:

1. The sheet name contains `Budget` (case-insensitive), e.g.
   `Budget FY2026`, `2026 Budget`, `MgmtCo Budget`.
2. The sheet's header block contains the word `Account` in a label
   column AND at least 6 month-like headers (`Jan`, `Jan 2026`,
   `2026-01`, etc.) in the same row.

Stop at the first match — the user can always pick another tab via the
"choose a different tab" branch.

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

1. Use the add-in's workbook-introspection tool to list sheet names + the
   first ~10 rows of each.
2. Apply the heuristic. Store any matches as `<EXISTING_BUDGET_TABS>`.

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

Only scan if the user already supplied a workbook path in their prompt
(otherwise there's nothing to scan yet — defer detection to the file
they pick next).

```bash
uv run "${CLAUDE_PLUGIN_ROOT}/scripts/read_workbook.py" \
  "<PATH>"
```

Apply the same heuristic to the JSON output.

### Chooser

**If `<EXISTING_BUDGET_TABS>` is non-empty (excel-addin or local-file with a path):**

Use `AskUserQuestion`:

> I see a budget tab already in your workbook
> (**`<existing tab name>`**). Want me to update it with Carta's data,
> or write the budget somewhere else?

| # | Option | What happens |
|---|---|---|
| 1 | **Update `<existing tab name>` in place** ← recommended | Refreshes the budget values on the existing tab — same accounts, same row positions; **no new tab is created**. |
| 2 | **Add a new tab** | Creates `Budget FY<year>` alongside the existing tab. |
| 3 | **Pick a different existing tab to update** | Lists all sheets in the workbook and asks which one. |
| 4 | **Cancel** | Stops the skill. |

If multiple existing budget tabs are found, list up to 3 of them as
option 1a / 1b / 1c (inside the same `AskUserQuestion` call) — never
silently pick one.

**Update-in-place semantics** (option 1):

- Read the existing tab via the runtime's read tool. Identify the
  label column (the column that holds account names) and the month
  columns. Treat any cell where `is_formula: true` as **load-bearing**
  — subtotal / Net Operating Income / FY-total rows stay formula-driven
  and are **never overwritten**.
- For each matched (`gl_code` or `account_name`) row already in the
  sheet, write the new monthly budget values into the existing month
  cells. The tab's row positions, section headers, formulas, and
  formatting all stay put.
- For Carta budget rows that don't match any existing row in the sheet,
  surface them in the pre-build review (Gate 5) — let the user decide
  whether to insert new rows or skip. **Never silently insert** into an
  existing budget tab without confirmation.
- Refresh the source note in **B3** (italic) to
  `Source: Carta Fund Admin (refreshed <ISO date>)` so the user can see
  when the values were last pulled.

**If `<EXISTING_BUDGET_TABS>` is empty:**

**Excel add-in runtime — 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 `Budget FY<year>`."* — then proceed. The chooser only exists to protect non-empty state.

Otherwise, use `AskUserQuestion` with the default options:

**Excel add-in runtime:**

> Where should I put the Carta budget?

- **"Add a new tab to the open workbook (recommended)"** — Claude creates a tab named `Budget FY<year>`.
- **"Overwrite an existing tab in the open workbook"** — Claude asks which tab and confirms before overwriting. (Used when the user knows there's a budget tab but the heuristic missed it.)
- **"Create a brand new workbook"** — Claude writes to a fresh file.

**Local-file runtime:**

> Where should I write the budget file?

- **"Crea