journal-and-adr

name	journal-and-adr
description	Use at the END of any substantive task in this repo (new feature, behavior change, notable refactor, non-trivial fix, doc/skill change) to append a dated journal entry, and WHENEVER you make a significant, hard-to-reverse architectural decision to also write an ADR. Covers the journal/ and adr/ folder conventions, the entry templates, ADR numbering and the supersede rule, and the repo-vs-machine-local knowledge principle. Invoke before finishing work so durable reasoning lands in the repo, not just in chat.
user-invocable	true

Journal & ADR — recording durable knowledge in this repo

This repo keeps two lightweight, committed records so reasoning survives beyond a single chat and reaches teammates on other machines:

• journal/ — a dated narrative of substantive work (the what & why).
• adr/ — Architecture Decision Records for significant, hard-to-reverse calls.

Both live at the repo root and are committed. They are the repo-local complement to Claude's machine-local memory — see "Where knowledge lives" at the bottom.

When to write

Append a journal entry at the END of any substantive task — a new feature, a behavior change, a notable refactor, a non-trivial bug fix, or a docs/skill change. Skip trivia (typos, formatting, purely mechanical renames).

Also write an ADR when that task involved a significant, hard-to-reverse decision — a choice a future maintainer will want the why for (a new dependency, a public-API or data-model change, a cross-repo contract, dropping or replacing a library). Most tasks need only a journal entry; an ADR is the exception. When you write one, link it from the journal entry's Related line.

In the framework, the uvicore-ship-framework-change skill's checklist already requires a journal entry and (if the change was an architectural call) an ADR — this skill is the how-to for both.

Journal — how

• One file per day: journal/YYYY-MM-DD.md. Append each piece of work as an ## (H2) entry; create the file if today's doesn't exist yet.
• Use today's real date (the harness provides it). Don't back- or post-date.
• Record the reasoning, not just the diff — a reader should understand why the change was made.
• Cross-repo work: if the change also touched a sibling repo in the constellation (the framework, an upstream/downstream lib, or the docs/schematic repos), note it under Related so a reader here knows there were downstream effects. Each repo keeps its own journal — add an entry in the other repo too if the work there was substantive.

Entry template

## <Short title>
- **Intent:** what was asked / the goal
- **Changed:** what changed and *why* (the reasoning, not just the file list)
- **Files:** key files touched
- **Related:** ADRs, tests, cross-repo edits, follow-ups

ADR — how

• Filename: adr/NNNN-kebab-title.md — zero-padded, sequential (0001-…, 0002-…). Pick the next number after the highest existing file; the index lives in adr/README.md.
• Format: compact Nygard — Status, Date/version, Context, Decision, Consequences.
• Never rewrite history. When a later decision changes an earlier one, write a NEW ADR and mark the old one Superseded by ADR-NNNN (leave its content intact).
• Update adr/README.md's index with a one-line link to the new ADR.

ADR template

# ADR NNNN: <Title>

- **Status:** Accepted | Proposed | Superseded by ADR-NNNN
- **Date / version:** YYYY-MM-DD (or uvicore X.Y.Z)

## Context
What forces / constraints / problem led to this?

## Decision
What we decided to do.

## Consequences
Trade-offs, what becomes easier/harder, migration impact, what to watch.

Where knowledge lives (repo vs. machine-local)

These repos are worked on by dozens of team members across many machines, and each is its own git repo. So all shared/durable knowledge goes in the repo — CLAUDE.md, .claude/skills/, docs/, and the journal/ + adr/ here. Claude's ~/.claude/.../memory/ is per-machine and per-user (not committed, not synced): fine for Claude's private working notes, but never the home for anything a teammate or another machine would need. If something there turns out to be broadly useful, promote it into the repo (a journal entry, an ADR, a skill, or CLAUDE.md).