Git Journal

Capture the "Why" behind code changes. Git tracks what/where/when/who—this skill captures why.

Trigger Phrases

Users invoke this skill with phrases like:

Phrase	Behavior
"remember to journal"	Set a session-long reminder. Throughout the conversation, proactively consider journaling when significant decisions are made, tradeoffs are discussed, or non-obvious solutions are chosen.
"anything to journal?"	Reflect on the current session. Review recent commits, code changes, and conversation to identify anything worth preserving in the journal.
"journal this"	Immediately capture the current context/decision in the journal.
"update the journal"	Run the update script and prompt for Why content.

"Remember to Journal" Mode

When activated, keep journaling in mind for the entire session:

• After complex problem-solving → consider journaling the reasoning
• After architectural decisions → capture the tradeoffs
• After rejected approaches → document why they were rejected
• Before commits → prompt if there's unjournaled context

"Anything to Journal?" Reflection

When asked, review:

1. Recent git commits on the current branch
2. Code changes made during this conversation
3. Decisions and tradeoffs discussed
4. Non-obvious solutions or workarounds implemented

Then suggest specific entries for the journal, or confirm nothing significant needs capturing.

Quick Start

1. Ensure journal exists:

   python skills/git-journal/scripts/ensure_git_journal.py
   

2. Update with current state:

   python skills/git-journal/scripts/update_git_journal.py
   

3. Write the Why section (automation handles Who/When/What).

Journal Location

journals/YYYY-MM-DD_<branch-name>.md

• One journal per branch
• Flat file structure (no nested folders)
• Branch names normalized (slashes → hyphens)

The 5 W's Priority

1. Why ← Primary. Always capture this.
2. What — Conceptual summary
3. Where — Key areas affected
4. Who — From git config
5. When — Timestamps

If time is limited, only Why must be correct.

What to Write in Why

## Why, current summary

**Intent**
- Refactored auth to support background token refresh

**Constraints**
- Must work offline after initial auth

**Tradeoffs**
- Added complexity for better UX

**Alternatives considered**
- Redux approach: rejected due to complexity

**Non-obvious nuance**
- Retry loop looks like a bug but handles edge case where...

Include:

• Problem being solved
• Why this solution was chosen
• Constraints (time, platform, APIs, business)
• Rejected alternatives and why
• Things that look wrong but are correct

Journal Structure

Two layers:

• Top: Aggregated summary (periodically consolidated)
• Bottom: Detailed log (append-only entries with timestamps)

Integration

See references/cursor-rule-template.md for a ready-to-use Cursor rule.

Optional pre-commit hook:

#!/bin/sh
python skills/git-journal/scripts/ensure_git_journal.py

Files

• scripts/ensure_git_journal.py — Create journal if missing
• scripts/update_git_journal.py — Update Who/When/What
• assets/git-journal-template.md — Template for new journals
• references/cursor-rule-template.md — Cursor rule template