Decision Records

Decision records (Architecture Decision Records, ADRs) track key technology and design choices in a project. Backlog.md supports the ADR format natively. Each decision is stored as a Markdown file in backlog/decisions/, including status metadata and full context.

Creating Decision Records

# Default status is proposed
backlog decision create "Use PostgreSQL as the primary database"

# Specify the status at creation time
backlog decision create "Migrate to TypeScript" -s accepted

After creation, the system generates a file such as decision-3 - Migrate-to-TypeScript.md under backlog/decisions/. The file frontmatter includes a status field that identifies the decision's current lifecycle stage.

Status Flow

Decision records support five standard statuses that reflect the full lifecycle from proposal to retirement:

There are two ways to change status:

# Change only the status; the body is preserved byte-for-byte
backlog decision update decision-3 --status accepted

# Change status and append content in the same commit
backlog decision update decision-3 --status superseded --append-content "## Supplement\n\nSuperseded by decision-7"

--status accepts free text; the convention values are proposed / accepted / rejected / superseded. An explicitly passed status takes precedence over the frontmatter value. You can also edit the decision file frontmatter directly, or edit it in the Web interface decision detail page (see Documents & Decisions). On the MCP side, the decision_update tool provides content / appendContent / status parameters. It is recommended to record the reason and time of status changes in the body to keep the audit trail complete.

Listing Decisions

backlog decision list

The output includes the ID, title, and current status of all decisions. Completed decisions (accepted, rejected, deprecated, superseded) are usually shown alongside active ones for quick reference to historical choices.

In TTY terminals, this command opens a dual-pane interactive browser: the left pane lists Decisions (N) and the right pane renders the raw Markdown of the selected decision in real time. ← / → switch focus between panes, ↑ / ↓ (or j / k) navigate or scroll within the current pane, Enter opens the full viewer, ? opens the help popup, and q exits. The active pane border is highlighted in yellow.

# Plain-text output (good for scripts)
backlog decision list --plain

# Paging window: at most n / skip n / total count only
backlog decision list --max-count 20
backlog decision list --max-count 20 --skip 20
backlog decision list --count

# Structured JSON output (versioned envelope kind: "decision-list")
backlog decision list --json

Non-TTY environments fall back to plain-text output by default; when the decision log is empty it prints No decisions found..

Decision listing is also exposed through MCP: the decision_list tool supports limit / offset / status / search filtering and returns a unified { items, total, offset, limit, hasMore } paging envelope. See MCP Workflow for details.

Viewing Decisions

backlog decision view decision-3

In TTY environments this opens a scrollable interactive viewer by default (PageUp / PageDown / Home / End are available; mouse tracking is disabled on Windows to avoid hanging PowerShell / VS Code). In non-TTY environments it falls back to --plain output of frontmatter and Markdown body.

When a single ID matches multiple files, the command prints all candidate paths and fails with exit code 1 rather than picking one (the same fail-closed identity rule as documents).

Updating Decisions

# Replace the decision body
backlog decision update decision-3 --content "## Context\n\nUpdated context description"

# Append a section (repeatable; preserves existing body)
backlog decision update decision-3 --append-content "## Supplement\n\nNew considerations"

decision update reuses structured section parsing (Context / Decision / Consequences / Alternatives). Both --content and --append-content support the same \n newline escapes as other commands; status is changed via --status (see previous section). The three options can be used individually or in combination.

ADR Format Overview

Generated decision files follow the standard ADR structure:

---
status: proposed
date: 2026-05-07
---

# Migrate to TypeScript

## Context

The project currently uses JavaScript. As the codebase grows, type-safety issues become more prominent ...

## Decision

Migrate fully to TypeScript with strict mode enabled.

## Consequences

- Positive: compile-time type checking, better IDE support, fewer runtime errors
- Negative: initial migration cost, team learning curve

Field Descriptions

• status: Current status of the decision, required.
• date: Creation date, auto-generated.
• Context: Describes the problem background and constraints.
• Decision: States the decision clearly.
• Consequences: Lists positive and negative effects of the decision.

Linking to Tasks and Documents

When creating or editing a task, you can link a related decision with the --doc option:

backlog task create "Upgrade build tool to Vite" --doc decision-3

This lets you jump directly to the decision context from the board or task detail, avoiding repeated discussion of decisions that are already settled.

Backlinks

The decision page (right pane of the CLI decision view interactive browser, and the Web decision detail page) displays a backlinks list showing which tasks, documents, decisions, or Wiki pages reference the current decision:

• The index is built on the client (buildBacklinkIndex) and refreshes live as content changes; it never writes back to files.
• Each backlink shows the source type icon, title, and ID; click to open the source in the current view.
• Sources that match multiple IDs are collapsed into a dropdown selector.

Backlinks are a read-only navigation aid and do not affect decision content or status flow.

Best Practices

• Record promptly: Create a decision record within 24 hours after a technical discussion ends so details are not forgotten.
• Keep it focused: Each decision addresses one issue; avoid mixing unrelated choices in the same file.
• Be transparent about status: Once a decision is superseded or deprecated, update its status to superseded or deprecated and reference the replacement in the body.
• Review regularly: Run backlog decision list each quarter to check for decisions that have remained in proposed for too long, and drive them to closure.