# Git Journal

> Capture the "Why" behind code changes during AI-assisted development. Creates branch-scoped markdown journals preserving reasoning, tradeoffs, and context. Also maintains living business-level QA docs in docs/ for self-healing tests and requirements clarity. Use before commits, PRs, or multi-file changes. Use when the user says "remember to journal", "anything to journal?", "journal this", "update the docs", or "anything to document?".

- Skill: `kingly-clark/git-journal` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add kingly-clark/git-journal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kingly-clark/git-journal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: kingly-clark (https://skillmd.com/u/kingly-clark)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kingly-clark/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:
   ```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)

---

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

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

2. Inspect taxonomy (for agent context):
   ```bash
   python skills/git-journal/scripts/update_docs.py --list
   ```

3. Create or update domain/feature files (agent writes content; script can scaffold):
   ```bash
   python skills/git-journal/scripts/update_docs.py --domain auth --feature sign-in
   ```

### Enhanced Flow (every journal invocation)

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