Journal

Monthly Development Journal

Generate a structured narrative of what happened in this project over a month. Reads git log, merged PRs, decisions, and any project memory the agent has access to.

Cadences

Default is monthly. Other cadences accept the same data but produce different narratives:

• /journal weekly — last 7 days. Lighter narrative; focus on what shipped + what's next.
• /journal sprint — last sprint length (default 14 days; configurable via .claude/journal-cadence.yaml).
• /journal release — since the last git tag. Releases-as-units narrative.
• /journal monthly (default) — calendar month, full retrospective.

The data-gathering steps (git log, PRs, decisions, memory) are identical; only the time window and narrative emphasis differ.

Step 1: Determine the Window

Resolve the time window by cadence:

| Cadence | Window resolution | |---|---| | monthly (default) | Previous calendar month if today is day 1-7, otherwise current month. Argument may be a month name (march) or YYYY-MM. | | weekly | Previous ISO week if today is Mon/Tue, otherwise current ISO week. Argument may be YYYY-WW. | | sprint | Last sprint length ending today (default 14 days; configurable via .claude/journal-cadence.yaml). | | release | Since the most recent git tag (use git describe --tags --abbrev=0). End at HEAD. |

Compute start_date and end_date accordingly. For monthly, start_date = first day of month, end_date = first day of next month. For weekly, ISO week boundaries. For sprint, today minus sprint length. For release, the tag's commit date and HEAD's commit date.

Check if the would-be filename (per Step 6's table) already exists. If so, ask: "A journal for {window-label} already exists. Regenerate it?"

Step 2: Gather Data

Run ALL of the following in parallel:

Git History

• git log --oneline --since="{start_date}" --until="{end_date}" — all commits
• git log --since="{start_date}" --until="{end_date}" --format="%H %s" --reverse — commits with hashes for grouping by branch
• git shortlog -sn --since="{start_date}" --until="{end_date}" — contributor summary
• Detect default branch: git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' (fallback to main)

Merged PRs (if gh is available)

• `gh pr list --state merged --limit 30 --json number,title,headRefName,mergedAt --jq '.[] | select(.mergedAt >= "{start_date}" and .mergedAt value at small windows).

Step 5: Present for Review

Show the full journal in the conversation. Ask:

"Here's the journal for {window-label}. Anything you'd like to add, change, or remove before I save it?"

Step 6: Save

Create the journal directory if needed:

mkdir -p "$(git rev-parse --show-toplevel)/.claude/journal"

Filename by cadence:

| Cadence | Filename | |---|---| | monthly (default) | .claude/journal/YYYY-MM.md | | weekly | .claude/journal/YYYY-WW.md (ISO week) | | sprint | .claude/journal/sprint-.md | | release | .claude/journal/release-.md |

Confirm: "Journal saved to ."

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: momentmaker
• Source: momentmaker/kaijutsu
• License: MIT
• Homepage: https://kaijutsu.dev/

Install and usage instructions live in the source repository linked above.