From dev-journal
Development journal: write, search, and retrieve project decisions and session logs. USE WHEN: user says "log", "journal", "write entry", "record what we did", "what did we decide about", "search journal", "show last entries", "check context", "what have we done". USE PROACTIVELY: invoke /journal check at the start of any session or before any architectural decision (new file, API design, protocol choice) without being asked. DO NOT USE for: general file writing, git commits, or inline code comments.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev-journal:journalThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Manage a per-project development journal with sequenced, dated entries.
Manage a per-project development journal with sequenced, dated entries.
Parse $ARGUMENTS to determine the command:
| Invocation | Action |
|---|---|
/journal (no args) | Write a new journal entry (default action) |
/journal <title> | Write a new entry with the given title |
/journal search <query> | Search journal by filename, then full text |
/journal last [N] | Show last N entries (default 1) for context |
/journal check | Find journal entries relevant to the current conversation |
/journal init | Create the journal directory, README, GUIDE.md, CLAUDE.md @import, and first entry |
/journal help | Show available commands and usage |
The journal directory is always docs/journal/. Create it if it doesn't exist.
YYYY-MM-DD--NNN-short-description.md
YYYY-MM-DD — today's dateNNN — three-digit sequence number, zero-padded (001, 002, ...), per-dayshort-description — lowercase, hyphen-separated, derived from the titleThe sequence number resets for each day. To determine the next number: find all existing entries for today's date (YYYY-MM-DD--*), take the highest NNN among them, and add 1. If no entries exist for today, start at 001.
The default action (no subcommand, or any text that isn't search, last, check, help, or init) is to write a new journal entry.
Title generation: If the user provides a title after /journal, use it. If /journal is invoked with no arguments, generate a title yourself by reviewing what was accomplished in the current conversation — look at files modified, decisions made, and topics discussed. The title should be concise (3-8 words) and describe the main outcome, not the process.
Steps:
docs/journal/ doesn't exist or has no README.md, run the full init command first (see init below), then continue.# NNN — <Title>
**Date:** YYYY-MM-DD
**Scope:** <infer from the work done>
## Summary
<One-paragraph summary of what was done and why — written by reviewing the conversation.>
## What changed
<Detailed description. Use tables for file lists, decisions, comparisons. Use bullet lists for sequential steps or findings.>
## Context
<Why this matters. Link to related entries or docs if relevant.>
search <query>Two-phase search:
Phase 1 — Filename search:
Use Glob to find journal entries whose filenames contain the query terms (case-insensitive). If matches are found, list them with their title (extracted from the # NNN — heading) and date.
Phase 2 — Full-text search (automatic if Phase 1 finds fewer than 3 results): Use Grep to search the content of all journal entries for the query. Show matching entries with the relevant excerpt (a few lines of context around each match).
Present results as a table:
| # | Date | Entry | Match |
|---|------|-------|-------|
| 019 | 2026-03-10 | DESPEE naming across docs | filename |
| 011 | 2026-03-05 | Monolithic DSP + ESP32 display | content: "DESPEE" on line 42 |
last [N]helpPrint the following command reference to the user:
## Journal Commands
| Command | Description |
|---------|-------------|
| `/journal` | Write a new entry (auto-generates title from conversation) |
| `/journal <title>` | Write a new entry with the given title |
| `/journal search <query>` | Search entries by filename and content |
| `/journal last [N]` | Show last N entries (default 1) |
| `/journal check` | Find entries relevant to the current conversation |
| `/journal init` | Set up the journal directory, README, GUIDE.md, and CLAUDE.md @import |
| `/journal help` | Show this help message |
Entries are stored in `docs/journal/` as `YYYY-MM-DD--NNN-description.md`.
No other action is needed — just display the help text and stop.
checkProactively find journal entries relevant to the current conversation. Designed to be invoked by Claude automatically when starting work or before architectural decisions — not only on explicit user command.
Steps:
docs/journal/ exists. If not, inform the user there is no journal yet and suggest /journal init.*auth*, *migration*).## Relevant journal entries
| # | Date | Entry | Relevance |
|---|------|-------|-----------|
| 014 | 2026-03-08 | Auth middleware rewrite | mentions `auth.ts`, decided on JWT over sessions |
| 009 | 2026-03-03 | Database migration strategy | discusses migration patterns relevant to current work |
### Key decisions from past entries
- **Entry 014:** Chose JWT tokens over server-side sessions because of horizontal scaling requirements.
- **Entry 009:** All migrations must be reversible; use a down() function in every migration file.
initThe init command is idempotent — it checks what already exists and only creates what is missing. Run through each step in order, skipping anything that is already in place.
Directory: If docs/journal/ does not exist, create it.
README.md: If docs/journal/README.md does not exist:
Before writing anything:
README.md. Extract the first # Heading as the project name
and the first non-heading paragraph as the project purpose.docs/journal/README.md — construct the content from what you just read.
Do NOT use placeholder text like <Project Name>. The heading must be the actual name.Template (fill in the actual project name):
# <actual project name> Development Journal
Chronological log of design decisions, implementation sessions, and architecture changes.
Entries are named `YYYY-MM-DD--NNN-description.md` where `NNN` is a global sequence number.
To add an entry: `/journal <title>`
To search: `/journal search <query>`
To review recent context: `/journal last [N]`
For help: `/journal help`
GUIDE.md: Check whether docs/journal/GUIDE.md already exists.
GUIDE.md template:
## Journal
This project maintains a development journal in `docs/journal/`.
Entries are named `YYYY-MM-DD--NNN-description.md` (e.g., `2026-03-13--004-fix-plugin-installation.md`).
### Commands
| Command | What it does |
|---------|-------------|
| `/journal` | Write a new entry — title is auto-generated from the conversation |
| `/journal <title>` | Write a new entry with an explicit title |
| `/journal search <query>` | Search entries by filename and content |
| `/journal last [N]` | Show the last N entries (default 1) |
| `/journal check` | Find entries relevant to the current conversation |
| `/journal init` | Set up the journal directory and CLAUDE.md @import |
| `/journal help` | Print command reference |
### When to use the journal
- **Before starting work:** Run `/journal check` to surface past decisions relevant to the files or topics you're about to touch.
- **Before architectural decisions:** Run `/journal search <topic>` to see if the topic was discussed before.
- **After completing work:** Run `/journal` to capture what was done and why.
### Examples
/journal # auto-title from conversation /journal Switched to monorepo # explicit title /journal search auth # find past auth decisions /journal last 3 # review last 3 entries /journal check # what's relevant right now?
CLAUDE.md @import: Check whether the project root CLAUDE.md already contains the line @docs/journal/GUIDE.md.
CLAUDE.md does not exist: create it with just that line.CLAUDE.md exists but does not contain the @import: append the line @docs/journal/GUIDE.md to the end of the file (on its own line).CLAUDE.md already contains the @import: skip.First journal entry: Check whether any journal entries (docs/journal/????-??-??--*) already exist.
docs/, skills/, CLAUDE.md).Report what was done. List each component and whether it was created, updated, skipped (already present), or skipped (user declined). Example:
Journal init complete:
- docs/journal/ — already existed
- docs/journal/README.md — created
- docs/journal/GUIDE.md — updated (user confirmed)
- CLAUDE.md @import — already present
- First entry — skipped (entries already exist)
docs/hardware.md).These rules apply at all times, not just when explicitly invoked via /journal:
Session start: Before writing any code or making any change, silently run check
to surface relevant past decisions. Do not announce this — just do it and surface results
only if something relevant is found.
Post-work reminder: After any significant block of work (file edits, architectural decisions, debugging sessions), offer: "Want me to write a journal entry for this session?" Do not skip this offer even if the user did not mention journaling.
Architectural gate: If the user is about to make a choice between two technical
approaches (library, protocol, structure), first run /journal search <topic> silently
and report any past decision before proceeding.
check because "the user didn't ask for it."npx claudepluginhub juliuszfedyk/dev-journal --plugin dev-journalGenerates markdown developer journals from Claude Code activity data over specified time periods like today or last week. Focuses on accomplishments, decisions, and project progress with day-by-day breakdowns.
Writes and maintains implementation diaries for non-trivial tasks like features, bug fixes, refactors; captures changes, why, successes, failures with errors/commands, learnings, tricky parts, review notes in dated Markdown files.
Logs daily development progress with project-isolated diary entries and optional sync to Notion/Obsidian. Invoke via /diary or when summarizing achievements.