---
name: start-new-case
description: Use when the user describes something they want to build in Tela but has not said whether it should be a canvas, a workflow, or an agent — or asks "how do I start", "what's the best way to do X", or wants to know if a template already exists for their case.
---

# Starting a new case

When someone describes a problem rather than naming a thing to build, do this in order:

1. Understand the shape of the work (below).
2. Recommend **one** of canvas / workflow / agent, and say why in one sentence.
3. Look for a template that already covers it.
4. Build the smallest version that can be tested, then iterate with the feedback loop.

Do not ask a long questionnaire. Most cases are decidable from what the user already said, plus at
most one clarifying question.

## Choosing

### Canvas — one model call

Variables in, one answer out. No steps, no tools, no branching.

Reach for it when the work is a single transformation: extract fields from a document, classify a
ticket, rewrite text in a house style, summarize, translate, draft from a form.

**This is the default.** Most real cases are one call. A canvas is the cheapest thing to build, the
easiest to review attribute by attribute, and it can be wrapped in a workflow later without being
rewritten.

### Workflow — a known sequence of steps

A chain of steps you can draw in advance. Twelve action types exist: `llm-completion`, `canvas`,
`agent`, `agent-fcc`, `code-execution`, `condition`, `map`, `stop`, `template`,
`document-splitter`, `document-cropper`, `document-templater`.

Reach for it when at least one of these is true:

- The output of one model call feeds a **different** prompt, with different instructions.
- The work needs **deterministic** glue: code, a document split, a DOCX fill, a cropped page range.
- It must **branch** on a value — route by category, stop early when a condition fails.
- It must **repeat** over a list of items (`map`).
- It composes existing canvases you already trust (`canvas` node).

Know the constraint before promising anything: a workflow is a **linear chain**. It branches only
through `condition` ports and `map` subgraphs. There is no free-form fan-out — see the graph shape
rules in `workflow.md`. If the user's mental picture is a diagram with parallel arms merging back,
say so up front rather than discovering it at save time.

### Agent — the steps are not known in advance

Multi-round, decides its own next move, uses tools, reads and writes files in a sandbox, and can call
canvases, workflows, and other agents as capabilities.

Reach for it when the work is open-ended: research until a question is answered, operate a repo,
investigate and follow leads, use a tool whose need depends on what it finds.

Agents cost the most to build and to evaluate. Do not choose one because the task is "complex" — a
long pipeline is still a workflow. Choose one because the **sequence is genuinely unknown until
runtime**.

### The one question that usually decides it

> Can you write down the steps in advance?

- No, it depends on what it finds → **agent**
- Yes, and there is more than one, or one of them is not a model call → **workflow**
- Yes, and it is one → **canvas**

### A second consideration: how it will be reviewed

The choice changes what evaluation you get, and teams that care about quality should hear this
before committing:

| | Canvas | Workflow | Agent |
|---|---|---|---|
| Per-attribute review | yes | yes | yes |
| Written acceptance criteria judged by an LLM | yes | yes | **no** |
| Comments on a result | yes | yes | **no** |
| Named metrics over attributes | no | no | yes |
| See the exact prompt that ran | **no** | yes (step outputs) | yes (session thread) |

If the user's priority is a reviewable, auditable output, canvas and workflow are the stronger
ground. See `test-case-review.md` and `measure.md`.

## They compose

Nothing here is a one-way door:

- A canvas becomes a step in a workflow via the `canvas` node.
- A workflow or agent becomes a tool for an agent via capabilities.
- A workflow can call another workflow's template via the `template` node.

So the honest advice is almost always: **start with a canvas, promote it into a workflow step when a
second stage appears.** Say that instead of over-designing on day one.

## Then look for a template

Before writing a prompt from scratch, check the catalog — see `templates.md`.

```bash
bun --preload ~/.claude/skills/tela-studio/preload.ts -e "
for (const t of await tela.recommendTemplates('ler notas fiscais em PDF e extrair fornecedor e total'))
  console.log(t.score.toFixed(2), '|', t.template.type, '|', t.template.name, '—', t.reason)
"
```

Templates carry `useCases`, `industries`, and `utilities`, which is what makes matching a user's
description possible. Present the top match with what it does and what it will ask for, and let the
user decide — do not instantiate one without saying which you picked and why.

Check `isAmbiguousRecommendation(results)` before picking. Extraction and validation templates share
most of their vocabulary, so a near tie is common and means the intent is not yet pinned down — show
both and ask.

If nothing scores well, say so plainly and build from scratch. A bad template is worse than none: the
user inherits a prompt they did not write and cannot explain.

## Build the smallest testable thing

Once the path is chosen:

1. Create it with a **structured output** from the start. Without one, results cannot be reviewed
   attribute by attribute, and the whole feedback loop degrades to eyeballing prose.
2. Add **two or three test cases** with real inputs — not invented ones.
3. Run them, review the attributes, and only then iterate.
4. Use `compareVersions` to prove the next version is better before promoting it.

Resist building the full pipeline first. A canvas with one good test case teaches more in five
minutes than a six-step workflow with none.