/journal — record what actually happened

The journal is the anti-relearning device: a fresh collaborator (or future-you) opens the repo and resumes in five minutes without re-deriving a single decision. It records reality, not intentions — the plan says what should happen; the journal says what did.

Adjacent skills: /retro (trends across many sessions; /journal records one) · /learn (one durable lesson; /journal the whole session) · /resume (reads what /journal wrote).

Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:

link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)"   # empty = not symlinked
pack="$(dirname "$(dirname "$link")")"   # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
  "$pack/bin/acstack-config" || true          # resolved keys, with sources
  "$pack/bin/acstack-update-check" || true    # ≤1 fetch/day; silent ONLY if already checked today
  "$pack/bin/acstack-recall" || true          # LEARNINGS.md + bug-class names, capped 3KB
else
  echo "runtime off — proceeding without recall/update-check"
fi

Operating principles

• Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
• Never delete a decision. Supersede it: ~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason.
• Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
• Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
• Attribution: follow the project's attribution setting (default none) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit -m/-F messages only.
• Config: read .claude/acstack.md at the project root (fall back to ~/.claude/acstack.md) before acting. ## Settings keys override pack defaults; a ## <skill-name> section overrides both. Unknown keys and sections are ignored.
• Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
• Recall: if LEARNINGS.md exists at the project root, read it before starting.
• Conduct: follow the acstack-conduct block in this repo's AGENTS.md — the word is the mode; the user sets the pace.
• Hackathon lane: if the project's AGENTS.md carries the acstack:hackathon-lane block, only /do changes the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route.

One document set. Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name its path in the report's scope line. If more than one candidate set exists — a monorepo, nested products, an apps/* tree each with its own docs — list the candidates and STOP. Never pick one silently: a confident answer about the wrong product is worse than no answer (conduct rule 8).

Procedure

1. Gather. Read the config, JOURNAL.md (create from references/journal-template.md if missing), PLAN.md, and git log since the last journal commit — or, for a first entry (no prior journal commit exists), the full log, said as such. Get current test counts — run the suite if it's cheap; otherwise use the last recorded counts and say you did.

2. Write the entry under ## Key decisions and journey, newest first, heading ### <what changed> (YYYY-MM-DD[ morning/evening]). Follow references/worklog-rules.md for granularity — exact bugs, exact numbers, why-X-not-Y, what did NOT change, validation close.

   Two sessions journaling the same day will conflict here, and that is the tolerable outcome. Every entry goes in at the same anchor, so concurrent writes collide — measured 2026-09-14: CONFLICT (content): Merge conflict in JOURNAL.md. A conflict is safe; it stops and asks. Resolve it by keeping both entries, newest first, never by dropping one or merging them into a single heading — two sessions did two pieces of work and the record should show both. What must NOT happen silently is a wrong number: if the skeleton stores a derived count, re-derive it with the project's own tool after resolving rather than accepting whichever side git kept.

3. Classify any eval results. Every failure gets a bucket from the canonical table in ../audit/references/eval-review-rules.md: prompt issue / grader brittleness / provider flake / data issue / parser issue / genuinely ambiguous. Genuinely-ambiguous survives only as acceptable_failure: <written reason>. Use FAIL → fixed notation for resolved ones, and add a "Read" column giving the interpretation, not just the verdict. Never adjust a case to raise the number.
4. Update the skeleton sections: the top blockquote (**Last update**: date + 2-3 sentence delta), TL;DR, the what's-built table, pending-from- you table, deferred list. Keep "how to run" honest — rerun it if it may have drifted.
5. Sync PLAN.md. Check off boxes whose Acceptance actually passes now (verify — don't assume). A regression is recorded as ~~[x]~~ → **Verdict (date):** re-opened — reason, never a silent uncheck.
6. Commit with subject from journal-commit-format (default Journal YYYY-MM-DD: <summary>) plus a brief body, per CONDUCT rule 10. Include the PLAN.md sync in the same commit. Stage explicitly — never git add -A. Stage JOURNAL.md and PLAN.md by name. A blanket add sweeps whatever else was in the tree into a commit labelled "Journal", which is how unrelated work lands under a subject nobody would look under. Other files already modified → say so, list them, and leave them unstaged.

When the preconditions are not met

Each of these stops rather than guessing; naming the gap is the deliverable.

• Not a git repo. Write the entry, then say plainly that no commit was made and why. The journal is still worth having; a fabricated commit step is not.
• Nothing to record. A session with no commits and no plan movement gets that stated in one line, not an entry padded to look like progress. An honest "no work landed since <date>" is a true record.
• No PLAN.md. Write the entry and skip the sync step, saying so — never invent a task list to sync against.

Hard rules

• Numbers over adjectives: 60/90 → 8/123 flagged, 94.2s → 71.2s (~25%), 88 passed, 40 skipped (was 79/40). If a claim has no number, ask whether it deserves to be in the journal.
• Log incidental discoveries, including self-indicting ones ("the test was already stale before this change").
• Deferrals get a reason and a sequence ("after X, so Y is measured against real data"), never a bare "later".