decision-log

Files (1)

• SKILL.md

SKILL.md (first lines)

# decision-log — capture the *why*, promote the important bits

> **Vendor-neutral skill.** Plain markdown any agent (Claude Code, Codex, Gemini CLI,
> OpenCode) can read and drive — it lives in this workspace's shared `skills/` dir per
> the convention in `CONTEXT.md`. Claude Code also exposes it as the `/decision` slash
> command (`.claude/commands/decision.md`, a thin wrapper around this skill).

Code is a snapshot with the decision history erased — `git blame` gives *what/when/who*,
never *why*. Intent is unrecoverable after the fact; you can only capture it *as you
decide*. This skill is that capture, at the cheapest tier that fits.

## The three tiers (capture cheap, promote the keepers)

```
Tier 3  ADR            docs/adr/NNNN-slug.md         committed · permanent · linkable
   ▲    promote at checkpoint (or on demand)
Tier 2  Decision note  work/<proj>/decisions.md      in-flight · per-project · ephemeral
   ▲    distilled from
Tier 1  Commit trailer git commit message            permanent · in-repo · machine-read
```

Default policy — deliberately light, so it doesn't die of ceremony:

- **Tier 1 — always.** Every non-trivial commit carries a one-line `Decision:` reason.
  (No-git workspace — no commits by design: Tier 1 is N/A; the wide net starts at
  Tier 2 — date every note.)
- **Tier 2 — for any choice with a rejected alternative.** If there was a real fork,
  append a note. This is the wide net: cheap, append-only, lives beside the work.
- **Tier 3 — only on promotion.** An ADR is earned, not automatic. Promote only when
  the decision passes the **AND test** — *hard to reverse* AND *surprising* AND *a
  real trade-off* (from upstream `domain-modeling`; same bar in `docs/adr/README.md`).
  If any leg is missing, skip. Most notes never become ADRs, and that's correct.

## Capture a decision (Tier 2 — the common case)

First, grep `decisions.md` for an earlier note on the same subject and classify
the new one as ADD, UPDATE, SUPERSEDE, or NOOP. The rule is in
`skills/checkpoint/SKILL.md` → "Classify before you write". UPDATE edits the
earlier note in place. SUPERSEDE appends the new note and adds a `**Retired:**`
line under the old note's heading. Both are allowed exceptions to the file
being append-only. Never delete a note.

For an ADD or a SUPERSEDE, append to `work/<project-name>/decisions.md` (create
it if absent), newest last:

```markdown
## YYYY-MM-DD — <what the decision is about>
**Chose:** <the approach>
**Because:** <the reason — the constraint or force that decided it>
**Rejected:** <alternative> — <one-line why it lost>; <alternative> — <why>
**Blast radius:** <files / symbols / flows this touches>
**Promote?:** no | maybe — <condition> | yes — <why it's ADR-worthy> | upstream — <template PR>
```

Append with a shell heredoc (`cat >> work/<project-name>/decisions.md <<'EOF' … EOF`)
— the file is append-only, and shell append lands the note without loading the
file into context (in a long-lived work item it can run to thousands of tokens).

Write it *when you decide*, not in a cleanup pass — the reasoning is freshest (and only)
in the moment. Keep it to the fork that mattered; skip decisions with no real alternative.
Never put secrets in it. It must read without the transcript — no "as decided above"
(`docs/work-directory-conventions.md` → "Readable without the transcript").

**Archive when it grows.** ~16KB (`wc -c`) is a *trigger*, not a size target:
when `decisions.md` passes it, move the settled notes — `Promote?:` reads `no`
or `done → ADR-NNNN` — to `decisions-archive.md` beside it (create on first
use, newest last). Open `maybe`/`yes` notes stay in place *regardless of the
size that leaves* — a long-lived work item can sit well above 16KB after a
sweep, and that's fine; don't churn trying to hit the number. If a single open
note grows outsized (10KB+), split it: keep the decision statement and
`Promote?:` line live, move the supporting detail to the archive with a
pointer. Same discipline as the handoff ledger: the live file stays cheap to
consult; history stays on disk.

Counter-example — *don't* log this: "picked `date-fns` over `dayjs` for a one-off
formatting helper". Reversible in minutes, either lib would do, no trade-off that
matters — that's a Tier-1 `Decision:` trailer at most, not a note.

Get the date from the system (`date +%F`) — don't guess it.

## Record it in the commit (Tier 1)

When the change lands, add trailers to the commit body so a graph can walk `commit → ADR`:

```
Decision: <the one-line reason>
Rejected: <the main alternative and why> <!-- optional -->
Refs: ADR-NNNN                            <!-- only if an ADR exists -->
```

## Promote a note to an ADR (Tier 3)

On demand, or when `checkpoint` flags a `Promote?: yes|maybe` note. Wayfinder maps
count too: a `work/<effort>/map.md` "Decisions so far" entry is a Tier-2 note and is
promoted the same way (per `docs/agents/issue-tracker.md` → "Decision-log tie-in").
Steps:

1. Pick the namespace by subject (see `docs/adr/README.md`). A decision about the
   **workspace machinery** the template ships (skills, scripts, session and
   decision conventions) is a template ADR, `TADR-NNNN` in `docs/template-adr/`:
   write it there only in the template repo itself. In an instance, leave it a
   Tier-2 note marked `Promote?: upstream` and propose the TADR to the template —
   the template assigns the number, and a local one collides at the next sync.
   Everything else is the project's: cross-repo or workspace decisions →
   `docs/adr/` (the default); a decision contained in one product repo → that
   repo's `repos/<repo>/docs/adr/`. `ls <adr-dir>/` → next free `NNNN`
   (zero-padded, never reuse a number; each directory's sequence is independent).
2. Copy `<adr-dir>/0000-template.md` → `<adr-dir>/NNNN-kebab-slug.md` (a product
   repo without one uses `docs/adr/0000-template.md`); fill Context /
   Decision / Alternatives / Consequences from the note (expand, don't just paste).
3. Fill the **Provenance** block: `Promoted from:` the note anchor, `Commits:` the shas,
   `Supersedes:` any ADR this replaces (and set that ADR's status to
   `superseded by ADR-NNNN`).
4. Set `Status: accepted` and today's date; add it to that directory's `README.md`
   index (`docs/adr/` or `docs/template-adr/`).
5. Flip the note's `Promote?:` to `done → ADR-NNNN` (or `TADR-NNNN`) so it isn't
   re-promoted next checkpoint.
6. If a graph exists (`graphify-out/graph.json`), run `graphify update .` so the ADR's
   edges enter the graph.

From kashman001/ai-workspace-template, MIT.

More from kashman001/ai-workspace-template