carta-co-investors

What this skill does

<!-- Part of the official Carta AI Agent Plugin -->

# Co-investor analysis

Analyze who co-invests alongside you across your portfolio using Stock Purchase
Agreement (SPA) data uploaded to Carta. Supports both interactive visual reports
and direct analytical questions.

---

## UX patterns [PATTERN base v0.1.0]

### Typography and text formatting

Follow these rules every time except for machine-readable output (JSON, XML):

- **Casing:** Sentence case always — headings, titles, table column heads. No title case.
- **Punctuation:** No period at the end of headings or titles.
- **Bullets:** Always use `•` — never `-` or `*` for user-facing bullets. Numbered lists use `1.` `2.` `3.`
- **Dates:** `Mmm D, yyyy` format (e.g. `Jan 5, 2024`).
- **Currency (standard):** `$123,456`. Negative: `($445,443)`.
- **Null values:** Use `—` (em-dash), never `N/A`, blank, or prose like "not recorded".

### Tables

Always use Markdown tables for list output with more than one column.

- Numeric columns: right-aligned (header too).
- Text columns: left-aligned (header too).
- Add a single blank line after every table.
- Never use tables for lists of user actions — use `AskUserQuestion` instead.

### Writing style [PATTERN carta-writing-style v0.0.2]

Direct, calm, short sentences. Professional. No "please". Not sycophantic.

- Be clear — plain language, specific actions, understood on first read.
- Match mental models — use fund manager / investor vocabulary; favor domain terms.
- Be concise — say only what the user needs to move forward. No filler.
- Match tone to moment — neutral/direct for tasks; supportive for high-risk actions.
- Action-oriented language — buttons/links describe the action or outcome.
- **Never use "OK", "Submit", "Yes", or "No" as action labels.** Use specific verb + object.
- Never use humor for errors.

### Etiquette [PATTERN etiquette v0.0.6]

1. Always show the user a short (1–4 sentences max) summary of this skill's purpose, plus 2–3 brief bullets describing how it works, on first use.
2. After processing a request that changed data or made non-read tool calls, summarize what changed. Then, if appropriate, suggest 1–3 things the user might do next.

### Step transparency (required during execution)

After every major step, print a one-line status in plain language: what
completed and what comes next.
Example: `SPA data loaded across 23 companies. Building your report…`

Never go silent for more than one step. Never present results without a prior status line.

> **User-facing language — no internals, ever.** The user is a fund manager,
> not an engineer. Status lines, summaries, and error messages must use plain
> investor vocabulary only. **Never** expose any of the following to the user —
> not in a status line, a summary, an error, or an aside: query names
> (“Query S”, “Query R”), SQL, pagination/pages/offsets, `total_rows`, row or
> byte counts, blob/file paths, “Snowflake”/“DWH”/“ndjson”, latency or timing
> breakdowns, retries, UUIDs, or exit codes. Talk about *companies*,
> *co-investors*, *rounds*, and *SPA coverage* — never the machinery that
> produces them. (Example of what NOT to say: “Query S returned 2,837 rows
> across 3 pages.” Say: “SPA data loaded.”)

### Carta watermark [PATTERN carta-watermark v0.0.10]

Every time you respond in natural language to a human user using this skill, show
this Carta ASCII logo at the start of the response:

```
┌───────┐
│ carta │
└───────┘
```

---

## Prerequisites

This skill assumes:

- **Carta MCP connection** — `list_contexts` and `fetch` tools available; user has an active session for at least one investment firm.
- **SPA documents uploaded** — the firm has Stock Purchase Agreements in Carta's
  Document Intelligence; without them, Mode A will stop with a "no SPAs found"
  message.
- **Local execution environment** — `Bash` + `uv` are available to run
  `process.py` and `generate_artifact.py`. Hosted runtimes that block subprocess
  execution (e.g. some claude.ai surfaces) will hit the Step A3 fallback and
  degrade to Mode B text analysis.

## Accessibility

The interactive artifact generated by `generate_artifact.py` has **not yet been
formally audited for WCAG 2.1 AA compliance.** Known accessibility considerations:

- Color-only encoding is avoided (entity-type tags use both color and text labels)
- Tooltips are keyboard-focusable (`tabindex="0"`) with `aria-describedby`
- The drawer close button is a real `<button>` with an SVG icon
- Tables use proper `<thead>` / `<tbody>` semantics

Users who need a WCAG-compliant text view should request Mode B output explicitly
("just tell me", "no file", "quick summary").

---

## When to use

- "Who are my most frequent co-investors?"
- "Show me an interactive co-investor report"
- "Who co-invested with me most often?"
- "Who are my most frequent co-investors with more than 5% of a round?"
- "Who co-invested in [Company Name]?"

---

## Step 0: Announce

Open every invocation with:

> "I'll analyze co-investors across your portfolio using SPA data uploaded to
> Carta — pulling data across all your funds. I'll normalize fund vehicles so
> each firm counts once, and build the interactive report. Larger portfolios
> take a moment."

Then proceed immediately to Step 1.

---

## Step 1: Establish firm context

1. Call `list_contexts` to get the firm UUID and display name.
2. If nothing returned → stop with: "I couldn't find any Carta data associated
   with your account. Try reconnecting to the Carta MCP server. If you believe
   you're already connected, contact your Carta representative."
3. Call `fetch("fa:list:entities", {})` and extract:
   - `firm_carta_id` from any entity in the response — the integer PK used in
     Carta web URLs.
   - `firm_vehicle_names` — collect the `name` of every entity returned. These
     are the firm's own fund vehicles. Use them as additional firm-exclusion
     patterns in Step A1 — without this, vehicles named differently from the
     parent firm slip into the co-investor results.
4. Store:
   - `<firm_id>` — the UUID (36-char string)
   - `<firm_name>` — display name from `list_contexts`
   - `<firm_carta_id>` — integer PK from `fa:list:entities`
   - `<firm_vehicle_names>` — array of fund vehicle name strings
5. Resolve `<base_url>` from the current Carta MCP server URL — never hardcode
   an environment URL. For the production MCP server (`mcp.app.carta.com`),
   `<base_url>` is `https://app.carta.com`. For any other MCP server URL,
   default to `https://app.carta.com` as well.

**Pre-flight check:** before any DWH query, confirm that `<firm_id>` is a
non-empty UUID string (matches pattern `[a-f0-9-]{36}`). If not, stop with:
"Could not determine your firm ID. Try reconnecting to the Carta MCP server.
If you believe you're already connected, contact your Carta representative."

Tell the user: `Firm context loaded: <firm_name>. Fetching SPA data…`

---

## Step 2: Route

**The default output of this skill is the interactive artifact. Proceed directly to Step A1.**

Only route to **text-only analysis (Mode B)** if the user explicitly signals they want text:
- Says "text only", "no file", "just tell me", or "quick summary" → Q1
- Mentions a specific company by name → Q4
- Mentions ">5%", "over 5%", "lead", or "leads" → Q2
- Mentions "<5%", "less than 5%", "under 5%", or "follow-on" → Q3

**Everything else — including any general request about co-investors — goes to Step A1.**

---

## Mode A — Interactive artifact

Generate a self-contained interactive HTML file showing the firm's most frequent
co-investors. Each portfolio company in the table is clickable — clicking it opens
a right-side drawer with the full investor breakdown for that company (investors,
% of round, amount paid).

### Step A1: Fetch SPA data

Resolve a stable, cross-platform working directory once before fetching.
The intermediate response files and the final HTML artifact all live under
`$WORKSPACE`. **Both the Claude process AND the