Journaling sessions

Journaling Sessions

Capture what a session produced as structured, separable, retrieval-ready entries — prose with metadata, one idea each — that a future session can find and reason about in isolation. The quality bar is not "does this summarize the session" but "will a future session, retrieving this cold months from now, be measurably better for having it."

These entries are raw material: a downstream process clusters many of them into generalizations, and repeated reinforcement promotes the durable ones into long-lived guidance. Write each entry so that clustering works — that is what every rule here optimizes for.

This skill produces raw capture. It runs an automatic multi-pass loop so you get thorough output from a single invocation — you do not need to ask for "multiple passes."

What a session produces

Three kinds of knowledge; capture all three, not only the most obvious:

• Conclusions — decisions made, facts discovered, tradeoffs analyzed, hypotheses formed. What a meeting summary would contain.
• Process dynamics — the shape of the reasoning: where breakthroughs happened, where we got stuck, what surprised us, what assumptions proved wrong.
• Perceptions — what the user cared about, what engaged them or felt like overhead, what they pushed back on and why.

The three-part framing is a coverage checklist, not a prediction of how entries cluster. Underjournaling conclusions is fine; underjournaling perceptions is a systematic blind spot.

When to produce

• The session was substantive (not quick Q&A).
• Something was decided, discovered, or perceived worth remembering.
• An authoritative source was read/ingested end-to-end.
• The user asks ("journal", "log this", "wrap up"), or the session is clearly ending.

Were you asked, or did you notice? — write, or offer first

How this skill activated decides whether you write the journal now or only offer it. The journal is real work — often several thousand tokens — and every entry you write lands in the user's long-term store; producing one unbidden, or on a session that wasn't worth it, is the cost to avoid.

• The user asked — write now. "journal", "log this", "wrap up", or any request to preserve what was worked out ("don't lose this", "before I forget", "so next time we don't relitigate"). Run the loop below and write the file. No confirmation step.
• You activated on your own — offer first. The session is winding down and you judged it substantive (3+ decisions/findings), but the user voiced no wish to capture — e.g. a bare "that's everything, thanks." Do not write the journal. Emit a single one-line offer naming what is capturable, then stop: "This session worked out 4 decisions and a dead end worth journaling — want me to capture them?" Write the entries only after the user accepts.
  • One offer, not a nag. If the user declines, ignores it, or says stop, do not offer again this session.
  • Match a shown cadence. If the user already journaled once this session, you may offer again when the next arc of work finishes — they've shown they want this session captured.

When you can't tell which path you're on, offer — don't auto-write.

Pick the mode

Most sessions are one of two shapes; the capture questions differ. Pick first.

• Implementation / decision mode — the session did work: made a choice, diagnosed a bug, designed a component, ran an experiment, built something. Use the Conclusions / Process / Perceptions framework below.
• Reference-ingestion mode — the session converted an authoritative source (standard, textbook, regulation, paper, framework docs, teaching material) into entries. The reliable signal: most entries would have origin: reading. Use the eight-category taxonomy in references/reference-ingestion.md, and detect any declared downstream use (implementation / teaching / cross-project / positioning) before capturing — that file explains how.

A session can be both (implementation-targeted reference-ingestion is canonical); run both frameworks.

The workflow — automatic multi-pass

Once you are writing — the user asked, or accepted your offer (see "Were you asked, or did you notice?" above) — produce all entries in a single file. Do not pause for approval between entries. If a journal file already exists for this session, read it first and only add what is not yet captured. If the session contains ready-made entry drafts (e.g. from a questioning/critique pass), include them verbatim — they are already shaped — then add the rest.

Then run this loop internally, before presenting anything:

1. Identify the mode (+ downstream use if reference-ingestion).
2. Pass 1 — produce all entries for the chosen framework.
3. Self-check (silent) against the three coverage axes in references/coverage-check.md: source, downstream-use, measurability.
4. If gaps: run pass N+1 adding only the missing entries. Repeat until the coverage signals are clean, or a 3-pass cap is reached. Pass 1 routinely under-captures, often by a lot; this loop is the mitigation, not optional.
5. Present once: the file, the entry count and its breakdown by entry type ("ran K passes; coverage clean").
6. One surviving offer: only if a downstream use was declared and remains thin after the cap, offer a single targeted pass naming the specific axis. Otherwise stop — do not offer a generic "second pass."

For long runs (40+ entries), save after each arc to avoid quality drift; the user can say "continue journaling" to resume.

How to produce — implementation mode

Work through these in order. Skip any with no answer. Each becomes one or more entries. Aim for at least one process or perception entry per session.

Conclusions.

• What was decided? What was chosen, what was rejected, what evidence drove it. Include the WHY — the reasoning matters more than the outcome.
• What was discovered? Bugs diagnosed, research findings, empirical observations, undocumented patterns. Include the source.
• What tradeoffs were analyzed? Approaches compared, dimensions used, winner, conditions where the loser would win.
• What hypotheses changed? Created, confirmed, refuted, with the evidence.
• What contradicted existing knowledge? Both sides and how to resolve.
• What connects across domains? Structural similarities, shared principles.

Process dynamics.

• Where did breakthroughs or turning points happen? The reframing question, the observation that changed direction — high-value reusable reasoning patterns.
• Where did we get stuck or go wrong? Dead ends, wrong assumptions, wasted effort, what Claude got wrong and how it was corrected. A system that only remembers successes has survivorship bias.
• What assumptions did Claude bring that were challenged? Default recommendations pushed back on, consensus that didn't apply.

Perceptions.

• What did the user care about most — not the topic, but what within it mattered (depth vs speed, correctness vs progress, elegance vs pragmatism).
• What was the user's energy like — what engaged them vs felt like a chore.
• What would help a future instance work better with this user on this topic?

How to produce — reference-ingestion mode

Work through the eight categories in references/reference-ingestion.md in order, checking each against the source before deciding it does not apply. Aim for at least one OBSERVATION entry on the source-reading dynamics.

Output

Write entries in the structured envelope defined in references/output-format.md — the envelope, the full field set (including visibility, language, and the optional validated boolean), entry types, the ANTI_PATTERN template, area/domains, refs, confidence, multi-user privacy, and the VALIDATED marker.

Where the journal goes. Write the file to docs/journal/<YYYY-MM-DD>-<session>.md by default, so consolidate-knowledge has a defined place to gather from. A target_store profile with a path overrides that location; use it when the store lives elsewhere.

Binding to a specific store (optional). By default the envelope is generic — a placeholder author and example area values — and any structured store can ingest it. But area and author are scope/partition keys in a typical store (retrieval filters by author; consolidation runs author+area-scoped), so when you are journaling into a specific existing store, the host or user can supply an optional target_store profile that binds them to that store's real vocabulary — otherwise the entry ingests cleanly and is then silently orphaned from the corpus it belongs to. The profile is something you are given (stated inline, or by being pointed at one) — do not hunt for it at a fixed path or invent one. Absent a profile, behavior is exactly as today. See references/store-binding.md for the profile shape and binding rules.

Envelope vs prose-only — decide by an explicit signal, not inference. The envelope exists to be machine-ingested and clustered, so it is the default; drop it only on an explicit opt-in:

• A target_store profile is present ⇒ there is a store downstream, so the envelope is mandatory — never take the prose-only branch.
• The user explicitly says there is no store downstream — "just for my own re-reading", "no vector store", "skip the envelope" ⇒ emit each entry's CONTENT prose and skip the envelope. Keep the discipline that carries the value (one idea per entry, reasoning inline, anti-patterns hunted); drop only the ceremony.
• Neither signal ⇒ default to the envelope. A mis-inferred "no store" yields a whole file that reads like a journal but no store can parse — the costlier error — so when unsure, emit the envelope.

Writing quality

Five rules carry most of the value; the full craft is in references/writing-for-retrieval.md:

1. Be concrete and include the reasoning inline. "Connection pooling cut p99 latency 6x under load by reusing TCP+TLS setup" beats "pooling is faster."
2. One idea per entry. If it wants to exceed ~300 words, it's two entries.
3. Anti-patterns are the most valuable entries — actively hunt for what was tried and failed, not only what worked.
4. Apply the reconstruction test at drafting time: would a future instance benefit from this specifically, vs. reconstructing it from generic training? If training already covers it, don't draft it.
5. Front-load the distinctive concept and use specific names — the first sentence does the heaviest retrieval work.

Boundaries

• Live run state is not journal material. The plan, current cursor, invariants, and mid-run decisions of a run still in flight belong to compaction-survival's control anchor — rewritten continuously by the same run so a compaction or reset cannot erase them. Journal entries capture what a finished stretch of work taught, after the fact; "persist the state so a reset doesn't lose it" is an anchor ask, not a journaling ask.
• Handing work to a fresh session or teammate is context-handoff's brief, not a journal.
• Consolidating prior journals into higher-level guidance is the downstream pass (consolidate-knowledge), not this skill.