# Git Journal

> Capture the "Why" behind code changes during AI-assisted development. Creates branch-scoped markdown journals preserving reasoning, tradeoffs, and context that would otherwise be lost. Use before commits, PRs, or multi-file changes. Use when significant reasoning happened in conversation that should be preserved. Use when the user asks to document why a decision was made. Use when the user says "remember to journal", "anything to journal", or similar prompts. Use when this capability is needed.

- Skill: `tomevault-io/git-journal` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-journal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-journal/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/git-journal

---


# 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:
   ```bash
   python skills/git-journal/scripts/ensure_git_journal.py
   ```

2. Update with current state:
   ```bash
   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

```markdown
## 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:
```bash
#!/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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kingly-clark) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->