decisions

name	decisions
description	Record durable architectural or policy choices with `mt decision`. Use when choosing between alternatives, setting lasting constraints, superseding an accepted decision, or capturing significant rationale while context is fresh.

Decisions

Overview

Use mt decision for durable choices that change how the system should behave or what future work must respect.

When to use

• A significant tradeoff or architectural choice was just made.
• A new constraint should guide future implementation.
• An accepted decision needs to be deprecated or superseded.
• The user asks for an ADR-style writeup or wants rationale captured explicitly.
• During implementation or review, code forced a contract-affecting assumption (→ decision candidate).

Core rules

• Record the decision immediately with mt decision new while the context is fresh.
• Link the decision to affected specs or tasks rather than burying the rationale in a comment.
• Treat accepted decisions as immutable; create a superseding decision instead of rewriting history.
• Use comments for ephemeral progress. Use decisions for durable reasoning and constraints.

Workflow

1) Pull current context

• mt search <topic>
• mt show <spec-or-task-id>
• Check whether an existing decision already captures the choice before creating a new one.

2) Create the decision

Prefer file/stdin input for rationale:

cat <<'EOF' | mt decision new --title "Use gate-based delivery contracts for workstreams" --source <task-or-spec-id> --rationale-file -
Context:
- We need deterministic recovery for PR-backed workstreams.

Decision:
- Gates, not generic workflows, define what remains before successful completion.

Consequences:
- Runtime completion checks inspect durable gate state.
- Reviewer and merge coordination happen through gate handoffs.
EOF

3) Link it to the right intent

• Use --source <task-or-spec-id> when the decision comes from current work.
• Add explicit links when needed:

mt link --from <decision-id> --rel affects --to-spec <spec-id>

4) Update later by superseding, not rewriting

• Statuses: proposed, accepted, deprecated, superseded
• If an accepted decision is no longer right, create a new decision and mark the old one superseded or deprecated instead of mutating the original rationale.

Decision candidates (provisional capture during implementation)

A decision candidate is a contract-affecting assumption discovered during implementation or code review — not yet a full decision.

When to capture a candidate

Record a candidate when implementation introduces behavior that:

• Changes the truth value of an existing guarantee or constraint, OR
• Creates an undeclared guarantee or constraint (new behavioral surface the system is now silently committed to).

The second category is more dangerous — undeclared guarantees become load-bearing through usage rather than intent.

How to capture

Create the candidate as a first-class decision in proposed status so it is queryable and linkable:

cat <<'EOF' | mt decision new --status proposed --title "Chose WAL mode for SQLite" --source <task-id> --rationale-file -
Context:
- Spec says "persist records to SQLite" but does not specify journal mode.

Decision:
- Using WAL mode for concurrent read support.

Consequences:
- Introduces concurrent-reader guarantees and checkpoint requirements not in spec.
EOF

Link it to affected specs: mt link --from <decision-id> --rel affects --to-spec <spec-id>

Resolution at closeout

All proposed decisions linked to the current work must be resolved before closeout/merge. They are never auto-promoted on age alone. For each candidate:

• Fold into spec — the spec was incomplete. Update the guarantee/constraint, then deprecate the proposed decision.
• Accept — a durable tradeoff. mt decision update <id> --status accepted.
• Discard — implementation detail with no contract impact. mt decision update <id> --status deprecated with rationale.

High-severity candidates block merge

Unresolved candidates in these domains block merge:

• Security / privacy
• Money / billing
• Compatibility / migration
• Data shape / API contract changes

Significance threshold

Use the same threshold as for full decisions: user-visible behavior, security/privacy, money/billing, compatibility/migration, data shape/API contract, cross-spec invariants, objective tradeoffs (e.g. latency vs cost). Below this threshold, the choice is discretion — no candidate needed.

Practical rules

• A good title states the choice, not the meeting topic.
• Capture the alternative you rejected when it materially affects future readers.
• Keep rationale concrete: what problem existed, what choice was made, and what downstream constraints follow.
• If you need a broader spec/task breakdown alongside the decision, use the sibling planning/ skill.

Reference

• For a longer ADR-style template, open ../planning/references/decision-template.md.