--- 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 ready for the owner's review. Use after build-draft, when the cases have run locally. The last step of build; deploy follows. --- # 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 first: 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 build-draft says, before reviewing anything. - You need the `introspection` CLI (`npm i -g @introspection-ai/cli`). No login unless the repository is the Introspection hosted one. - The `pr/` branch 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 of these is missing, go back to the step that makes it. ## Steps 1. **Check the state:** `introspection check`, then one smoke test as a local task, `introspection tasks create runs/smoke- --work-dir --prompt "hello"` from the build folder, to see the Recipe start and answer. 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, 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, and what a stranger would misread. Size the review to the Recipe: for a small one (a few cases, no tools, no documents, no connections), one `reviewer` with all four questions; otherwise one `reviewer` per question, all started in the same turn. In Claude Code or Codex, start subagents of your own with the same instructions (`agents/reviewer.yaml` in the Operator); a reviewer needs only read-only tools and nothing outside the repository. "Reviewers unavailable" is never a reason to skip review. 3. **Fix what blocks,** and run the checks again. Record what wasn't fixed and why. 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. Don't change an approved case yourself. 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 (`git rm`), and 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. **Package the pull request** with [the description template](references/pr-description.md) in `docs/PULL_REQUEST.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. 6. **Hand over to deploy-runtime,** straight away: the pull request is ready, and deploy lands it, creates its runtime, connects it and tests a real conversation on staging. ## 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. - No reviewer finding is left blocking. - The pull request exists (or the hosted branch is pushed) with a description a business owner can read.