Help/Recipes/Tech lead or staff engineer

Design review page

Options and a proposed decision.

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

Not connected yet? Set up your AI Run in Claude Run in ChatGPT

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

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

What you get back

Open the full example →

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.

Example design review: serve recipes to agents by URL

The problem

Recipes live in a onecell cell. A person can open them, and a connected agent can read them over MCP. But the moment that matters most is before an agent is connected: onboarding, a link in a chat, or a new teammate's first session. Agent setup already solves this for its own instructions: /agent-setup/prompt.md is plain Markdown any agent can fetch. Recipes have no equivalent.

Goals

Any agent can fetch a recipe by URL, with no connection and no login.
One source of truth: a recipe is edited in onecell, not also in the repo.
Onboarding surfaces can link to recipes: agent setup, the Agents page, the first-run Inbox note.

Not a goal: serving private documents by URL. Only what is deliberately published as public.

Options

Option	How	For	Against
A. Public pages only	Publish each recipe; link /p/<slug>	No code; works today	HTML pages are heavy for agents to read, and the copyable prompt is buried in markup
B. Markdown files in the repo	recipes/*.md served like agent-setup/prompt.md	Versioned in git; same pattern as agent setup	Two copies of every recipe, the cell and the repo, which will drift
C. Markdown for any public page (recommended)	A route serves /p/<slug>.md from the published document through documentToMarkdown	One source; every public document gains an agent-readable form; embeds become links	Depends on publishing; the route must check visibility exactly as /p/<slug> does

flowchart LR
  C["Recipe written in the recipes cell"] -->|"publish as public"| P["Published document"]
  P --> H["/p/slug for people"]
  P --> M["/p/slug.md for agents"]
  S["agent-setup/prompt.md"] -->|"links the recipes index"| M
  A["Agent with no connection"] -->|"fetches"| M

Option C: one published document, two forms. Agent setup links the recipes index, so a new agent can find a recipe before it is connected.

Risks

The .md route must use the same visibility check as the public page, or it becomes a way round it. Reuse the public page's resolver and add a test that a private document returns 404.
Embedded examples become links. They still work, but an agent has to fetch the example separately.
Public pages can be indexed by search engines. That is intended for recipes; say so in the publish step.

Effort

Small: one route handler, a test for visibility, and a line in agent-setup/prompt.md. The Markdown export and the public resolver already exist.

.md for agents

Variations

Reviewing with the team

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.

With an interactive model

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 for the kind of thing that works.

A lightweight version

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

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.