--- name: build-brainstorm description: Start a new Introspection agent (Recipe) by drafting its cases from the owner's own material, asking only about the gaps, and getting the cases approved. Use when someone wants a new agent and no cases are approved yet. metadata: min-cli-version: "0.73.0" next: "build-draft" --- # Build: brainstorm Turn what the owner wants into **cases** they approve: concrete situations, each with the input the agent receives, a good result, a bad result, and how it will be checked. They are the agent's specification and first eval; nothing is built here. Understand the job before drafting a single case: from the owner's material when they have it (rules, templates, good results), otherwise from a short interview. The owner confirms the brief before they see cases, so approving the cases means approving tests of something you both agreed, not your guesses. ## Before you start - **Resume:** if `evals/cases/` has cases, continue with the drafts that aren't approved. - **Starting fresh:** when the owner hasn't described the agent yet ("help me build a new agent"), ask how to start before anything else, as [starting fresh](references/starting-fresh.md) says. - **Outside the Operator's launcher** (Claude Code, Codex): set up the folder and ask as [other hosts](references/other-hosts.md) says. Check the CLI first; say something only when something is missing, in one line. You need the `introspection` CLI, at least this skill's `metadata.min-cli-version`, and only one on the `PATH`: ```sh introspection --version which -a introspection ``` Otherwise stop and tell the owner what to run (`npm i -g @introspection-ai/cli@latest`, and remove an older build from their `PATH`). No login. `introspection init` already checked Pi and the folder, and the workspace note names `files/` and `outputs/`: don't check them again or tell the owner about them. ## 1. Create the repository Create the agent's repository before writing any file, `docs/DESIGN.md` included. Use another template only when the owner names one, and keep its licence. From the build folder: ```sh introspection init --template template-starter && cd && git checkout -b pr/ ``` Don't make the folder first: `init` makes it. Propose a short name in your first message without waiting; if they prefer another, rename the folder, the `package.json` name and `.introspection/.yaml`. Commit as you go, so a stopped session resumes. ## 2. Start from what's already here Read anything in the inputs folder (`files/`) at once and say in one line what you found; when it's empty, say nothing. - **If the owner hasn't said what the agent should do,** ask only that, in one short sentence in your reply ("What should the agent do?"). - **Don't ask for material up front,** or explain how to share files. Ask for a document only as an optional part of a question it would answer ("If you have a scoring guide, drop it in the files folder; otherwise, how should answers be judged?"). - **A link or an existing agent the owner names:** read it straight away, as [the owner's material](references/material.md) says, and record what it is. - **A file they share:** read it at once and keep it in the repository, for build-draft to turn into a skill the agent loads. Never ask them to summarise or redact it. Keep each message under about 40 words, and never repeat a request the owner has already seen. ## 3. Write and confirm the brief One short paragraph answering items 1 to 7 of [the readiness check](references/readiness.md): who it's for and how a task starts, what each request brings and what it returns, good and bad results, and what it must never do or leave to a person, then any defaults you chose. **Name who reads each output.** When it isn't the person talking to the agent (a hiring team reading about a candidate), propose a second agent for that audience, run in a task of their own (item 6). When the material doesn't answer the items, interview first, as [the readiness check](references/readiness.md#interviewing) says; when something stays vague, show something concrete instead of asking again. Write it into Part A of `docs/DESIGN.md` and review it with `review_artifacts`: one item, "The brief", `section: "Part A"`. Revise until it's approved. ## 4. Ask what it runs on Once the brief is approved, ask which model the agent runs on and how hard it thinks, as [choosing the model](references/model.md) says. ## 5. Draft the cases Draft from the confirmed brief and the material, into `evals/cases/` in [the case format](references/cases.md), with approval fields empty: - **Three or four cases per agent,** from its must-haves and boundaries and the readiness kinds (ordinary work, ambiguity, missing input, partial failure, a request it should decline). Always one ordinary case and its most important boundary. List the rest under "Later cases" in Part A, for improve. - **`check: code`** on every property that can be checked mechanically. - **One example result on a sample,** if the owner has one: the input of an ordinary case ("share one you received, as the agent would get it; it won't be committed"). With no material, draft from the brief and a realistic example, and let their corrections build the cases. ## 6. Ask only about the gaps One decision per question: what each request brings, the scope for now, choices the material leaves open, and contradictions you found between documents. Use [the readiness check](references/readiness.md) to find gaps, not as a questionnaire: an item the material answers is not a question. ## 7. Show the draft for approval In your message, a table of every case: id, title, how it's checked. If none is `code`, say what that leaves untested and offer code checks for the mechanical ones. Then review with `review_artifacts`: each case labelled by id and title ("C2: the candidate gives a vague answer"), `docs/DESIGN.md` first only if it changed since the brief was approved. - **Present the cases as tests of the one job,** not as features. If the owner wants fewer, say what will go untested. - **Change what they asked for** and review just those files again. When a request doesn't say what to change ("too vague"), ask one question about that case before editing it. ## 8. Record the approval Record only what the review result says was approved; never infer an approval. Record each approved case as `eval-case` says ("Approval"), naming the owner and the review they approved in; a later edit to the case reopens it. - **Change a case's approval fields only from a review that included that case:** never re-stamp or rewrite the others, even when the brief changes. - **Ask about an approved case again only when its file has changed** since it was approved; one that hasn't keeps its approval and isn't shown again. ## How to ask - **Ask only what changes a case;** never re-ask or restate the owner's answers. A question works read aloud, under about 75 words. - **No tool, model or file names** in questions or cases, unless the owner is an engineer. - **Find out what the agent must reach** for each case (email, a Drive folder, an API); a case needing a source it can't reach isn't done. - **Material that could be standing or per-request** (a deal brief serves one deal or many): ask which. ## Done when - Every case in `evals/cases/` is approved in a review, and committed to `pr/`. - Then hand over to `build-draft`, and not before: brainstorm writes the brief and the cases, never the Recipe's instructions or agents.