git-journal

Git Journal

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

This skill has two outputs:

Output	Location	Purpose
Technical journal	journals/YYYY-MM-DD_<branch>.md	Branch-scoped change log: tradeoffs, alternatives, technical nuance
Business docs	docs/	Living current-state QA documentation by feature domain

Every git-journal invocation runs the technical journal flow unchanged, then evaluates whether business docs need updating.

Trigger Phrases

Phrase	Behavior
"remember to journal"	Session-long reminder. Proactively consider journaling after significant decisions; also evaluate business docs.
"anything to journal?"	Reflect on session; suggest journal entries and any docs updates needed.
"journal this"	Capture current context in journal; evaluate business docs impact.
"update the journal"	Run journal scripts and prompt for Why content.
"update the docs"	Run docs scripts; prompt for business context; update relevant docs/ files.
"anything to document?"	Review whether business docs need creation or updates for current work.

"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
• After user-facing behavior changes → evaluate docs/ updates

"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, evaluate business docs, or confirm nothing significant needs capturing.

---

Part 1: Technical Journal (unchanged)

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)

---

Part 2: Business QA Docs

Purpose

docs/ is the current state of how the product works from a business perspective—not a changelog. Journals record incremental technical reasoning; docs aggregate by feature domain so QA, AI agents, and future Notion sync can answer: how should this behave, and why?

Docs Location

docs/
  _index.md                 # Master entry: taxonomy, app matrix
  <domain>/
    _index.md               # Domain overview, sub-feature links
    <feature>.md            # Feature detail (when enough content warrants a file)

Taxonomy rules:

• Organize by business domain (auth, shop, arena), not by branch or technical layer
• Map branch/package hints: feat-auth → auth/, feat-shop → shop/, etc.
• Create a new domain folder when work touches a new business area
• Split into <feature>.md only when distinct detail exists; otherwise keep content in domain _index.md
• Folder names are lowercase, hyphenated (e.g. attend2earn, watch2earn)

Apps and applies_to

Always confirm which apps apply. Valid values:

Value	Meaning
wunderfan	Wunderfan only
wunderpar	Wunderpar only
golf-champs	Golf Champs only
wunderfan, wunderpar	Shared (common pair)
all	All apps

Use YAML frontmatter applies_to: [wunderfan, wunderpar]. Per-app differences go under ## App-Specific Behavior with ### Wunderfan, ### Wunderpar, etc.—do not duplicate whole docs.

Feature File Format

Use assets/docs-feature-template.md for new feature files. Required frontmatter:

---
domain: auth
feature: sign-in
applies_to: [wunderfan, wunderpar]
last_updated: YYYY-MM-DD
---

Sections (intent-based language, not implementation):

• Business Intent — problem solved, why feature exists
• User Experience — happy path in plain language
• Business Rules — governing rules
• Acceptance Criteria — Given/When/Then or testable checklists
• App-Specific Behavior — per-app differences
• Edge Cases — failure paths, boundary conditions
• Open Questions — unresolved items; mark [Resolved YYYY-MM-DD] when answered

Update last_updated whenever content changes. Do not reference journals in docs—journals are changelogs, docs are current state.

Business Docs Quick Start

1. Ensure docs scaffold exists:

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

2. Inspect taxonomy (for agent context):

   python skills/git-journal/scripts/update_docs.py --list
   

3. Create or update domain/feature files (agent writes content; script can scaffold):

   python skills/git-journal/scripts/update_docs.py --domain auth --feature sign-in
   

Enhanced Flow (every journal invocation)

1. Technical journal     → ensure + update + write Why (existing flow)
2. Analyze changes       → user-facing vs purely technical?
3. Map taxonomy          → which domain(s)? new domain?
4. Load existing docs    → ensure_docs.py if needed
5. Assess impact         → business change? if no, skip docs
6. Prompt user           → question framework (below); never guess
7. Update docs           → merge into current-state files; set last_updated
8. Staleness check       → flag docs that may contradict current work
9. Update root _index.md → taxonomy + app matrix from frontmatter

Purely technical changes (refactor, dependency bump, internal rename with no UX change) → update journal only, skip docs unless staleness is suspected.

Question Framework

Ask only what is needed—do not interrogate on every field every time.

Always ask (if not already known):

• Which apps does this apply to? (Wunderfan / Wunderpar / Golf Champs / All)

New feature or domain:

• What business problem does this solve for the user?
• What does the user experience look like? (happy path)
• What business rules govern this behavior?
• What does success look like from the user's perspective?

Updating existing feature:

• Does this change user-facing behavior, or is it purely technical?
• Are any existing business rules affected?
• Has app applicability changed?

Potential staleness:

• Docs for [domain] describe [behavior X]. Has this changed with your current work, or is it still accurate?

Unclear context:

• What exactly happens when [edge case] occurs?
• Is [assumption from existing docs] still valid?

If the user cannot answer, record an Open Question in the doc—do not invent business rules.

Root _index.md

Maintain:

• Taxonomy — table of domains with links to _index.md or feature files
• App matrix — which domains/features apply to which apps (derived from frontmatter)
• Last refreshed — date the index was regenerated

Run update_docs.py without flags after doc changes to refresh the index.

---

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
python skills/git-journal/scripts/ensure_docs.py

Files

Journal (unchanged):

• 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

Business docs:

• scripts/ensure_docs.py — Create docs/ and root _index.md if missing
• scripts/update_docs.py — Taxonomy listing, domain/feature scaffolding, index refresh
• assets/docs-index-template.md — Root docs/_index.md template
• assets/docs-domain-template.md — Domain docs/<domain>/_index.md template
• assets/docs-feature-template.md — Feature file template

Shared:

• references/cursor-rule-template.md — Cursor rule template