Track a Decision¶
Not every choice is worth recording — but the ones that are tend to come up again later. This guide explains when to track a decision and how.
When to record a decision¶
Record decisions that involve genuine tradeoffs: architectural choices, approach selections where a reasonable person might have picked differently, and process changes made after discussion.
Examples worth recording:
“We’re using SQLite for local dev to keep the stack simple.”
“We chose async event streaming over polling for lower latency.”
“The spec review step now happens before kickoff, not after.”
Examples that are not decisions in this sense:
“Fixed a null check in the export handler.” (Bug fix, not a tradeoff.)
“Added a missing index.” (Obvious mechanical improvement.)
If you’re debating whether something qualifies, it probably does.
How agents propose decisions automatically¶
Agents record decisions as they work. When Implementation chooses an
approach, or Spec resolves an open question, the agent calls
propose_decision before moving on. You’ll see a proposed decision appear
in the Decisions panel on the right side of the space.
You don’t need to ask agents to do this — it’s part of how they work.
How to propose a decision yourself¶
You can record a decision directly by mentioning any agent:
@Product I'd like to record a decision: we're using SQLite for local dev
to keep the stack simple.
Or ask an agent that was part of the discussion:
@Spec can you record the decision we just made about the retry strategy?
The agent will create a proposed decision and it will appear in the panel.
Resolving and rejecting decisions¶
A proposed decision sits in proposed state until someone acts on it.
Resolve it to accept it as the team’s direction. Agents and team members can resolve decisions; the outcome is recorded with a short explanation of why.
Reject it to note that the option was considered but not adopted. Rejected decisions are still visible — knowing what you didn’t choose is often as useful as knowing what you did.
To resolve or reject from the UI: open the Decisions panel, find the decision, and click Resolve or Reject.
To ask an agent to do it:
@Product can you resolve the SQLite decision — we've confirmed it.
Reviewing past decisions¶
Open the Decisions panel at any time to see all proposed, resolved, and rejected decisions in chronological order. Filter by status to narrow the list.
To get a narrative summary instead:
@Product can you summarize the key architectural decisions so far?
The agent will pull from the full decision history and give you a readable digest.