> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Decision tracking MCP tools reference

> Reference for dotbot's 7 decision tracking MCP tools - create, read, update, and transition decision records from proposed through accepted or superseded.

dotbot's decision tracking system provides a persistent, version-controlled record of architectural, technical, business, and process decisions made during a project. Every decision record is stored in `.bot/workspace/decisions/` and committed to git, giving your entire team visibility through standard version history. The AI agent uses these records to constrain implementation: tasks declare `applicable_decisions` to ensure the agent respects previous choices before writing any code. There are 7 MCP tools for working with decision records.

***

## Decision states

A decision record moves through the following states:

| State        | Meaning                                                                      |
| ------------ | ---------------------------------------------------------------------------- |
| `proposed`   | The decision has been recorded but not yet formally accepted.                |
| `accepted`   | The decision is active and constrains future work.                           |
| `deprecated` | The decision is no longer relevant or applicable but is preserved for audit. |
| `superseded` | The decision has been replaced by a newer decision record.                   |

***

## `decision_create`

Creates a new Decision Record in the workspace with `proposed` status by default. **Required:** `title`, `context`, `decision`.

<ParamField path="title" type="string" required>
  Short title summarising the decision (e.g. `"Use PostgreSQL for primary data store"`).
</ParamField>

<ParamField path="context" type="string" required>
  Background explaining why this decision needed to be made - the forces at play, constraints, and situation that led to the decision.
</ParamField>

<ParamField path="decision" type="string" required>
  What was decided, stated clearly and unambiguously.
</ParamField>

<ParamField path="type" type="string">
  Type of decision. One of `architecture`, `business`, `technical`, `process`.
</ParamField>

<ParamField path="consequences" type="string">
  Trade-offs, risks, and follow-on constraints introduced by this decision.
</ParamField>

<ParamField path="alternatives_considered" type="array of objects">
  Options evaluated and why they were rejected. Each item has `option` (string) and `reason_rejected` (string).
</ParamField>

<ParamField path="stakeholders" type="array of strings">
  People involved in or affected by this decision.
</ParamField>

<ParamField path="related_task_ids" type="array of strings">
  IDs of tasks related to this decision.
</ParamField>

<ParamField path="related_decision_ids" type="array of strings">
  IDs of related decision records (e.g. `["dec-a1b2c3d4"]`).
</ParamField>

<ParamField path="tags" type="array of strings">
  Categorisation tags (e.g. `["database", "infrastructure"]`).
</ParamField>

<ParamField path="impact" type="string">
  Impact level. One of `high`, `medium`, `low`.
</ParamField>

<ParamField path="status" type="string" default="proposed">
  Initial status. One of `proposed` (default) or `accepted`.
</ParamField>

***

## `decision_get`

Retrieves a single Decision Record by its ID. **Required:** `decision_id`.

<ParamField path="decision_id" type="string" required>
  The decision ID (e.g. `"dec-a1b2c3d4"`).
</ParamField>

***

## `decision_list`

Lists all Decision Records, optionally filtered by status. Returns summary information for all matching records.

<ParamField path="status" type="string">
  Filter by status. One of `proposed`, `accepted`, `deprecated`, `superseded`. If omitted, all records are returned.
</ParamField>

***

## `decision_update`

Updates the fields of an existing Decision Record. Only the fields you provide are changed; all other fields retain their current values. **Required:** `decision_id`.

<ParamField path="decision_id" type="string" required>
  The ID of the decision to update (e.g. `"dec-a1b2c3d4"`).
</ParamField>

<ParamField path="title" type="string">
  Updated title.
</ParamField>

<ParamField path="type" type="string">
  Updated type. One of `architecture`, `business`, `technical`, `process`.
</ParamField>

<ParamField path="context" type="string">
  Updated context.
</ParamField>

<ParamField path="decision" type="string">
  Updated decision text.
</ParamField>

<ParamField path="consequences" type="string">
  Updated consequences.
</ParamField>

<ParamField path="alternatives_considered" type="array of objects">
  Updated alternatives. Each item has `option` and `reason_rejected`.
</ParamField>

<ParamField path="stakeholders" type="array of strings">
  Updated stakeholders.
</ParamField>

<ParamField path="related_task_ids" type="array of strings">
  Updated related task IDs.
</ParamField>

<ParamField path="related_decision_ids" type="array of strings">
  Updated related decision IDs.
</ParamField>

<ParamField path="tags" type="array of strings">
  Updated tags.
</ParamField>

<ParamField path="impact" type="string">
  Updated impact level. One of `high`, `medium`, `low`.
</ParamField>

***

## `decision_mark_accepted`

Transitions a `proposed` Decision Record to `accepted` status, making it active and binding for future tasks. Once accepted, the agent will read this decision whenever it is referenced in a task's `applicable_decisions` list. **Required:** `decision_id`.

<ParamField path="decision_id" type="string" required>
  The decision ID to accept (e.g. `"dec-a1b2c3d4"`).
</ParamField>

***

## `decision_mark_deprecated`

Marks a Decision Record as `deprecated`. The record is preserved for audit purposes but is no longer considered active or binding. Use this when a decision no longer applies without a direct replacement. **Required:** `decision_id`.

<ParamField path="decision_id" type="string" required>
  The decision ID to deprecate (e.g. `"dec-a1b2c3d4"`).
</ParamField>

<ParamField path="reason" type="string">
  Reason for deprecation. Helps future readers understand why the decision was retired.
</ParamField>

***

## `decision_mark_superseded`

Marks a Decision Record as `superseded` by a newer decision. Both the old and new IDs are recorded so you can trace the complete decision lineage. **Required:** `decision_id`, `superseded_by`.

<ParamField path="decision_id" type="string" required>
  The ID of the decision being superseded (e.g. `"dec-a1b2c3d4"`).
</ParamField>

<ParamField path="superseded_by" type="string" required>
  The ID of the decision that supersedes it (e.g. `"dec-e5f6g7h8"`).
</ParamField>

<Tip>
  Use `decision_mark_superseded` rather than `decision_mark_deprecated` when a new decision actively replaces an old one. This preserves the forward reference so anyone reading the old record can immediately navigate to its replacement.
</Tip>