tomevault-io 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:
- Recent git commits on the current branch
- Code changes made during this conversation
- Decisions and tradeoffs discussed
- Non-obvious solutions or workarounds implemented
Then suggest specific entries for the journal, or confirm nothing significant needs capturing.
Quick Start
Ensure journal exists:
python skills/git-journal/scripts/ensure_git_journal.pyUpdate with current state:
python skills/git-journal/scripts/update_git_journal.pyWrite 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
- Why ← Primary. Always capture this.
- What — Conceptual summary
- Where — Key areas affected
- Who — From git config
- 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 missingscripts/update_git_journal.py— Update Who/When/Whatassets/git-journal-template.md— Template for new journalsreferences/cursor-rule-template.md— Cursor rule template
Converted and distributed by TomeVault — claim your Tome and manage your conversions.