nubiv/devlog

Devlog

Records and recalls per-session devlogs in <repo-root>/.claude/devlogs/. Filenames are date-stamped and never overwritten — collisions get an incrementing index suffix.

Subcommands

| Subcommand | Purpose | |---|---| | write | Create a new devlog entry for the current session. | | read | Load one or more existing devlogs into the conversation. |

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.md
• Collisions: YYYY-MM-DD-1.md, YYYY-MM-DD-2.md, … (1-indexed, increment until free)

mkdir -p "$DIR"
DATE="$(date +%Y-%m-%d)"
PATH_OUT="$DIR/$DATE.md"
i=1
while [ -e "$PATH_OUT" ]; do
  PATH_OUT="$DIR/$DATE-$i.md"
  i=$((i+1))
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:

| Arg form | Behavior | |---|---| | (none) | Load the most recent devlog (latest by filename sort). | | today | Load all of today's entries (YYYY-MM-DD*.md), in index order. | | latest N | Load the N most recent devlog files. | | YYYY-MM-DD | Load every entry for that date (base file + all indexed suffixes). | | YYYY-MM-DD-N | Load that exact indexed file. | | all | Load every devlog (warn first if more than ~20 files — likely too much context). |

Filenames sort lexicographically by YYYY-MM-DD[-N], so ls "$DIR" | sort gives chronological 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.md, 2026-05-22-1.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.md or YYYY-MM-DD-N.md
• [ ] 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