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:

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

Trigger Phrases

"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:

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