| name | dev-journal |
| description | Write or update the narrative session entry in docs/development-journal.md. Captures decisions, learning, and AI tooling observations. MANDATORY before every commit. TRIGGER when the user says "update the journal", "write a journal entry", "log the session", or when preparing to commit (should auto-check if journal is current). |
Development Journal Entry
Write or update the session narrative in docs/development-journal.md.
Current Context
- Branch: !
git branch --show-current
- Recent commits: !
git log --oneline -5
- Changes this session: !
git diff --stat
Journal Entry Format
Entries are reverse chronological (newest at top). Each session gets one entry.
Template
### Session [N] — [Date] — [Milestone]
**What happened**: [1-3 sentences summarizing the session's work]
**Key decisions**:
- [Decision 1 and rationale]
- [Decision 2 and rationale]
**Learning**:
- [Non-obvious thing discovered]
- [Pattern or approach that worked well/poorly]
**AI tooling observations**: [How Claude Code helped or hindered — what worked, what didn't]
**What's next**: [What the next session should pick up]
**Retro** (include when completing a milestone):
- Estimate vs actual: [Xh estimated, Yh actual]
- What surprised you: [unexpected complexity, discovery, or outcome]
- Process improvement: [what would help next time]
Rules
- Read the existing journal first — check the latest session number and continue the sequence
- Be narrative, not mechanical — explain WHY decisions were made, not just what was done
- Capture learning — the journal's value is in recording insights that prevent future mistakes
- Include AI observations — how was Claude Code used? What prompts worked well? What was frustrating?
- Write DURING the session — do not defer to end. Sessions can be interrupted or run out of context.
- Every commit should have a current journal — treat this as a hard requirement
Verification
