[taddyb]

Adds an automatic research journal at docs/journal/. Independent of #40 — no Rust, no build, no CI gate, src/ and the invariants untouched.

The problem

89 runs and ~20 experiment bundles exist under .ddrs/. The reasoning behind almost all of them lives only in conversation history, which gets compacted away. CLAUDE.md already requires committing knowledge from a completed run; nothing enforced it and nothing made it cheap, so the repo has findings docs for the campaigns someone remembered to write up and nothing for the other 200 runs.

The design

One file per month, append-only, two parts:

• Ledger — one row per completed run or experiment, smoke tests and shards included, so no run is lost. Machine-written.
• Entries — Question / What we did / Result / Conclusion. Human-written.

The split is the whole design. scripts/journal.py scrapes everything a manifest knows and writes _TODO_ for everything it cannot:

 ddrs run / ddrs experiment finishes
            |
      scripts/journal.py
            |
   smoke test or shard? ──yes──> ledger row only
            |no
   ledger row + entry stub with 4 _TODO_ fields
            |
   docs/journal/2026-09.md   (git-tracked, append-only)

Three hooks in .claude/settings.json: PostToolUse on ddrs run/ddrs experiment writes the record; Stop blocks only on stubs the current session opened; SessionStart reports runs finished outside a session and writes nothing.

It never invents judgement

This is the load-bearing constraint, and it shaped three decisions:

• --mode backfill writes ledger rows only. 103 of the 224 historical records would otherwise have opened a full stub, and nobody can reconstruct the hypothesis behind a run from two months ago. History gets provenance, not guesses.
• Stop is scoped to the originating session. A session with no context on a run would be pressured into inventing a hypothesis.
• The skill says so explicitly: an entry for a run whose purpose is unrecoverable writes unknown — run predates this entry. One confident guess and the record stops being evidence.

What is already in it

224 historical records backfilled, 121 correctly classified as smoke tests or shards:

Month	Ledger rows
2026-06	19
2026-07	25
2026-08	13
2026-09	167

Plus one hand-written entry for the gridded DDM30 port, so the format ships with real content rather than a placeholder.

Safety

The hook runs on every Bash call in the repo, so it is built not to matter when it does not apply:

Property	How
Cannot fail the command it observes	Top-level except exits 0
Cheap when irrelevant	Regex-gated; ~30 ms and silent otherwise
Cannot perturb a worktree	Stdlib only, no git subprocess
Cannot loop	stop_hook_active guard
Killable	DDRS_JOURNAL_OFF=1

scripts/test_journal.py (stdlib, no deps, all passing) covers idempotency — three backfills leave the table unchanged — smoke classification, that judgement is never auto-written, that the Stop nag is session-scoped and cannot loop, and that a corrupt manifest does not take down the observed command. Also verified live against the real .ddrs, then cleaned up.

Known gaps, stated up front

1. A hook only sees commands Claude runs. ddrs run typed in your own terminal produces no PostToolUse; it is caught at the next session start instead. Capture is eventual, not immediate.
2. Long runs are backgrounded, so PostToolUse fires before the manifest exists. Handled by scanning for any finished-and-unjournaled run rather than only the one that command started.
3. Experiment ledger rows are thin (N arm(s), status) because experiment manifests carry no scalar result; theirs live in figures/.

Review notes

• docs/journal/ is deliberately not in SUMMARY.md — a working notebook, not published mdBook docs.
• The gridded entry links to a spec that lands with Gridded (ISIMIP DDM30) routing as a data source, the ddrs-run skill, and three silent-failure fixes #40; that link resolves when Gridded (ISIMIP DDM30) routing as a data source, the ddrs-run skill, and three silent-failure fixes #40 merges.
• Design, rejected alternatives (Rust subcommand, file-per-entry, entry-for-every-run), and full blast radius: docs/superpowers/specs/2026-09-10-research-journal-design.md.
• The ddrs-journal skill has not been through the RED/GREEN subagent cycle writing-skills prescribes. Worth doing if you want confidence its entry-quality rules bind under pressure.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EqnrtmU91yzuVpGnADnXLP