--- name: build-review description: Review a drafted Introspection agent (Recipe) with fresh-context reviewers, fix what they find, and package it as a pull request the owner can review. Use when the approved cases have run locally on the current Recipe. metadata: min-cli-version: "0.73.0" next: "deploy-connect" --- # Build: review Check the draft as someone who wasn't in the conversation would, fix what they find, and hand the owner a pull request they can review without having followed the work. ## Before you start - **Check the stage.** No approved cases in `evals/cases/` means `build-brainstorm`. Every approved case needs a run of the current Recipe: a `code` case an eval run under `eval-runs/`, a `person` case a run folder under `runs/` with its transcript approved. A case without one means `build-draft` isn't finished: go back and run it, as it says, before reviewing anything. - **Check the branch.** `pr/` has the cases (`evals/cases/`), the design (`docs/DESIGN.md`, Parts A and B) and the Recipe, and build-draft's last commit records the case results. If any is missing, go back to the step that makes it. - **Tools:** the `introspection` CLI (`npm i -g @introspection-ai/cli`). No login unless the repository is the Introspection hosted one. ## 1. Check the state From the build folder: ```sh introspection check introspection tasks create runs/smoke- --work-dir --prompt "hello" ``` The smoke test shows the Recipe starts and answers. If nothing in the Recipe or its evals has changed since build-draft's last passing run (`git status` and the commits since say so), use that run's results; otherwise ask the eval runner to run the suite once more and use its results. ## 2. Review with fresh context Run the review in `reviewer` subagents. Give each only the repository's path and its questions, never the conversation. [The review questions](references/review-questions.md) cover the design against the cases, the Recipe against the design, the checks against the cases, what a stranger would misread, the situations no case covers, and, when Part B names an original, what it does that the Recipe doesn't. - **Size the review to the Recipe.** For a small one (a few cases, no tools, no documents, no connections), one `reviewer` with all the questions. Otherwise one `reviewer` per question, all started in the same turn. - **The original gets its own reviewer,** with the copy's path. A reviewer needs only read-only tools and nothing outside the repository, except the copy of the original in `files/` that Part B names. - **In Claude Code or Codex,** start subagents of your own with the same instructions (`agents/reviewer.yaml` in the Operator). - **"Reviewers unavailable" is never a reason to skip review.** ## 3. Fix what blocks Fix what blocks, and run the checks again. Record what wasn't fixed and why. Don't change an approved case yourself. - **A gap against the original, or a situation no case covers, is the owner's decision, not a fix:** ask in the pull request's summary, about each one by name, whether it should become a case. - **A finding that needs the owner's decision** (a case that seems wrong, a default they should see) goes in the pull request's summary as a question. ## 4. Check nothing private is committed No client documents (case inputs are referenced by hash), no credentials, no tokens. The branch is local until deploy, so remove anything found with a new commit: ```sh git rm ``` Squash this build's own commits only if a pushed branch would still carry it. Never delete `.git` or start the history again, and say in the pull request what you removed. Public material the owner pointed you to (a job posting, a public guide) isn't private: keep only the part the agent needs. ## 5. Promote the baseline Promote the suite's last full run of the reviewed Recipe as its baseline, in a commit of its own on `pr/`, as `eval-compare`'s "Keep a baseline" says, once per suite with an eval run. It is what later runs compare with: improve's regression check reads it to tell a case that broke from one that never passed. A case that fails in it stays failing there, with its reason in Part B; never rerun until it passes to promote. ## 6. Package the pull request Write `docs/PULL_REQUEST.md` with [the description template](references/pr-description.md), open it for the owner with `show_artifact`, and commit it on `pr/`. Don't push: the branch stays local until deploy, which chooses the repository with the owner and opens the pull request there. ## 7. Ask where the Recipe should live The last question of the build, unless onboarding already registered a repository or the owner chose Introspection there. With the question tool, offer the repositories deploy-create's first step lists, in its order, or a GitHub repository the owner names: 1. one the clone already pushes to; 2. one the project has; 3. one the organization's GitHub integration reaches; 4. a new hosted one. Choosing creates, registers and pushes nothing. Record the answer in Part B's change log. ## Guardrails - **Bounded:** at most the four review questions, each pass with a time limit (about five minutes), and at most two rounds of fix-then-re-review. Anything still open after that goes into the pull request description as an open item, not another loop. - **A fix re-runs only what it touches, once.** After a fix, re-run `introspection check` and the cases the fix affects, one run each. Review isn't a second draft: don't tune the agent's instructions against one output and run it again, since that fits the agent to a single run. If a case still fails, record it in Part B and the pull request as an open item. - **Reviewers only report.** Findings come back as text; only this step edits the repository, so one reviewer can't undo another's work. - **No real data, credentials or pushes during review.** Reviewers read the repository; they don't run the agent against real connections or push anything. - **Never widen access to finish a review.** If a pass can't reach something (a permission prompt, a missing tool), record that and continue; never ask the owner for broader access or use paths outside the repository. - **The repository holds only what the Recipe needs.** Working files a run left behind (scratch scripts, test outputs, copies of inputs) are a blocking finding: remove them, and keep run outputs under a gitignored folder, since anything in the package ships with the agent. ## Done when - No working files are left in the repository outside what the Recipe needs. - `introspection check` passes, the Recipe boots (a `runs/smoke-` task answers), and every case passes or has a written reason in Part B. - Each suite's baseline is the last full run of the reviewed Recipe, promoted in its own commit. - No reviewer finding is left blocking. - The pull request exists (or the hosted branch is pushed) with a description a business owner can read. - Then hand over to `deploy-connect` straight away, with the repository choice: deploy connects what the Recipe needs, lands it in that repository, creates its runtime and tests a real conversation on staging.