feat: add decision as built-in issue type

Projects track what they're doing (issues) and what happened (events),
but not why they chose a particular approach. Decisions are a missing
first-class concept -- every project has them, they're distinct from
tasks, and they're the context hardest to recover after the fact.

Adds TypeDecision as a core work type alongside bug/feature/task/epic/chore.
Includes aliases (dec, adr), required sections template (Decision, Rationale,
Alternatives Considered), and a Claude plugin command for structured recording.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Executed-By: beads/crew/emma
Rig: beads
Role: crew
This commit is contained in:
mayor 2026-02-12 00:42:50 +01:00 • committed by Steve Yegge
commit aba0cab3cd
16 changed files with 156 additions and 25 deletions

View file

@ -0,0 +1,111 @@
---
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 (or you invoke `bd decision record`):
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:
```bash
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:
```bash
bd dep add <decision-id> <affected-id> --type related
```
4. Show the created decision to the user.
## List Decisions
```bash
bd list --type decision
```
To see all decisions including closed/superseded:
```bash
bd list --type decision --all
```
## Show a Decision
```bash
bd show <decision-id>
```
Include comments for discussion history:
```bash
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:
```bash
bd dep add <new-id> <old-id> --type related
```
3. Add a comment on the old decision:
```bash
bd comments add <old-id> "Superseded by <new-id>: <brief reason>"
```
4. Close the old decision:
```bash
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:
```bash
bd comments add <decision-id> "Implementation note: ..."
```
## Search Decisions
```bash
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`)

View file

@ -311,7 +311,7 @@ func init() {
countCmd.Flags().StringP("status", "s", "", "Filter by status (open, in_progress, blocked, deferred, closed)")
countCmd.Flags().IntP("priority", "p", 0, "Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)")
countCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
countCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate)")
countCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate)")
countCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL)")
countCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE)")
countCmd.Flags().String("title", "", "Filter by title text (case-insensitive substring match)")

View file

@ -776,7 +776,7 @@ func init() {
createCmd.Flags().Bool("silent", false, "Output only the issue ID (for scripting)")
createCmd.Flags().Bool("dry-run", false, "Preview what would be created without actually creating")
registerPriorityFlag(createCmd, "2")
createCmd.Flags().StringP("type", "t", "task", "Issue type (bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event); enhancement is alias for feature")
createCmd.Flags().StringP("type", "t", "task", "Issue type (bug|feature|task|epic|chore|decision|merge-request|molecule|gate|agent|role|rig|convoy|event); aliases: enhancement/feat→feature, dec/adr→decision")
registerCommonIssueFlags(createCmd)
createCmd.Flags().String("spec-id", "", "Link to specification document")
createCmd.Flags().StringSliceP("labels", "l", []string{}, "Labels (comma-separated)")

View file

@ -393,13 +393,14 @@ func TestCreateIssueFromFormValues(t *testing.T) {
})
t.Run("AllIssueTypes", func(t *testing.T) {
issueTypes := []string{"bug", "feature", "task", "epic", "chore"}
issueTypes := []string{"bug", "feature", "task", "epic", "chore", "decision"}
expectedTypes := []types.IssueType{
types.TypeBug,
types.TypeFeature,
types.TypeTask,
types.TypeEpic,
types.TypeChore,
types.TypeDecision,
}
for i, issueType := range issueTypes {

View file

@ -212,7 +212,7 @@ func findUnknownTypesInHydratedIssues(repoPath string, multiRepo *config.MultiRe
// Collect all known types (core work types + parent custom + all child custom)
// Only core work types are built-in; Gas Town types require types.custom config.
knownTypes := map[string]bool{
"bug": true, "feature": true, "task": true, "epic": true, "chore": true,
"bug": true, "feature": true, "task": true, "epic": true, "chore": true, "decision": true,
}
// Add parent's custom types

View file

@ -787,7 +787,7 @@ func init() {
listCmd.Flags().StringP("status", "s", "", "Filter by status (open, in_progress, blocked, deferred, closed)")
registerPriorityFlag(listCmd, "")
listCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
listCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule")
listCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision")
listCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL). Can combine with --label-any")
listCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE). Can combine with --label")
listCmd.Flags().String("label-pattern", "", "Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)")

View file

@ -656,7 +656,7 @@ func init() {
migrateIssuesCmd.Flags().String("to", "", "Destination repository (required)")
migrateIssuesCmd.Flags().String("status", "", "Filter by status (open/closed/all)")
migrateIssuesCmd.Flags().Int("priority", -1, "Filter by priority (0-4)")
migrateIssuesCmd.Flags().String("type", "", "Filter by issue type (bug/feature/task/epic/chore)")
migrateIssuesCmd.Flags().String("type", "", "Filter by issue type (bug/feature/task/epic/chore/decision)")
migrateIssuesCmd.Flags().StringSlice("label", nil, "Filter by labels (can specify multiple)")
migrateIssuesCmd.Flags().StringSlice("id", nil, "Specific issue IDs to migrate (can specify multiple)")
migrateIssuesCmd.Flags().String("ids-file", "", "File containing issue IDs (one per line)")

View file

@ -39,7 +39,7 @@ Boolean operators (case-insensitive):
Supported fields:
status Issue status (open, in_progress, blocked, deferred, closed)
priority Priority level (0-4)
type Issue type (bug, feature, task, epic, chore)
type Issue type (bug, feature, task, epic, chore, decision)
assignee Assigned user (use "none" for unassigned)
owner Issue owner
label Issue label (use "none" for unlabeled)

View file

@ -329,7 +329,7 @@ func init() {
searchCmd.Flags().String("query", "", "Search query (alternative to positional argument)")
searchCmd.Flags().StringP("status", "s", "", "Filter by status (open, in_progress, blocked, deferred, closed)")
searchCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
searchCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate)")
searchCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate)")
searchCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL)")
searchCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE)")
searchCmd.Flags().IntP("limit", "n", 50, "Limit results (default: 50)")

View file

@ -136,7 +136,7 @@ create, update, show, or close operation).`,
customTypes = config.GetCustomTypesFromYAML()
}
if !types.IssueType(issueType).IsValidWithCustom(customTypes) {
validTypes := "bug, feature, task, epic, chore"
validTypes := "bug, feature, task, epic, chore, decision"
if len(customTypes) > 0 {
validTypes += ", " + joinStrings(customTypes, ", ")
}
@ -408,7 +408,7 @@ func init() {
updateCmd.Flags().StringP("status", "s", "", "New status")
registerPriorityFlag(updateCmd, "")
updateCmd.Flags().String("title", "", "New title")
updateCmd.Flags().StringP("type", "t", "", "New type (bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event|slot)")
updateCmd.Flags().StringP("type", "t", "", "New type (bug|feature|task|epic|chore|decision|merge-request|molecule|gate|agent|role|rig|convoy|event|slot)")
registerCommonIssueFlags(updateCmd)
updateCmd.Flags().String("spec-id", "", "Link to specification document")
updateCmd.Flags().String("acceptance-criteria", "", "DEPRECATED: use --acceptance")

View file

@ -214,7 +214,7 @@ await beads_ready_work(workspace_root="/Users/you/project-a")
**Tools (all support `workspace_root` parameter):**
- `init` - Initialize bd in current directory
- `create` - Create new issue (bug, feature, task, epic, chore)
- `create` - Create new issue (bug, feature, task, epic, chore, decision)
- `list` - List issues with filters (status, priority, type, assignee)
- `ready` - Find tasks with no blockers ready to work on
- `show` - Show detailed issue info including dependencies

View file

@ -14,7 +14,7 @@ from pydantic import BaseModel, Field, field_validator
#
# The CLI handles validation of these values against the configured options.
# Built-in statuses: open, in_progress, blocked, deferred, closed
# Built-in types: bug, feature, task, epic, chore
# Built-in types: bug, feature, task, epic, chore, decision
IssueStatus = str
IssueType = str
DependencyType = Literal["blocks", "related", "parent-child", "discovered-from"]

View file

@ -385,7 +385,7 @@ async def get_tool_info(tool_name: str) -> dict[str, Any]:
"parameters": {
"status": "open|in_progress|blocked|deferred|closed or custom (optional)",
"priority": "int 0-4 (optional)",
"issue_type": "bug|feature|task|epic|chore or custom (optional)",
"issue_type": "bug|feature|task|epic|chore|decision or custom (optional)",
"assignee": "str (optional)",
"labels": "list[str] (optional) - AND filter: must have ALL labels",
"labels_any": "list[str] (optional) - OR filter: must have at least one",
@ -421,7 +421,7 @@ async def get_tool_info(tool_name: str) -> dict[str, Any]:
"title": "str (required)",
"description": "str (default '')",
"priority": "int 0-4 (default 2)",
"issue_type": "bug|feature|task|epic|chore or custom (default task)",
"issue_type": "bug|feature|task|epic|chore|decision or custom (default task)",
"assignee": "str (optional)",
"labels": "list[str] (optional)",
"deps": "list[str] (optional) - dependency IDs",
@ -862,7 +862,7 @@ async def list_issues(
Args:
status: Filter by status (open, in_progress, blocked, closed)
priority: Filter by priority level (0-4)
issue_type: Filter by type (bug, feature, task, epic, chore)
issue_type: Filter by type (bug, feature, task, epic, chore, decision)
assignee: Filter by assignee
labels: Filter by labels (AND: must have ALL specified labels)
labels_any: Filter by labels (OR: must have at least one)
@ -964,7 +964,7 @@ async def show_issue(
@mcp.tool(
name="create",
description="""Create a new issue (bug, feature, task, epic, or chore) with optional design,
description="""Create a new issue (bug, feature, task, epic, chore, or decision) with optional design,
acceptance criteria, and dependencies.""",
)
@with_workspace

View file

@ -394,7 +394,7 @@ async def beads_ready_work(
async def beads_list_issues(
status: Annotated[IssueStatus | None, "Filter by status (open, in_progress, blocked, deferred, closed, or custom)"] = None,
priority: Annotated[int | None, "Filter by priority (0-4, 0=highest)"] = None,
issue_type: Annotated[IssueType | None, "Filter by type (bug, feature, task, epic, chore, or custom)"] = None,
issue_type: Annotated[IssueType | None, "Filter by type (bug, feature, task, epic, chore, decision, or custom)"] = None,
assignee: Annotated[str | None, "Filter by assignee"] = None,
labels: Annotated[list[str] | None, "Filter by labels (AND: must have ALL)"] = None,
labels_any: Annotated[list[str] | None, "Filter by labels (OR: must have at least one)"] = None,
@ -438,7 +438,7 @@ async def beads_create_issue(
acceptance: Annotated[str | None, "Acceptance criteria"] = None,
external_ref: Annotated[str | None, "External reference (e.g., gh-9, jira-ABC)"] = None,
priority: Annotated[int, "Priority (0-4, 0=highest)"] = 2,
issue_type: Annotated[IssueType, "Type: bug, feature, task, epic, chore, or custom"] = DEFAULT_ISSUE_TYPE,
issue_type: Annotated[IssueType, "Type: bug, feature, task, epic, chore, decision, or custom"] = DEFAULT_ISSUE_TYPE,
assignee: Annotated[str | None, "Assignee username"] = None,
labels: Annotated[list[str] | None, "List of labels"] = None,
id: Annotated[str | None, "Explicit issue ID (e.g., bd-42)"] = None,

View file

@ -501,11 +501,12 @@ type IssueType string
// Core work type constants - these are the built-in types that beads validates.
// All other types require configuration via types.custom in config.yaml.
const (
TypeBug IssueType = "bug"
TypeFeature IssueType = "feature"
TypeTask IssueType = "task"
TypeEpic IssueType = "epic"
TypeChore IssueType = "chore"
TypeBug IssueType = "bug"
TypeFeature IssueType = "feature"
TypeTask IssueType = "task"
TypeEpic IssueType = "epic"
TypeChore IssueType = "chore"
TypeDecision IssueType = "decision"
)
// TypeEvent is a system-internal type used by set-state for audit trail beads.
@ -520,11 +521,11 @@ const TypeEvent IssueType = "event"
// (event was also a Gas Town type but was promoted to a built-in internal type above.)
// IsValid checks if the issue type is a core work type.
// Only core work types (bug, feature, task, epic, chore) are built-in.
// Only core work types (bug, feature, task, epic, chore, decision) are built-in.
// Other types (molecule, gate, convoy, etc.) require types.custom configuration.
func (t IssueType) IsValid() bool {
switch t {
case TypeBug, TypeFeature, TypeTask, TypeEpic, TypeChore:
case TypeBug, TypeFeature, TypeTask, TypeEpic, TypeChore, TypeDecision:
return true
}
return false
@ -560,6 +561,8 @@ func (t IssueType) Normalize() IssueType {
switch strings.ToLower(string(t)) {
case "enhancement", "feat":
return TypeFeature
case "dec", "adr":
return TypeDecision
default:
return t
}
@ -589,6 +592,12 @@ func (t IssueType) RequiredSections() []RequiredSection {
return []RequiredSection{
{Heading: "## Success Criteria", Hint: "Define high-level success criteria"},
}
case TypeDecision:
return []RequiredSection{
{Heading: "## Decision", Hint: "Summarize what was decided"},
{Heading: "## Rationale", Hint: "Explain why this option was chosen"},
{Heading: "## Alternatives Considered", Hint: "List alternatives and why they were rejected"},
}
default:
// Chore and custom types have no required sections
return nil

View file

@ -545,6 +545,7 @@ func TestIssueTypeIsValid(t *testing.T) {
{TypeTask, true},
{TypeEpic, true},
{TypeChore, true},
{TypeDecision, true},
// Gas Town types are now custom types (not built-in)
{IssueType("message"), false},
{IssueType("merge-request"), false},
@ -621,6 +622,14 @@ func TestEventTypeValidation(t *testing.T) {
if TypeEvent.Normalize() != TypeEvent {
t.Errorf("TypeEvent.Normalize() = %q, want %q", TypeEvent.Normalize(), TypeEvent)
}
// decision aliases
if IssueType("dec").Normalize() != TypeDecision {
t.Errorf("IssueType(dec).Normalize() = %q, want %q", IssueType("dec").Normalize(), TypeDecision)
}
if IssueType("adr").Normalize() != TypeDecision {
t.Errorf("IssueType(adr).Normalize() = %q, want %q", IssueType("adr").Normalize(), TypeDecision)
}
}
func TestIssueTypeRequiredSections(t *testing.T) {
@ -633,6 +642,7 @@ func TestIssueTypeRequiredSections(t *testing.T) {
{TypeFeature, 1, "## Acceptance Criteria"},
{TypeTask, 1, "## Acceptance Criteria"},
{TypeEpic, 1, "## Success Criteria"},
{TypeDecision, 3, "## Decision"},
{TypeChore, 0, ""},
// Gas Town types are now custom and have no required sections
{IssueType("message"), 0, ""},