================
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:

.. code-block:: text

   @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:

.. code-block:: text

   @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:

.. code-block:: text

   @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:

.. code-block:: text

   @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.