carta-budget-actuals

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 menus-and-flows v0.0.7]
[PATTERN base v0.1.0]

# Budget actuals

Entry point for updating actuals in an existing budget. Six references:

- [`references/add-actuals-columns.md`](references/add-actuals-columns.md) — **Layout A**: interleave Budget / Actual / Variance per month on the Budget tab (recommended for active tracking).
- [`references/add-actuals-tab.md`](references/add-actuals-tab.md) — **Layout B**: add a peer `<year> Actuals` tab alongside the Budget tab.
- [`references/refresh-existing.md`](references/refresh-existing.md) — **Layout C**: overwrite stale actuals cells in columns that already exist.
- [`references/add-period.md`](references/add-period.md) — **Layout D**: append the single next month/quarter column.
- [`references/tag-view.md`](references/tag-view.md) — **Layout E**: new tab with actuals sliced by reporting dimension (department, project code, class, etc.) and a two-row period / tag header. Only offered when the entity has tagged journal data.
- [`references/get-actuals.md`](references/get-actuals.md) — internal helper, the canonical actuals-query routine.

## UX Rules

Audience is an accountant in Excel. Plain English only. Never surface MCP
identifiers, DWH column names, UUIDs, raw JSON, SQL, or gate 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

- "Refresh the actuals on my budget"
- "Pull the latest actuals into the open budget"
- "Update my budget with March numbers"
- "The actuals are stale — sync them"
- "Add next month's column to the budget"
- "Extend the budget through April"

## DO NOT use this skill for

- **Building a new budget from scratch** — use `carta-create-budget`.
- **Pulling the Carta-stored ManCo budget** — use `carta-fetch-budget`.
- **Pacing / YTD vs budget / variance / "are we on track"** — use `carta-budget-vs-actuals`.
- **What-if scenarios** — use `carta-budget-scenarios`.
- **P&L / income statement requests** — use `carta-consolidating-pnl`.
- **Balance sheet requests** — use `carta-consolidating-balance-sheet`.

---

## 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": "<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 Gate 3.

---

## Gate 0.5 — Detect runtime

Detect whether this is **Claude for Excel** (workbook is open in the
add-in) or **Claude Code / Cowork** (working with a `.xlsx` file on
disk). See `carta-create-budget/SKILL.md` Gate 0.5 for the heuristic — same
rule applies here.

If unclear, ask the user via `AskUserQuestion`:

> "How are you working with the budget — inside Excel via Claude for
> Excel, or as a local .xlsx file (Claude Code / Cowork)?"

Store `<RUNTIME>` (`excel-addin` or `local-file`) for Gates 1, 4, 7, 8.

---

## 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 `<TARGET_TAB>`."* — then proceed. The chooser only exists to protect non-empty state; an empty workbook has none. The chooser still applies whenever there is data or more than one tab.

> Where should I write the updates?

- **"Update the open workbook directly — recommended"** (modify in place).
- **"Update the open workbook in a new tab"** (preserves the original).
- **"Create a brand new workbook with the updated data"**.

If user picks "update directly", confirm **which tab** explicitly. If
multiple tabs look like budgets, ask which one.

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

> Where is the budget file, and where should the updated version land?

- **"Modify the file in place — recommended"** — ask for the path.
- **"Write a new file alongside the original"** — ask for the path; new file gets a `-updated` suffix by default.

If the user gave a path in the original prompt, skip the choice. Store
`<DESTINATION>` (open workbook + tab in add-in mode, or `.xlsx` path +
sheet name in local-file mode).

---

## Gate 2 — Choose the layout (always ask)

Four layouts are valid for putting actuals into a workbook, and the
same prompt can plausibly mean any of them. **Always ask the user**
how the actuals should appear — never assume from the prompt's
phrasing alone.

Use `AskUserQuestion`:

> How should the actuals appear in the workbook?

| # | Option | Reference loaded |
|---|---|---|
| 1 | **Interleave Budget / Actual / Variance columns per month** on the Budget tab ← recommended | [`add-actuals-columns.md`](references/add-actuals-columns.md) |
| 2 | **Add a separate `<year> Actuals` tab** alongside the Budget tab | [`add-actuals-tab.md`](references/add-actuals-tab.md) |
| 3 | **Refresh existing Budget / Actual / Variance cells** (the cells are there, just stale) | [`refresh-existing.md`](references/refresh-existing.md) |
| 4 | **Add only the next single period column** | [`add-period.md`](references/add-period.md) |
| 5 | **Build a tag-view tab — actuals sliced by reporting dimension** (department, project code, class, etc.) | [`tag-view.md`](references/tag-view.md) — only offered when the entity has tagged data; see Gate 2.5 |

Use the user's prompt only as a *hint* for which option to highlight —
never as authority to skip the question:

| Phrase in the prompt | Hint |
|---|---|
| "interleave", "Budget / Actual / Variance", "variance by month", "add `<year>` actuals" (no other clue) | Option 1 (also the default `← recommended`) |
| "add a tab", "track on its own tab", "separate actuals tab" | Option 2 |
| "refresh", "the actuals are stale", "pull latest", "sync" | Option 3 |
| "add next month", "extend through `<month>`", "next period" | Option 4 |
| "by department", "by tag", "by cost center", "split by", "broken down by", "by reporting tag", "by project code" | Option 5 |

**Option 5 availability**: always show Layout E in the chooser. If the user
picks it and Gate 2.5 finds no tag data on the entity, tell them in one sentence
and fall back to Layout A automatically. Do not pre-filter the chooser — the
entity name needed for the probe is not available until Gate 3.

The user's pick locks the reference to load for the rest of the
workflow. **Immediately call `read_skill` for the chosen layout — do not reconstruct from memory:**

| Layout chosen | Call |
|---|---|
| Option 1 — Interleave columns |