---
name: convention-decision-log
type: convention
description: >-
  The tool-agnostic standard for the decision log — what it records, the
  index-plus-weekly-child-documents structure, the entry format, and the
  lifecycle (append newest-first, one entry per decision, update rather than
  leave a stale one). Read whenever recording or organising a consequential
  decision. The discipline holds even if the tracker changes; convention-linear
  maps it onto Linear documents. Grown as the format solidifies.
---

# Decision log

How consequential decisions are recorded so the reasoning survives the session that made it. Stated independently of any tracker, so it survives a change of tool — `convention-linear` is the tool layer that maps this onto Linear documents. The failure mode is silent: a decision made in chat and never logged does not persist, and the next session re-litigates it or contradicts it.

## What it records

A decision log captures every **consequential architectural, structural, or scope decision** — what was decided, why, and what changes as a result. Not every choice: a reversible, low-blast-radius call does not need an entry; a decision that future work will depend on, or be confused by if it is missing, does.

Logs are **scoped per domain**, one log per project/area, sharing this format:

- `osclaude.log-decisions` — how Claude is operated (skills, routines, the delivery loop, the conventions).
- `build.log-decisions` — careerOS infrastructure and build.
- `app.log-decisions` — AI-behaviour experiments.
- `a1-<client>.log-decisions` — one log per A1 client engagement (see *Slug naming* below).

## Slug naming

A log's slug follows its project, with one fixed rule for the families that need it:

- **A1 client engagements** use a **hyphenated `a1-` prefix** then the client name: `a1-<client>.log-decisions`, with weekly children `a1-<client>.log-decisions.YYYY-Www` (e.g. `a1-firmup.log-decisions`). The prefix is hyphenated; the rest follows the project name. Set when the engagement is scaffolded, so the next client does not re-derive it (worked case: `a1firmup` corrected to `a1-firmup`, 2026-06-27).
- **Other domains** use the established stems above (`osclaude.`, `build.`, `app.`). A new domain takes a short stem matching its project and is added to the list here when first stood up.

## Structure — index plus weekly child documents

A log is an **index** plus **child documents**, not one ever-growing page:

- The **index** holds this purpose, the entry format, and a table listing the child documents, each linking to one. It is the scannable front page.
- Each **child document** holds the full entries for one **ISO week** (`<log-name>.YYYY-Www`), newest entry at the top.

Weekly is the bucket because each document must stay **small enough to append safely** — appends often mean rewriting the whole document, so a small bucket bounds both effort and the risk of clobbering existing entries, on a predictable boundary that needs no "is it too big yet" judgement. Buckets are not migrated when the scheme changes: earlier periods stay in their original documents, listed in the index, and the new scheme starts from the changeover.

## Entry format

```
### YYYY-MM-DD — [Decision title]
**Decision:** What was decided
**Context:** What was happening / what triggered it
**Why:** Reasoning. Options considered briefly where relevant.
**Impact:** What changes downstream
**Status:** Active / Superseded by [X]
```

## Lifecycle

- **Append** the entry to the **current period's** child document — creating that document if it does not yet exist — then add or update that period's row in the index.
- **One entry per decision.** Don't bundle unrelated decisions into one entry, or split one across several.
- **Update, don't leave stale.** When a logged decision is later resolved or reversed, edit its entry — set `Status: Superseded by [X]` and point to the superseding decision — rather than leaving a contradiction in place.

## Tool mapping

This convention is the discipline; the tracker binding lives elsewhere. In Linear, the index and child documents are project documents and the index table links to each child — see `convention-linear` for the document mechanics, slug naming, and the full-replace-write caveat that sets the bucket size. If the tracker changes, this format is unaffected; only the mapping is rewritten.

## Quick checklist before logging a decision

- [ ] Is the decision actually consequential (depended-on or confusing-if-missing), not a routine reversible call?
- [ ] Entry in the standard format — Decision, Context, Why, Impact, Status?
- [ ] Appended to the current period's child document (newest at the top), creating it if needed?
- [ ] Index row for that period added or updated?
- [ ] Slug correct for the domain (A1 client → `a1-<client>.log-decisions`)?
- [ ] Any decision this supersedes updated to `Superseded by [X]`?
- [ ] Tone clean per `cos.tov`?