# Recipe: design review page, options and a proposed decision

A copy-paste prompt: your agent reads what exists, then writes a design review with options, a diagram, risks and a proposed decision for reviewers.

> [!info]
> **For:** a tech lead or engineer proposing a change. **When:** before building anything that others will have to live with. **Takes:** a few minutes of agent time. **You get:** a review page with the problem, options, a diagram, risks and a proposed decision that reviewers can accept.

## The prompt

```text
Write a design review page in onecell for <problem>. Save it to <cell>.

1. Look first: search onecell and call list_decisions for earlier specs,
   decisions and discussions, and read the code involved. Link what
   exists rather than restating it.

2. Draft "Design review: <problem>" with create_document (dry run first):
   - The problem in a short paragraph, with the constraint that makes
     it hard
   - Goals and non-goals
   - Options: a table of 2 to 4 approaches, with how, for and against
   - A mermaid diagram of the recommended approach
   - Risks as a checklist, each with how you would catch it
   - Your recommendation as a decision block, status proposed
   - Effort: a rough size, and what already exists to reuse

3. If a number or behaviour is hard to picture (load, latency, cost),
   suggest an interactive block, but don't add one unless I ask.

4. Reply with the link and the one question reviewers must answer.
   Keep it a draft.
```

## What your agent does

1. Reads what exists
   Earlier specs and decisions in onecell, and the code the change touches, so the options are grounded.
2. Lays out the options
   Two to four real approaches with honest trade-offs, including the cheap one.
3. Draws the recommendation
   A mermaid diagram of how the chosen approach works.
4. Proposes, doesn't decide
   The recommendation is a proposed decision block. Reviewers accept it, and onecell records who did.

## What you get

A real review of an open question from this cell: how an agent that isn't connected to onecell yet can fetch a recipe. It found that the Markdown export already exists, which made the recommended option small.

<!-- onecell:block {"type":"embed","documentId":"2e7e97a0-0f8a-4315-87ed-40fb8f8f0c89"} -->
[Example design review: serve recipes to agents by URL](https://onecell.io/p/example-design-review-recipes-by-url)

## Variations

<details>
<summary>Reviewing with the team</summary>

Save it to a shared cell or the hive and share it with the reviewers. When they agree, accept the decision block. Anyone who later asks “where did we decide this?” gets this page.

</details>

<details>
<summary>With an interactive model</summary>

If the choice turns on how a system behaves under load, ask for an interactive block that lets reviewers try it. See the tail latency model in [Systems intuition](https://onecell.io/cells/onecell-examples/f7182ef3-c5db-45ed-9a3a-e9aea903e85a) for the kind of thing that works.

</details>

<details>
<summary>A lightweight version</summary>

For a small change, ask for the problem, one recommended approach, its risks and the proposed decision. Skip the options table.

</details>

## Tips

- Include the option you expect to reject: it shows reviewers why.
- The effort section is where reading the code pays off. Existing pieces often shrink the estimate.
- End with one question for reviewers, not five.

---

Part of [onecell recipes](https://onecell.io/cells/recipes/6afc2a14-8a68-480d-99d8-7edd66893874): copy-paste prompts for using onecell in your work.