Decision Journal

# Decision Journal Contract

## When To Use

- A workflow has just made a decision and needs to record the tradeoff:
  what was chosen, what was rejected, what was sacrificed.
- A workflow has hit a failed approach, rework, or blocker and needs to
  record the lesson.
- Building or validating a consumer hook that writes to the journal.

## When NOT To Use

- Scaffolding the files at project init (that is `attune:project-init`).
- Recording a full architecture decision that warrants a numbered ADR in
  `docs/adr/`; reference its number from a journal entry instead of
  duplicating it.

This is a convention and a helper rather than a hard runtime
dependency. Consumers degrade gracefully when leyline is absent
(see Fallback).

## What This Captures, And Why

AI-assisted work tends to narrate tool output ("the agent built X") and lose
the human reasoning: the decision, the road not taken, and the honest rework
nobody mentions. Two append-only logs, co-located with the code, fix that:

- `docs/tradeoffs.md` records decisions **and the alternatives sacrificed**.
- `docs/lessons-learned.md` records insights, failed approaches, and rework,
  framed blamelessly.

## Files And Discipline

Both files live in `docs/` (co-location is the strongest anti-staleness
lever). Each is a single append-only running log with a scannable
`## Active index` at the top and an `## Archive` section at the bottom.

1. Append-only. An accepted entry is never edited or deleted; only its
   `Status` changes.
2. Supersede, do not overwrite. A reversal adds a new entry, flips the old
   entry's status to `superseded-by: <new-id>`, and links both ways.
3. Stable IDs (`TR-001`, `LL-001`) so links from PRs, commits, and code
   never break.
4. Every entry links back to its PR, commit, or issue.

Status vocabularies:

- Tradeoffs: `proposed -> accepted -> (superseded-by: TR-NNN | deprecated)`
- Lessons: `open -> actioned -> closed`

## Capture UX: Draft And Confirm

When a workflow reaches a decision or lesson point:

1. Draft the entry from the live context of the phase (the options weighed,
   what was given up, the failure and its root cause).
2. Show the draft to the human and let them confirm or edit.
3. Append it. Tradeoffs start `proposed`; lessons start `open`.

Do not auto-write without the confirm step. The point is to capture the
human reasoning, not to generate noise.

## CLI Interface

Run the helper from leyline:

    python3 ${LEYLINE}/scripts/journal_append.py <tradeoffs|lessons> \
      --project-root <repo-root> \
      --title "<short title>" \
      [--phase <phase>] [--status <status>] \
      [--field key=value ...] \
      [--json '<full field object>'] \
      [--supersedes TR-NNN] \
      [--dry-run]

The helper assigns the next ID, renders the template, inserts the entry above
the `## Archive` marker, updates the active index, and (with `--supersedes`)
flips the prior entry's status and adds backlinks. It is idempotent: appending
an entry whose substantive fields already appear is a no-op.

### Tradeoff fields

`title` (required), `context`, `drivers` (list), `options` (list of
`{name, pros, cons, chosen}`), `decision`, `ystatement`,
`consequences_positive`, `consequences_negative`, `phase`, `deciders`,
`links`. Prefer `--json` for the list-valued fields. `status` and `date`
are auto-set (`proposed` / today) but can be overridden.

### Lesson fields

`title` (required), `what_happened`, `what_went_well`, `what_didnt_work`,
`root_cause`, `action`, `category`, `owner`, `phase`, `links`. `status`
and `date` are auto-set (`open` / today) but can be overridden.

## Fallback (leyline Absent)

The entry template ships inside each scaffolded file as an HTML-comment footer
(`<!-- ENTRY TEMPLATE ... -->`). W