nubiv/my-nome/devlog

Devlog

Records and recalls per-session devlogs in <repo-root>/.claude/devlogs/. Filenames are date-stamped with a zero-padded two-digit index (-00, -01, …) and never overwritten — every entry carries a suffix, so lexicographic sort equals chronological order.

Subcommands

If the user invokes /devlog with no subcommand, ask which one they want.

Shared setup

Both subcommands need the repo root and the devlogs directory:

REPO_ROOT="$(git rev-parse --show-toplevel)"
DIR="$REPO_ROOT/.claude/devlogs"

If the cwd is not in a git repo, ask the user where the devlogs live before continuing. Today's date is date +%Y-%m-%d.

write subcommand

Creates a new entry. Never overwrites an existing file.

Filename selection

• First file of the day: YYYY-MM-DD-00.md
• Next files: YYYY-MM-DD-01.md, YYYY-MM-DD-02.md, … (0-indexed, zero-padded to two digits, increment until free)

Always suffix — there is no bare YYYY-MM-DD.md. The zero-pad keeps ls | sort in creation order (a bare base name would sort after its own -NN entries because . > -).

mkdir -p "$DIR"
DATE="$(date +%Y-%m-%d)"
i=0
PATH_OUT="$DIR/$DATE-$(printf '%02d' "$i").md"
while [ -e "$PATH_OUT" ]; do
  i=$((i + 1))
  PATH_OUT="$DIR/$DATE-$(printf '%02d' "$i").md"
done

Then write the entry to $PATH_OUT using Write and report the final absolute path back to the user.

Entry template

# Devlog — YYYY-MM-DD
 
**Session window:** HH:MM–HH:MM (local)
**Branch:** <git branch>
**Repo:** <repo name>
 
## Summary
One-paragraph high-level recap of what this session set out to do and what shipped.
 
## Changes
-<file/area>: <what changed and why>
 
## Decisions
-<decision>: <reasoning / alternatives considered>
 
## Issues & blockers
-<issue>: <status — open / resolved / deferred>
 
## Next steps
-[ ] <todo>

Omit sections with nothing meaningful — don't pad with "N/A".

Content guidance

• Source content from the actual session, not generic placeholders. Pull from git log --since=..., git status, git diff --stat, and concrete decisions made in conversation.
• Keep it factual: what changed, why, what's next. Avoid restating what the diff already shows.
• If the user scopes it ("just log the migration work"), keep it scoped — don't dump the whole session.
• Devlogs are for future-you reading cold weeks later. File names, function/PR/issue IDs, and reasoning matter more than narration.

read subcommand

Loads existing devlog files into context using Read so their content is available for the rest of the conversation.

Selection rules

Parse the user's argument(s) after read:

Every entry carries a zero-padded -NN suffix, so filenames sort lexicographically by YYYY-MM-DD-NN and ls "$DIR" | sort is chronological — most recent is the last line.

Legacy note: older entries may exist as a bare YYYY-MM-DD.md (no suffix). Those sort after the day's -NN entries and will be wrongly picked as "most recent" — rename any you encounter to YYYY-MM-DD-00.md (and renumber later same-day entries) before relying on sort order.

Steps

1. List $DIR (e.g. ls "$DIR"). If empty or missing, tell the user there are no devlogs and stop.
2. Resolve the user's selector into a concrete file list.
3. Read each file in chronological order.
4. After loading, give a one-line summary: which files were loaded and their date range. Don't re-summarize their contents unless the user asks.

Quick examples

• /devlog read → loads the single most recent file.
• /devlog read today → loads 2026-05-22-00.md, 2026-05-22-01.md, … if they exist.
• /devlog read 2026-05-20 → loads every entry from 2026-05-20.
• /devlog read latest 3 → loads the 3 newest devlogs.

Review checklist

Before finishing a write:

• [ ] File path is under <repo-root>/.claude/devlogs/
• [ ] Filename matches YYYY-MM-DD-NN.md (zero-padded; first of the day is -00)
• [ ] No existing file was overwritten
• [ ] Final path reported to the user

Before finishing a read:

• [ ] Resolved selector to a concrete file list
• [ ] Used Read (not cat) for each file
• [ ] Reported what was loaded