getcargohq__cargo-skills/cargo/references/interaction.md

Interaction conventions — plan gates, choices, and presenting

How an agent working with Cargo communicates: when to stop and ask, how to offer choices, and how to present what happened. These defaults apply across every skill in this pack; recipes and runbooks link here instead of restating them.

They exist because Cargo work is collaborative and (often) paid: building a play, wiring a node graph, or fanning out a batch is a back-and-forth with the user, not a fire-and-forget task.

1. The plan gate — design approval before building

Before creating or editing a node graph, deploying a release, or launching anything beyond a trivial single-node change, present the plan and wait for approval:

• Trigger — how the play/workflow is launched (manual/CLI run, batch over a segment, schedule, segment change). Ask if it isn't stated; it shapes the whole graph (input shape, volume, where outputs land).
• Nodes and data flow — what each node does and what feeds it, in human-readable names. Past three nodes, draw it: a Mermaid flowchart of the graph, with the paid steps marked, is the artifact the user approves.
• Cost shape — which nodes are paid, rough per-record estimate.

Treat this as a hard gate: don't start building from an unconfirmed plan. It complements the cost gate in ../../cargo-gtm/references/cost-discipline.md, which stays authoritative for spend (sample → approval → full run): the plan gate approves the design, the sample gate approves the spend. A trivial change (fix one expression, rename a node) doesn't need the ceremony — say what you changed and why.

Batches get their own gate, every time. Launching a batch is the one action that turns a design mistake into a full bill in a single command, so it never goes straight to full scope: run 10–20 records, show what came back and what it cost, then ask whether to enroll the rest — with the record count and the credit estimate in the question, not just "proceed?". This holds even when the plan gate already passed, and even when the batch arrived through cargo-orchestration or cargo-project with no GTM framing. Mechanics per data kind: ../../cargo-orchestration/SKILL.md → "Create a batch".

2. Real choices: ask, with a recommended default

Many Cargo stages can be built more than one way — several providers cover the same enrichment, several actions do nearly the same thing, a step can be an agent node or a deterministic one. When alternatives genuinely differ:

• Never pick silently. List the options by human-readable name (never raw actionSlugs or UUIDs), with cost and what each is best at.
• Mark a recommended default and say why — the simplest option that fits the use case. The user should be able to accept in one word.
• Batch related questions into one round (trigger + provider + output destination), not a drip of one-offs.
• Don't ask when there's nothing to decide: one obvious option, or a pure read. Asking permission to look something up is friction, not collaboration.

How should this play be triggered?
1. Manual / CLI runs (recommended) — start with one-off test runs; attach a
   schedule or segment trigger later.
2. Segment change — every record entering the segment becomes a run.
3. Schedule — recurring batch over the segment.

And for email lookup: waterfall verify-first (~0.4 cr/row, recommended) or
FullEnrich premium (~1 cr/row, better coverage on small companies)?

3. Presenting defaults

• Narrate meaningful steps. One or two sentences before a change (what and why) and after it (what happened). Refer to nodes, actions, and plays by name.
• Summarize, don't dump. Raw JSON, full SQL results, or CSV contents are never the primary answer — turn them into a short table, a count, or a one-line takeaway, and keep large exports out of the conversation entirely (context discipline: ../../cargo-gtm/references/cost-discipline.md §6). Show raw output only when the user asks.
• Lead with the conclusion. State what happened or what you found first; evidence after.
• Show the structure at checkpoints. After building or editing a graph, after a pilot, and when reporting a run: a picture beats prose. For a node graph that means a Mermaid flowchart from cargo-ai orchestration node diagram (free, runs nothing) rather than a transcription — routing, fallback edges, and which nodes bill all survive the trip. Sources and rules: ../../cargo-orchestration/references/node-diagram.md. For anything else structural (a schema, a segment breakdown), a compact table.
• Always surface the URL. Every created or touched resource gets its app.getcargo.io link (URL patterns: uuid-flow.md) so the user can open it in the Cargo app.
• Receipts after paid actions are their own convention — format in cost-discipline.md §2.

4. Show the rows, not the schema

A user who has just built a model can't tell from a column list whether they built the right thing. Ten real rows tell them in one glance. So whenever a model gains structure or data, show the table:

• After creating a model or adding columns — echo the resulting schema as a compact table (column, type, what fills it). The model is still empty at this point; don't run a preview query expecting rows, and don't present emptiness as a result.
• After the first data lands (a batch, a play, an import writes into the model) — run cargo-ai storage query execute "SELECT * FROM <dataset>.<model> LIMIT 10" and show those rows. This is the checkpoint that matters: it's the first moment the user can see what they actually built.
• After a play populates a new column — preview that column alongside the record's identifying fields (name, domain, …), so filled vs. empty is obvious at a glance.

Storage queries are free and fast, so this preview costs nothing but a line of output. Keep it to ~10 rows and the columns that carry meaning — this is a glance, not an export (§3: summarize, don't dump). If the preview comes back empty or full of nulls when it shouldn't, that's a finding — say so instead of moving on.

Where these apply most

• Building or editing plays/workflows (cargo-orchestration, and node-graph steps in cargo-gtm recipes).
• Activating GTM recipes end-to-end (cargo-gtm — the pilot gate already encodes §1's spirit for spend).
• Reporting diagnostics (cargo-diagnostics — conclusion-first tables).
• CDK plans (cargo-project — project plan output is the plan-gate artifact; present the diff, not the raw state).