carta-create-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]

# Create budget

Entry point for building a new budget. The skill routes to one of four
references in `references/` based on user intent.

## 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, DWH column
  names (`ACCOUNT_TYPE`, `EFFECTIVE_DATE`), UUIDs, raw JSON, SQL, or gate labels.
- **Currency formatting:** positive `X,XXX`, negatives `(X,XXX)`, totals bolded — using the resolved currency's symbol, not always `$` (derive the currency from the data, never default to USD; see Hard rules).
- **Difference values are absolute** — e.g. `0` for a match, `2,000` for a gap, in the resolved currency.
- **Status vocabulary:** ✅ Match | ⚠ Mismatch ($X diff) | ❌ Missing in Carta | ❌ Missing in Client Doc.
- **No environment URLs.** Output goes into Excel cells, not Carta dashboard links.
- **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. Bare-text
  menus render inline in Claude for Excel, which breaks the chooser UI
  and forces the user to type the number.

## When to use

Build / create / generate / draft a budget for a future year ("build a 2026 budget", "draft from last year's actuals", "make me a 2026 budget for `<entity>`").

Also covers **restructuring an existing budget** in the workbook:

- "Group / organize / categorize the budget line items into a few top-level categories" → `references/reorganize-categories.md`
- "Add a 5% inflation buffer to expenses" / "apply a contingency buffer" / "pad the budget by X%" → `references/inflation-buffer.md`

## DO NOT use this skill for

- Refreshing actuals on existing budget → `carta-budget-actuals`
- Pacing / variance / on-track → `carta-budget-vs-actuals`
- What-if scenarios → `carta-budget-scenarios`
- P&L / income statement → `carta-consolidating-pnl`
- Balance sheet → `carta-consolidating-balance-sheet`

---

## Execution discipline

Execute all gates silently. Do not narrate tool calls, intermediate results, or status updates. Only speak at explicit decision points: Gate 0.5 (if runtime is ambiguous), Gate 1 (destination chooser), Gate 2 (parameter gate), Gate 5 (approval), and Gate 7 (next-step menu).

Do NOT output any of the following between gates:
- "Let me probe the server prefix…" / "Good — prefix is `carta_sandbox`."
- "Now running the DWH queries." / "Queries complete."
- "Approved. Writing now." / "Both tabs branded."
- Any sentence that narrates a tool call you are about to make or just made.

---

## Entry mode — fresh session vs. chained skill

Before Gate 0, check whether these context variables are already set from an earlier budgeting skill call in the same session:

- `<SERVER>` — connected Carta MCP server prefix
- `<ENTITY_NAME>` — the resolved entity name
- `<ENTITY_UUID>` — the resolved entity UUID
- `<RUNTIME>` — `excel-addin` or `local-file`

**If all four are in context:** skip Gates 0 and 0.5 entirely. In Gate 2, pre-fill the entity and skip asking for it — ask only for `budget_year`, window, and other budget parameters. Proceed from Gate 1.

**If any is missing** (fresh session or cold invocation): run Gates 0 and 0.5 in order, then continue from Gate 1.

Do not ask "which firm?" or "which runtime?" when those are already established from the skill the user just ran.

---

## Gate 0 — Carta MCP environment + resolve firm

### Detect the Carta MCP server

1. Call `refresh_mcp_connectors` (no params). It returns `servers[]` with `name` and `status`.
2. Filter to entries whose `name` is `Carta`, starts with `Carta (`, or equals `carta`. Drop `failed` entries (need re-auth at claude.ai → Settings → Connectors).
3. For each `connected` candidate, probe both prefix forms in parallel (one message, both calls): `mcp__claude_ai_Carta__welcome` and `mcp__carta__welcome`. Whichever returns first is `<SERVER>`.

`<SERVER>` is resolved only after `welcome` returns successfully. **Do not call any other `mcp__<SERVER>__*` tool before `welcome` — every other command is gated behind it and will return a reminder instead of executing. This means `list_contexts`, `set_context`, and all DWH commands must be in a separate message that comes after `welcome` returns — never in the same parallel message.**

**If no Carta server is connected:** tell the user, list `failed` connectors, stop. **If multiple connected:** default to `Carta` (production). **Don't** probe every prefix in `allowed-tools` — only `connected` ones. **Never** use `tool_search_tool_bm25` to find the server prefix — it is not in `allowed-tools` and bypasses the `connected`-only filter. Determine the prefix solely from the `refresh_mcp_connectors` result.

### Resolve the firm/entity

The Carta MCP exposes three top-level tools: `welcome`, `fetch`, `set_context`. List contexts via `fetch(command="contexts:list", …)` — never a direct `list_contexts` top-level tool.

If the user named a firm:
1. `fetch(command="contexts:list", params={"firm_name": "<entity>"})`.
2. Multiple matches → `AskUserQuestion` to disambiguate.
3. `set_context(firm_id=<uuid>)`. **Do not skip this step — DWH queries scope to the active context. Proceeding without `set_context` means queries may return data for the wrong entity.**

Prefer granular tools when exposed: `mcp__<SERVER>__list_contexts(firm_name=...)` / `set_context(firm_id=...)`.

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

If no firm was named, defer to Gate 2.

---

## Gate 0.5 — Detect runtime

Set `<RUNTIME>`:
- **`excel-addin`** — references to "this workbook" / "the open spreadsheet" / open tab without a file path.
- **`local-file`** — user supplied a file path (`~/Downloads/Budget.xlsx`) or asked to "create a new file" / "write to disk".
- If unclear, ask via `AskUserQuestion`: *"Are you working in Excel via Claude for Excel, or with a local .xlsx (Claude Code / Cowork)?"*

---

## Gate 1 — Where to write

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

Otherwise, use `AskUserQuestion`:

> Where should I put the new budget?

- **"Update the open workbook — new tab (recommended)"** — Claude creates a tab named `Budget <year>`.
- **"Update the open workbook — overwrite an existing tab"** — Claude asks which tab and confirms before overwriting.
- **"Create a brand new workbook"** — Claude writes to a fresh file.

If the user has no workbook open at all, default to "brand new workbook" without asking.

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

Use `AskUserQuestion`:

> Where should I write the budget file?

- **"Create a new .xlsx (recommended)"** — ask for the destination path and folder.
- **"Modify an existing .xlsx"** — ask for the file path; the skill will add a new sheet inside it (default name `Budget <year>`).

If the user gave a path in the original prompt, skip the choice and use that path.

**Done when:** the write destination is locked. Store `<DESTINATION>`
(open workbook + tab in add-in mode, or `.xlsx` path +