/decision

description: Record, list, and manage project decisions with rationale tracking
argument-hint: "record|list|show|supersede"

Record and track project decisions as beads issues with structured rationale, alternatives considered, and links to affected work.

Decisions use `--type decision`. The description field holds the structured decision record.

Record a Decision

When the user wants to record a decision (i.e. the `record` action of this command):

1. Gather the following (ask if not provided):

• **Title**: Short summary of what was decided (required)
• **Rationale**: Why this was chosen (required)
• **Alternatives**: What else was considered (optional but encouraged)
• **Affects**: Issue IDs this decision impacts (optional)
• **Priority**: How important (default P2)

2. Create the issue with structured description:

bd create "<title>" --type decision \
  --description "$(cat <<'EOF'
## Decision

<one-sentence summary of what was decided>

## Rationale

<why this was chosen>

## Alternatives Considered

- **<alt 1>**: <why rejected>
- **<alt 2>**: <why rejected>

## Affects

- <issue IDs or area descriptions>
EOF
)"

3. If `--affects` issue IDs were provided, link them:

bd dep add <decision-id> <affected-id> --type related

4. Show the created decision to the user.

List Decisions

bd list --type decision

To see all decisions including closed/superseded:

bd list --type decision --all

Show a Decision

bd show <decision-id>

Include comments for discussion history:

bd comments <decision-id>

Supersede a Decision

When a decision is replaced by a new one:

1. Record the new decision (as above) 2. Link the new decision to the old one:

   bd dep add <new-id> <old-id> --type related

3. Add a comment on the old decision:

   bd comments add <old-id> "Superseded by <new-id>: <brief reason>"

4. Close the old decision:

   bd close <old-id> --reason "Superseded by <new-id>"

Add Context to an Existing Decision

Use comments to append discussion, implementation notes, or revisit rationale:

bd comments add <decision-id> "Implementation note: ..."

Search Decisions

bd search "keyword" --type decision

Conventions

• **Status**: `open` = active decision, `closed` = superseded or reversed
• **Description format**: Use the structured template above for consistency
• **Linking**: Use `related` dependency type to connect decisions to affected issues
• **Labels**: Use labels for categorizing decisions (e.g., `architecture`, `tooling`, `process`)