# Decider

> Architecture Decision Record (ADR) and architectural decision document management: templates, creation, search, supersession tracking, and INDEX maintenance.

- Skill: `zenobi-us/decider` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add zenobi-us/decider`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zenobi-us/decider/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: zenobi-us (https://skillmd.com/u/zenobi-us)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zenobi-us/decider

---


> **Never edit this file directly.** To make additions or modifications, edit the appropriate section in `./vstack.toml`. Then run `vstack refresh`.

# Decider

Manages Architecture Decision Records (ADRs) — represented in this skill as numbered `DXXX` architectural decision documents indexed in `INDEX.md` (by default under `docs/decisions/`) — with canonical templates, creation/update workflows, and a search CLI. Provides the single source of truth for decision entry format and lifecycle.

```bash
.agents/skills/decider/scripts/decisions <command> [options]
```

## Commands

| Command | Purpose | Output |
|---------|---------|--------|
| `search --issue [ID]` | Find decisions linked to an issue | JSON `[{id, decision, path}]` |
| `search "[KEYWORDS]"` | Ranked keyword search (AND, scored) | JSON `[{id, decision, path, score}]` |
| `search "a\|b"` | Regex OR search | JSON `[{id, decision, path}]` |
| `list` | List all active decisions | JSON `[{id, decision, path}]` |
| `next-id` | Get next available DXXX | Single `DXXX` line |
| `get [DXXX]` | Get decision details | JSON `{id, decision, status, date, path}` |

Options: `--limit N` (default: 5) for search results.

## Workflows

| Workflow | Trigger | Purpose |
|----------|---------|---------|
| `workflows/create-decision.md` | Research complete, significant path choice | Assign ID, write file, add INDEX row, update superseded |
| `workflows/update-decision.md` | New decision affects existing | Supersede, partial supersede, or revisit existing entries |
| `workflows/search-decisions.md` | Before implementing, reviewing, auditing | Search by issue, keywords, or ID |

## Templates

| Template | Purpose |
|----------|---------|
| `templates/decision-entry.md` | Decision file format (minimal, standard, comprehensive) |
| `templates/index-row.md` | INDEX.md table row format |

## Schemas

| Schema | Purpose |
|--------|---------|
| `schemas/decision-format.md` | Canonical format constraints for decision documents and INDEX |

Project-level configuration:

| Variable | Purpose | Default |
|----------|---------|---------|
| `$DECISIONS_DIR` | Path to decision documents directory | Auto-discovers `docs/decisions/`, `decisions/`, `doc/decisions/`, or `adr/` with `INDEX.md` |

Set `DECISIONS_DIR` in committed `vstack.settings.toml` under `[env]` when it is shared project policy. `.env.local` remains supported for local overrides.

If the decisions directory does not exist (never initialized), read-only lookups (`search`, `list`) emit an empty JSON array with a stderr note and exit 0 — no decisions recorded is not an error. `next-id` and `get` still require an initialized directory, and a configured path that exists but is not a directory is always a hard error.

## Decision Lifecycle

```
Research Complete → Create Decision (§ 6.1)
                        ↓
                 INDEX.md + DXXX-descriptor.md
                        ↓
            ┌───────────┴───────────┐
            ↓                       ↓
    Search/Reference         Update/Supersede
    (review, audit,          (new research,
     implementation)          revisit conditions met)
```

## Quick Reference

### Creating Decisions

1. Get next ID: `decisions next-id`
2. Select template size (minimal/standard/comprehensive) from `templates/decision-entry.md`
3. Write decision file to `[project decision documents]/[DECISION_ID]-[DESCRIPTOR].md`
4. Add row to `[project decision documents]/INDEX.md`
5. Update any partially superseded decisions

### Searching Decisions

1. By issue: `decisions search --issue [ISSUE_ID]`
2. By keywords: `decisions search "[RELEVANT_KEYWORDS]"`
3. Read full decision files — index summaries are insufficient for understanding scope and rejected alternatives
4. Suggestions contradicting active decisions are invalid unless decision is flawed

### Decision Entry Format

All entries require: title (`# DXXX: Title`), date, status, research ref (or `—`), decision statement, rationale, revisit conditions. See `schemas/decision-format.md` for full constraints.

## Decision Approval

Do not create decision documents without explicit user approval. If your work involves a significant architectural choice, technology selection, or trade-off that warrants a decision record, surface this in your response upon task completion — e.g., "This introduced a decision worth recording: [brief summary]. Want me to create a decision entry?" Let the user confirm before running the create workflow.

## Content Guidelines

### What to Log

- Technology selections with alternatives considered
- Performance trade-offs (chose X over Y for reason Z)
- Significant path choices where conditions might change
- Research-informed decisions

### What NOT to Log

- Variable names, small refactors, bug fixes
- Obvious choices with no realistic alternatives
- Standard pattern applications

## System Dependencies

- `bash` 4+
- `jq`
- GNU `grep` with `-P` (PCRE) support (`grep`, `ggrep`, or Homebrew `gnubin/grep`)
- `sed`, `find`