--- 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 built and there is no approved set of cases yet. The first step of build; build-draft follows. --- # 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. The cases are the agent's specification and its first eval. Nothing is built in this step. Understand the job before drafting a single case. How you get there depends on what the owner brings. With real material (their rules or guidelines, templates, examples of good results), the documents answer most questions: write the brief from them, confirm it, and draft early, asking only about the gaps. With little or none (a role description, a sentence of intent), interview first: a short conversation until you can write the brief, and only then draft. Either way 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 - If the repository already has cases in `evals/cases/`, resume from them: this step is done for every approved case, and you continue with the drafts that aren't approved. - **Starting fresh, ask how to start** when the owner hasn't described the agent yet (a new build opens with only "help me build a new agent" or similar): one question with the question tool, header "Start", "How do you want to start the new agent?", options "Build it with me (recommended)" (they describe it or share documents; you draft its tests, then build and test it with them) and "Start from a template" (a starter Recipe they edit themselves), with one sentence before it on what building with you involves. For a template, propose a short name, run `introspection init --template template-starter`, tell them to run `cd && introspection local`, and stop: there are no cases to draft. If the owner's first message already describes the agent, they've chosen to build: skip the question. - You need the `introspection` CLI (`npm i -g @introspection-ai/cli`). This step needs no login. Report readiness in one line; don't narrate the checks. - Create the agent's repository first, so the cases have a home: `introspection init --template template-starter`, then `git checkout -b pr/`. Choose a short name from what the owner described and propose it in your first message without waiting; if they prefer another, rename the folder, the `package.json` name and `.introspection/.yaml`. Use another template only when the owner names one, and keep its licence. Commit as you go: a session that stops resumes from these files. ## Steps 1. **Start from what's already here, then the job.** Look in the workspace's inputs folder (`files/`) yourself and read anything there at once; say in one line what you found, if anything. If the owner hasn't said what the agent should do, ask only that, in one short sentence ("What should the agent do?"). Don't ask for material up front, and don't explain how to share files or ask for access to `files/`: you already have it. Ask for a document only later, when a question in step 2 is one a document they may have would answer (rules or guidelines, a scoring guide, a template, an example of a result they liked), as an optional part of that question ("If you have a scoring guide, drop it in the files folder; otherwise, how should answers be judged?"). **A link the owner gives is material they've shared:** open it yourself at once, with the host's web tool or `curl -L` in a shell, save the readable text into `files/` and read it, before saying anything else. Never say you can't read a link you haven't tried, and never ask them to paste what it shows; only if fetching fails, say so in one line and ask for the text. Keep each message short enough to read aloud, under about 40 words, and never repeat a request the owner has already seen. When they share a file, read it at once (see the shared instructions for Word and PDF), and keep it in the repository for build-draft to turn into a skill the agent loads at run time (a file nothing points to is invisible to the agent). Never ask them to summarise or redact their own material. 2. **Understand the job, then draft.** - **Write the brief:** one short paragraph in plain language saying who the agent is for and how a task starts, what each request brings, what it returns, what a good and a bad result look like, and what it must never do or must leave to a person, with any defaults you chose listed after it. These are items 1 to 7 of [the readiness check](references/readiness.md). - **When the material answers them,** write the brief from it straight away. - **When it doesn't, interview first.** Ask open questions in your reply, not with the question tool: discovery isn't a choice between options. One or two per message, each building on the last answer, starting with what the material leaves most open (who it's for, how it should come across, what happens with its result, what would make it go well or badly). Use the readiness check to pick the next question, not as a questionnaire, and default what wouldn't change what the agent does. Stop when you can write the brief, or after about five exchanges, whichever comes first; when something stays vague, show something concrete instead of asking again. - **Confirm the brief** before drafting: show it and ask what they'd change or add, in your reply ("Anything you'd change or add?"). Write the confirmed brief into Part A of `docs/DESIGN.md`. - **Then draft from the confirmed brief and the material:** - the cases, one per must-have, rule or boundary they state (positions it insists on, structural rules, how results should read), plus the readiness set: ordinary work, ambiguity, missing input, partial failure, and a request it should decline, such as conceding something the material forbids; - one example result on a sample, if the owner has one. Say which kind of input the sample should be, the one the agent receives in an ordinary case, not just "a sample" ("share one you received, as the agent would get it; it won't be committed"). Write the drafts to `evals/cases/` in [the case format](references/cases.md), with approval fields empty. 3. **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. 4. **Show the draft for approval:** the cases and the example, in plain language, in your message itself, before the approval question, so the owner sees what they approve without opening anything. One short block per case: its id and title, the situation and what the agent receives, a good result, a bad result, and how it's checked. Then give the full path of each case file and of `docs/DESIGN.md`, so they can open them. Ask what they'd change or add, in neutral words ("Anything you'd change or add before I build it?"), not "is this right?", which invites a yes, nor "what's wrong?", which assumes a fault. Offer "Approve all" (and, when useful, "Approve all but one") as options; don't offer "Change" as an option, since the owner types any change as their own answer. Present the cases as tests of the one job, not as features: if the owner wants fewer, say what will go untested. Update what they correct and show it again. 5. **Record the approval** in each approved case: who, when, and the message they approved it in. An approval is an explicit message, never inferred. Commit to `pr/` and hand over to **build-draft**. If the owner has no material, the interview in step 2 does the work: once the brief is confirmed, draft from it and a realistic example, and let their corrections build the cases. ## How to ask - **Use the host's question tool** for every decision: `ask_user_question` in Introspection and Pi, `AskUserQuestion` in Claude Code, or the equivalent elsewhere. One question, two or three short option labels; the tool numbers them and lets the owner type a different answer. Without a question tool, ask in text with numbered options and "or tell me otherwise". Don't list the options in the question text. A request for files or other free text isn't a decision: ask it in your reply (step 1), and so are step 2's interview questions. - **Every question must work read aloud:** under about 75 words, with enough context that a bare option number makes sense. - **Ask only what changes a case,** and never re-ask what's answered or restate the owner's answers. - **Speak the owner's language:** no tool, model or file names in questions or cases, unless they're an engineer. - **Find out what the agent must reach** for each case (email, a Drive folder, an internal API). A case that needs a source it can't reach isn't done. - **Request material is not standing material.** A customer's contract or an inbox is a case input: referenced by content hash, never committed. When something could be either (a deal brief serves one deal or many), ask.