Decisions

The Decisions plugin keeps what was decided about the blueprints as records of their own: one markdown file per decision in the root’s decisions/ folder, each made for the blueprints and tasks it names by their permanent ids. A decision is not a blueprint and not a task: never a collection item, never checked as one, never in the index. It is small, closer to a comment than to a task: a title that says what was decided, a type, a status, who logged it, and notes on why. An agent that decides something on its own while working logs it as itself, for a person to confirm. Off by default; eidos plugin enable decisions switches it on and declares the folder.

In the browser

Decisions, an activity in the Activity Bar with the count of unconfirmed decisions on its icon: All decisions, Unconfirmed (the inbox, with its count), Assigned to me (the unconfirmed decisions handed to you, with their count), the table’s saved views under Decision views, By status, By type, and the settings at its foot.
The Decisions table: a row per decision with its type as an icon before the title and its id, its status and its assignee changed in the row, who logged it, the blueprints, and the days created and confirmed. It filters by category, status, type, assignee, blueprint, and who logged it, with a search box leading the filters as on every table, and any filter is kept as a shared or local view with Save as view. A right-click on a row opens its menu: Open, Open as a page, Confirm, Assign to me, Copy id, the ways out to the file, and Delete.
A decision opens in a modal from the table or a blueprint, with Expand for its own page, built as a task’s reader is: the properties edited in place, the notes in Reading and Editor, the file as Source, Confirm while it is unconfirmed, and Comments’ threads at the foot.
On the Home, Decisions assigned to you lists the unconfirmed decisions handed to you, so one passed to you to confirm or to act on is seen there; once it is confirmed or set aside it leaves the card.
New decision, from the page or the activity, asks for the type and the decision in a line, then makes the file and opens it.
In a blueprint, each decisions:log region is drawn as the live list of the decisions made for it, with Confirm on an unconfirmed one and Log a decision, which logs one for the blueprint in the section’s first type. Decisions, a view in the Auxiliary Sidebar, lists the open blueprint’s.
The plugin’s settings page holds the statuses (each with its category and colour), the default status, the Decision types (a name, title, icon, colour, and what it is for), and the default type.

The decision file

Frontmatter: id (the decision’s permanent id, given when it is made, in three parts: D- for any decision as a task’s is T-, then the decision type’s prefix when it has one, then letters or digits; so D-7M2P for a type with no prefix, and D-SF36 for a scope type whose prefix is S, the S after D- and never in its place), aliases (the ids the decision was known by before, kept when its id changes; each still reaches it wherever an id does), title (the decision itself, in a line), type (one the root declares), status, author (the alias of the root user who logged it, an agent’s own when an agent logged it), assignee (the aliases of the root users it is handed to, to confirm it or to act on it), blueprints (the ids of the blueprints it was made for), tasks (the ids of the Backlog tasks it was made for), created, updated, confirmed (the day it crossed into a confirmed status) and confirmed_by (who took it there), and any property the root declares in the plugin’s settings.

The body is the notes: why, what else was weighed, what it rules out. It has no sections the root declares. The file is named by the id and the first words of the title, as many whole words as fit in 40 characters in the root’s naming convention (d-7m2p-cache-the-index-in-memory.md in kebab-case), so a path stays short enough for Windows however long the title runs. A retitle that changes those words renames the file, through Git where it is on, and every link to it follows. A command takes a decision by its id or its file name. An id can be given by hand (add --id) or changed later (set --id, or the pencil beside the id in a decision’s head): the new one must not be any decision’s id or former id, in any case, and a change renames the file, keeps the old id as an alias, and rewrites every reference in the root. A decision is a Comments host addressed by its id (decisions:D-…); a thread on it, and an @mention in the thread, is how someone is asked about it.

Types and statuses

types keeps kinds of decision apart, so a development decision an agent made on its own is never mistaken for a scope decision or one a meeting settled. Each is a name (the decision’s type), a title, an icon and a colour, and a meaning. A root starts with three:

Development: how it is built, an approach, a library, or a trade-off chosen while building it. An agent logs one it made on its own. add takes it when no type is given (default_type).
Scope: what is in and what is out, a behavior promised or dropped, a boundary drawn.
Meeting: what a meeting settled, logged from its notes by whoever has them.

A type may also have an ID prefix, letters a new decision of the type wears after D- and before its value: a scope type with S gives D-SF36, and each Decision types card shows the id a new decision gets as you type the letters, and eidos decisions types lists it as ids D-S…. The value after the prefix is unique among every decision whatever prefix it wears. A decision whose type changes takes the new type’s prefix, its value kept, its old id kept as an alias, and its file renamed for the new id. A prefix applies to new decisions; once one is saved, the Decision types tab says how many decisions were written before it and offers to re-ID them, which eidos decisions reid does from the shell.

statuses is the root’s ordered list, each in one of three categories (status_categories): unconfirmed (waiting on whoever decides: the inbox), confirmed, or closed (set aside without being confirmed). A status not named is unconfirmed. A status crossing into the confirmed category stamps confirmed with the day and confirmed_by with who took it there; leaving it clears both. The default is Proposed, Confirmed, Rejected, and Superseded, with a new decision landing in default_status, Proposed. There is no priority.

Where a blueprint shows its decisions

In Framework Settings → Templates, each section of a template has a type beside its heading: Text, the default, Decisions, or Tasks (where the Backlog lists the tasks that serve the blueprint), each offered while its plugin is on. A Decisions section names the decision types it shows (none is every type), keeps its intent (a type’s meaning fills an empty one) and any default content, and writes a region at the end of its body:

## Constraints & Decisions

<!-- decisions:log types=development,scope -->
<!-- /decisions:log -->

A blueprint made from the template carries the region under that heading, and the plugin writes into it, after any change, every decision made for the blueprint: each in the first region that collects its type, as a line with its title linked to its file, its id, its status, and its author, ticked once confirmed. A decision whose type only a section the blueprint lacks collects gets that section, its heading added in the template’s order; one whose type no section of the template collects shows nowhere in the text, only in the Decisions view beside the blueprint. A blueprint with no decision and no region is not touched. The link lives on the decision; never type into the region.

On disk

decisions/ (or any folder declared owned_by: "@decisions/records"): the decisions, one file each. The root →
.eidos/plugins/decisions/settings.yaml, shared: statuses, status_categories, status_colors, default_status, types, default_type, and properties. The root’s own decision properties are declared here by hand for now.

From the shell

eidos decisions                                     # every decision, grouped by category
eidos decisions --unconfirmed                       # the inbox; --status, --type, --blueprint, --task, --author, --assignee, --where key=value, --search, --json
eidos decisions add "Cache the index in memory" --type development --for @search --task T-4KQ7 --notes "Why, and what else was weighed" --as agent
eidos decisions show D-7M2P                         # a decision by its id, or by its file name
eidos decisions set D-7M2P --status Rejected        # --title, --type, --for, --task, --assignee, --notes, --property name=value
eidos decisions set D-7M2P --id D-CACHE             # a new id: the file renamed for it, the old kept as an alias, every reference following
eidos decisions configure:type set scope --prefix S  # new scope decisions are D-S…; "" clears it
eidos decisions configure:status add Postponed --category closed --color orange --position 2  # a status; set|rename|remove, --default, --dry-run
eidos decisions configure:status rename Postponed Parked  # the decisions in it follow, their dates kept
eidos decisions configure:status remove Parked --to Rejected  # refused while decisions are in it, unless --to (same category) or --force
eidos decisions configure:type add research --icon star --color teal --meaning "What a study found"  # a type; set|rename|remove, --default
eidos decisions reid --type scope --dry-run         # how many decisions would take the prefix; --was <old>, --yes to write
eidos decisions reid --scheme --yes                 # also redraw the ids drawn under another id scheme than the root's
eidos decisions confirm D-7M2P D-9XQ4               # to the first confirmed status; --as
eidos decisions types                               # the types and what each is for; statuses lists the statuses
eidos decisions project                             # rewrite every decisions:log region that drifted; or one blueprint
eidos decisions rename-files --dry-run              # every decision named the old way, old name to new; without --dry-run, renamed with every link
eidos decisions remove D-7M2P                       # delete a decision, as the page's Delete does

Every command takes --json. A write is signed with --as <alias>, else EIDOS_USER, else the acting user, and the alias is kept as the decision’s author (or its confirmed_by); an alias that is nobody is refused with the eidos users add that creates it. Every write stamps updated.

An agent logs a decision it made itself as it makes it, as itself, attached to the blueprints and tasks it concerns: it adds itself once with eidos users add "<Its name>" --alias <alias> --agent when eidos users does not list it, and passes --as <alias> on every add. It never confirms, rejects, or changes the status of a decision it logged; the owner does that.

What the check reports

decisions/blueprint-missing (a decision names a blueprint the root does not have), decisions/task-missing (a task the backlog does not have), decisions/status-unknown, decisions/type-unknown, decisions/id-missing, decisions/id-duplicate (two files holding one id), decisions/alias-taken (a former id kept in aliases that another decision holds as its id), decisions/alias-duplicate (a former id two decisions keep), decisions/id-draft (under the sequential id scheme, a draft id still on the default branch; eidos ids finalize gives it its number), decisions/region-stale (a blueprint whose decisions:log regions are not what its decisions would write; Project fixes it), and decisions/file-name (a decision whose file is not named by its id and the first words of its title, as one logged before 0.10.1 is; Rename fixes one and eidos decisions rename-files every one, links and all, which you then commit). Reading a root never renames a file. Off again, the folder and its decisions stay where they are, and nothing of the plugin runs.