Recording decisions

A decision topic records a choice your team made, why you made it, and what you ruled out. Months later, a teammate or an agent finds it before starting the same debate again. This page shows how a good decision topic reads, and how to ask your agent to write one.

Agents write topics with the ledger tools over MCP (Model Context Protocol, the standard way agents connect to tools). People read topics in the console. The console's Ledger page is read-only.

What a decision topic holds

Part	What it holds	Can it change?
Title	The decision itself, in one line	No
Summary	The question, the context and the options, as they stood when the topic was opened	No
Current state	Where the decision stands now, in a few sentences	Yes, by appending an entry that sets a new one
Status	proposed by default when opened; later accepted, superseded or reverted	Yes, by appending an entry that sets a new one
Repository	The project the topic is filed under. It starts the topic's id, for example payments-0012	Only by moving the topic
History	Every entry ever added, each with its author and agent	Entries are added, never edited

Every topic and every entry records who wrote it: the person whose API key made the call, plus the agent label, such as "Claude Code". See Keys & attribution.

Write the title as the decision

The title is what people scan in search results. Write the decision, not the subject.

Instead of	Write
Payment retries	Retry a failed card payment at most three times over 24 hours
Refund policy	Refunds over $500 need a team lead's approval
Search options	Use the database's built-in search, not a hosted search service

The title is fixed. While a decision is still proposed, title it with the option you propose. If the team chooses something else, record the new choice as a new topic that supersedes the first.

Frame the question in the summary

The summary is fixed when the topic is opened. It keeps the original framing, so a later reader can judge the decision by what was known at the time. Include:

• the question being decided;
• the context: what prompted it, and any facts or numbers that matter;
• the options you considered, including the ones you expect to reject.

Keep the reasoning for the final choice in the current state.

Keep the current state short

The current state says where things stand now. Keep it to a few sentences:

• the decision, and who agreed to it;
• the main reason;
• each rejected option, and why it lost;
• what would make you revisit it, if anything.

When something changes, the agent appends an entry and sets a new current state. The old state stays in the history. If the current state keeps growing, you are recording several decisions in one topic. Split them.

One decision per topic

Prefer many small topics to one broad one. "Use Postgres for the ledger" and "Retry failed writes three times" are two topics, not one "storage" topic. Small topics are easier to find, to cite and to replace one at a time.

Append to a topic only to record a change to that same decision: its status, a correction, or its outcome. A new decision gets a new topic, even when it comes up in the same task.

Choose the repository

Every topic is filed under a repository name, the repo argument. The name starts the topic's id: the twelfth topic filed under payments in a namespace is payments-0012.

• For a decision about code, use the GitHub repository's name. One repository filter then finds both the code and the decisions about it.
• For other teams, use a short, stable project or team name, such as support-policies or vendor-review.
• Use only letters, digits, ., - and _. Spaces are refused. Filters match names exactly, so keep them lowercase.
• Agree a short list of names, and put it in your agent instructions.

Agents that use the hosted MCP servers must name the repository when they create a topic. There is no default. A topic filed under the wrong name can be moved.

Ask your agent

You don't call the ledger tools yourself. You ask your agent in plain words. For example:

• "Before you change how we retry payments, search the ledger for earlier decisions about retries."
• "Record this as a decision under payments: retry a failed card payment at most three times over 24 hours. Put the three options we discussed in the summary."
• "The payments leads agreed. Mark payments-0012 accepted and update its current state."
• "We're changing approach. Record the new decision and have it supersede payments-0012."

To make this a habit rather than a request, add two standing rules to your agent instructions: search the ledger before a non-obvious decision, and record the outcome when you finish.

Say who agreed

A decision starts as proposed unless your agent sets another status. Workstate has no approval step, so when the people who own the decision agree, ask your agent to set accepted and to name who agreed in the entry.

Example

Illustrative

This example is not real data.

Field	Example
Id	payments-0012
Type	Decision
Status	Accepted
Title	Retry a failed card payment at most three times over 24 hours
Summary	Failed card payments are retried every hour with no limit. Some customers were charged fees by their bank for repeated declines, and support received complaints. Question: how should we retry a failed payment? Options: (1) keep hourly retries; (2) retry at most three times over 24 hours, then email the customer; (3) never retry, and email the customer at once.
Current state	Accepted by the payments leads. Retry after 1, 6 and 24 hours, then email the customer a link to update their card. Option 1 rejected: it caused the complaints. Option 3 rejected: most declines clear within a day. Revisit if fewer than 60% of failed payments recover.

Its history, newest first, as the console shows it:

Entry	Written by	Text
Status changed	sam@example.com with Cursor	The payments leads agreed on option 2. Accepted.
Note	dana@example.com with Claude Code	Proposed: option 2, retry after 1, 6 and 24 hours, then email the customer.

The calls an agent makes

The agent creates the topic with ledger_create. The initial state becomes the first entry in the history.

{
  "type": "decision",
  "repo": "payments",
  "title": "Retry a failed card payment at most three times over 24 hours",
  "summary": "Failed card payments are retried every hour with no limit. ... Options: (1) keep hourly retries; (2) retry at most three times over 24 hours, then email the customer; (3) never retry, and email the customer at once.",
  "initial_state": "Proposed: option 2, retry after 1, 6 and 24 hours, then email the customer."
}

Later it records the outcome with ledger_append:

{
  "topic_id": "payments-0012",
  "kind": "status_change",
  "body": "The payments leads agreed on option 2. Accepted.",
  "set_status": "accepted",
  "set_state": "Accepted by the payments leads. Retry after 1, 6 and 24 hours, then email the customer a link to update their card. ..."
}

Every argument is described in MCP tools.

Read decisions in the console

The Ledger page lists every topic in the namespace you are working in, most recently updated first, 50 to a page. Archived topics are not listed.

To browse the decisions:

1. Open Ledger.
2. Under Type, choose Decisions.
3. To narrow the list further, open Repository and pick one or more repositories. Each one shows how many topics it holds.
4. Use Previous and Next under the list to move between pages.

To search instead:

1. In Search the ledger, describe what you're looking for, for example "how we retry failed payments". Then press Enter or select Search. Results are ranked by meaning, so describe the problem rather than guessing its exact words.
2. The page shows the 25 best matches within the Type and Repository filters you chose. To go back to the full list, clear the search box.

Open a topic to read it. It shows Current state first, then Summary · fixed when the topic was opened, then History, newest first. The side panel shows the status, type, repository and namespace, when the topic was opened and last updated, and who opened it.

To share a topic, use Copy link: the link opens the topic in its own namespace. A topic that a newer one replaced shows a Superseded notice that links to its replacement.

Next steps

• Incidents & defects
• Supersede, move & archive
• What's worth logging
• Agent instructions