Help/Recipes/Tech lead or staff engineer

Record a decision

With the reasoning, where it's found.

For: A tech lead, or anyone who just made a call that others will ask about later
When: Right after the decision, or when merging the pull request that carries it
Takes: About a minute of agent time
You get: A decision block with the context, the choice, the options weighed and what it commits you to, which list_decisions and search will find

The prompt

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

Record a decision in onecell: <what was decided, or "the decision we
just made">. Save it to <cell> (default: this project's cell).

1. Check it isn't already recorded: call list_decisions for the cell and
   search for the topic. If a decision block already covers it, update
   that one (get_document, then update_document with expected_version).

2. Gather the reasoning from where it happened: this conversation, the
   pull request and its comments (gh pr view <n> --comments), the commit
   message, or the issue. Use nothing you can't point to.

3. Write a decision block with create_document (dry run first), or add
   it to the right document with update_document:
   - title: the question, in a few words
   - context: why it needed deciding, and the constraint that forced it
   - decision: what we will do, in one or two sentences
   - consequences: what it commits us to, and what it rules out
   - status: accepted only if it was actually agreed or merged;
     otherwise proposed. Don't set decidedBy: onecell records who.
   Add a table of the options considered. If you had to infer any,
   say so.

4. Reply with the link and one line on what changes for the team.

What your agent does

Checks for an existing record
list_decisions and search find a decision block on the same question, so there is one record, not two.
Gathers the reasoning
From the conversation, the pull request thread, the commit message or the issue, only from sources it can point to.
Writes the decision block
Context, decision, consequences and honest status, plus the options considered. onecell stamps who moved it out of proposed, and when.
Tells you what changed
A link and one line for the team.

What you get back

Open the full example →

Here is the decision recorded from pull request #72, which moved the app's content security policy out of the build. Notice that the options the pull request didn't mention are marked as reconstructed.

Example decision: set the content security policy per request

Accepted2026-09-29by blondon via an agent

Set the content security policy per request, in proxy.ts

Context

The app's CSP was set in next.config's headers(), which Next evaluates when the image is built. Production settings live in the box's .env and change without a rebuild. When SANDBOX_ORIGIN was added after the build, the CSP never included it, and browsers refused the sandbox frame.

Decision

proxy.ts sets Content-Security-Policy and its report-only twin on every response, reading the environment at request time. The sandbox bootstrap is skipped because it sends its own policy. The CSP is removed from next.config.

Consequences

Settings that shape the CSP take effect on restart, with no rebuild. The policy is computed on every request, which is cheap. Anything else in next.config headers() is still fixed at build time, so new runtime settings must not go there.

Options considered

The pull request describes only the option chosen. The agent reconstructed the other two from the problem it solved, and marked them so.

Option	For	Against
Keep it in next.config and rebuild when settings change (reconstructed)	No code change	Every settings change needs a new image; easy to forget, as the launch showed
Pass SANDBOX_ORIGIN as a build argument (reconstructed)	Small change	Moves a runtime setting into the build, the same trap in a new place
Set it per request in proxy.ts (chosen)	Always matches the running settings; one place for all response policy	Runs on every request; the bootstrap needs an exception

Where it is enforced

A test sets SANDBOX_ORIGIN after start-up and checks that the next response's CSP follows it, and that the bootstrap gets none of it. See pull request #72 and the postmortem of the sandbox launch, where the problem was found.

.md for agents

Variations

From a pull request thread

Replace the first line with “Record the decision in pull request <n>”. The agent reads the description and review comments with gh pr view --comments and records it as accepted once the pull request is merged.

In the middle of a session

When a call gets made in chat, say “record that as a proposed decision”. You can accept it later in the document, or by asking your agent, and onecell records who accepted it.

Replacing an old decision

Add: “This replaces the decision on <topic>. Mark the old one superseded and link the two.” The history stays readable: what we thought then, and what we think now.

Tips

The context is the part people need in six months. The decision alone rarely explains itself.
Proposed is the honest default. Accept a decision when it has actually been agreed.
Ask “what decisions are open?” at the start of the week: list_decisions finds every proposed one, across clusters.