journal

Journal Skill

Write timestamped journal entries to notes/journal/ to preserve knowledge across sessions.

When to Write a Journal Entry

Write a journal entry when you encounter something that:

• Would be useful to know in a future session but doesn't belong in code comments
• Spans multiple issues or isn't specific to one task
• Is a discovery about the codebase, domain, or tooling
• Is a design insight or architectural observation
• Is a gotcha, workaround, or non-obvious behavior

Do NOT write a journal entry for:

• Task-specific progress notes (use your ticket/issue system)
• Durable design decisions (use notes/DECISIONS.md -- decisions are one-liners, not entries)
• Agent rules and patterns (use CLAUDE.md or auto-memory)
• Trivial observations that won't matter next week

Creating an Entry

Use the script to create entries -- it generates the correct filename and scaffolds the frontmatter:

# Agent creating an entry
${CLAUDE_PLUGIN_ROOT}/skills/journal/scripts/new-entry.sh ai vllm-batch-limit --tags vllm,performance

# Human creating an entry
${CLAUDE_PLUGIN_ROOT}/skills/journal/scripts/new-entry.sh hu checkpoint-design-notes --tags architecture

The script outputs the full file path. Open it and write the body.

Filename Template

<YYYYMMDD>T<HHMM>Z.<ai|hu>.<slug>.md

• Date and time: UTC, generated by the script
• Origin: ai for agent-written, hu for human-written
• Slug: short, descriptive, kebab-case

The origin marker is immutable. It captures who created the note, not who last edited it.

Content

Write the entry as plain markdown. Keep it concise -- a journal entry is a note, not an essay.

The script scaffolds optional YAML frontmatter from --tags and --refs flags. Humans may skip frontmatter entirely. Agents should include tags when the topic is clear and refs when working in the context of a specific issue.

References

If the entry relates to other journal entries, issues, wiki pages, or external resources, add a ## References section at the bottom:

## References

- [[related-note]]
- [Earlier observation on timeouts](20260207T0900Z.ai.vllm-timeout-mystery.md)

Use [[wikilinks]] for notes pages and relative paths for journal cross-references.

Reasoning About Authoritativeness

Not all journal entries carry equal weight. The primary authority signal is being linked from a hub file. A journal entry referenced from notes/INDEX.md, docs/, or another promoted entry has been actively vouched for.

When entries conflict, use this hierarchy:

1. Human-written (hu. in filename) -- highest baseline trust
2. AI-written, human-edited (ai. in filename, but git log shows human commits) -- validated
3. Linked from a hub file (notes/INDEX.md, docs/) -- promoted
4. AI-written, recent (< 2 weeks old) -- likely still accurate
5. AI-written, old, not linked -- treat as possibly stale

When in doubt, flag the conflict to the user rather than silently choosing.

Promoting Entries

Journal entries start as raw observations. They gain authority through promotion -- being linked from hub files:

• notes/INDEX.md -- project-facing index of active knowledge
• docs/ -- durable reference content

If an entry isn't linked from any hub, it's raw material -- useful for search, but not actively trusted.

Consolidation

Over time, entries accumulate. Periodically consolidate:

1. Read entries on a shared topic
2. Write a consolidated entry (or page in docs/) summarizing the current understanding
3. Move the original entries to notes/journal/archive/
4. Update hub files to point to the consolidated page

Consolidation is itself a form of validation. A consolidated page is more authoritative than the raw entries it replaced.

Searching the Journal

Before starting work on a topic, search existing entries:

# Find entries by topic
Glob: notes/journal/*.<topic>*.md

# Search entry contents
Grep: pattern="<keyword>" path="notes/journal/"

Also check notes/INDEX.md for curated links.

Directory Structure

notes/journal/
├── archive/                           # stale or consolidated entries
├── 20260209T1430Z.ai.vllm-batch-limit.md
├── 20260209T1512Z.hu.checkpoint-design-notes.md
└── ...