Decisions

Why things happened: log it when you decide, supersede it when you change course.

Code shows WHAT was built and git shows WHO and WHEN. Decisions record the missing piece: WHY. A decision is one line plus its reason, logged the moment you make the call, from the same terminal you made it in. Six months later, when someone (or some agent) asks why the app works this way, the answer is one command away instead of buried in a chat thread. And when you change course, you never erase history: the old decision stays, pointing at the one that replaced it.

1. Step 1 of 5

   Log it the moment you decide

   One line, plus the reason. The title says what you chose; --why says what you knew when you chose it. The reason is the valuable half: it is what lets future readers judge whether the decision still applies.

   plm decide

   $ plm decide "ship chapters one at a time" --why "a 156-command page overwhelmed readers"

   ✓ decision dec_1f04b2c8 — ship chapters one at a time

   full form · plm decide "<title>" [--why "…"]

2. Step 2 of 5

   Read the log before you re-litigate

   The list shows every decision with its author, date, and reason. Newest first; --tail flips to the oldest. This is the first thing to read before proposing a change: maybe it was already decided, and maybe the reason no longer holds, which is exactly the conversation to have.

   plm decisions

   $ plm decisions --head 2

   12 decisions · showing 2 newest

   dec_1f04b2c8 2026-07-12 edvard — ship chapters one at a time

   a 156-command page overwhelmed readers

   dec_9c22e0a4 2026-07-10 edvard — agents live on the hub, no local copies [2 comments]

   two working copies of a living thing always diverge

   full form · plm decisions [--head N|--tail N|--n N]

3. Step 3 of 5

   Changed your mind? Supersede, never delete

   Log the new decision first, then close the old one by pointing at its successor. The history stays honest: anyone reading the old decision sees it was superseded and by what. Deleting is reserved for admins and mistakes, not for changed minds.

   plm decision · supersede

   $ plm decision dec_1f04b2c8 --status superseded --superseded-by dec_4b8d11f0

   ✓ updated dec_1f04b2c8 (status, superseded_by)

   full form · plm decision <dec_…> --status superseded --superseded-by <dec_…>

4. Step 4 of 5

   Keep the reason honest

   A decision is editable by its author: sharpen the title, expand the why. Updating the reason is not rewriting history, it is documenting it better. The list always shows the current wording.

   plm decision · update

   $ plm decision dec_4b8d11f0 --why "chapters release one at a time; the overview is a table of contents"

   ✓ updated dec_4b8d11f0 (body)

   full form · plm decision <dec_…> [--title "…"] [--why "…"]

5. Step 5 of 5

   Discuss it where it lives

   Comments attach to the decision itself, not to a chat that scrolls away. Disagreement, context, links to evidence: put them on the record, next to the thing they are about.

   plm comment

   $ plm comment dec_4b8d11f0 "the git chapter landing first proved this: readers finish it"

   ✓ commented on dec_4b8d11f0

   full form · plm comment <dec_…> "<text>"

Also in this chapter

• Decisions are project-scoped: run inside a linked repo (plm link <project-slug>).
• Statuses: active or superseded. A superseded decision keeps its full text and points at its successor via superseded_by.
• Updates are author-or-admin only; hard delete is admin only and destructive. Supersede instead.