Learning Log

---
name: learning-log
description: >
  Auto-document insights and discoveries during development sessions. Unlike
  MEMORY.md (corrective rules from the self-correction-loop skill), the learning
  log captures organic discoveries: non-obvious bugs, undocumented architecture
  decisions, performance findings, workarounds, and gotchas. Stored at
  .claude/learning-log.md. Load this skill when Claude discovers something
  non-obvious, finds a workaround, uncovers an undocumented decision, or when
  the user asks about "learnings", "discoveries", "gotchas", "what did we learn",
  or "document this finding".
---

# Learning Log

## Core Principles

1. **Log insights, not rules** — MEMORY.md stores corrective rules ("always use X instead of Y"). The learning log stores discoveries ("X behaves differently when Y is configured because Z"). Rules prescribe behavior; insights explain the world.

2. **Structure enables searchability** — Every entry has a date, category, title, description, and affected files. Consistent structure means you can search by category, scan titles, or find entries related to specific files.

3. **Log during work, not after** — Capture insights the moment they occur. Waiting until the end of a session means half the detail is lost. A 2-line entry written immediately is worth more than a paragraph reconstructed from memory.

4. **Periodic review extracts patterns** — A monthly scan of the learning log reveals recurring themes. Three "gotcha" entries about the same subsystem suggests a systemic issue worth addressing. Individual entries are useful; patterns across entries are actionable.

5. **Distinct from handoff notes** — The wrap-up-ritual handoff captures session state (done/pending/learned). The learning log is a persistent, growing knowledge base. Handoffs are overwritten; the log only grows (and is periodically pruned).

## Patterns

### Log Entry Format

Each entry follows a consistent structure in `.claude/learning-log.md`:

```markdown
# Learning Log

## 2025-07-15 | Bug Root Cause | EF Core SaveChanges Silently Succeeds on Duplicate Keys
`SaveChangesAsync` with a duplicate PK throws on the *next* `SaveChangesAsync` call, not the insert.
**Files:** `src/Orders/Features/CreateOrder.cs:42`
**Resolution:** Call `SaveChangesAsync` immediately after `Add()`, before any other operations.

## 2025-07-12 | Gotcha | MassTransit Consumer Registration Order Matters
Multiple consumers for the same message type run in registration order. If the first throws,
subsequent consumers are skipped. Caused missed audit events.
**Files:** `src/Shared/Extensions/MassTransitConfig.cs:15-30`
**Resolution:** Configure independent consumer endpoints or use the retry filter.
```

### Auto-Logging Triggers

Log entries automatically when these situations occur:

```
TRIGGER 1: Non-Obvious Bug Root Cause
When debugging reveals the root cause is NOT where the error appeared.
→ Log the misdirection, the actual cause, and how to avoid confusion.

TRIGGER 2: Undocumented Architecture Decision
When you discover WHY something was built a certain way (not just HOW).
→ Log the decision, the alternatives considered, and the rationale.

TRIGGER 3: Workaround for Framework/Library Limitation
When the "correct" approach doesn't work and you need an alternative.
→ Log what didn't work, why, and what works instead.

TRIGGER 4: Performance Finding
When profiling or observation reveals unexpected performance behavior.
→ Log the finding, the measurement, and the optimization applied.

TRIGGER 5: External Service Behavior
When an external API/service behaves differently than documented.
→ Log the expected vs actual behavior and any workaround.

TRIGGER 6: Non-Obvious Configuration
When a setting or configuration has a surprising effect.
→ Log the configuration, the surprising behavior, and the correct setup.
```

### Category System

Use these 6 categories consistently:

```
Architecture Decision  — WHY something is structured a certain way
Bug Root Cause        — Non-obvious bugs where the error ≠ the cause
Performance Discovery — Unexpected performance behavior or optimization
Pattern Found         — Reusable pattern discovered in the codebase
Gotcha                — Surprising behavior in frameworks, libraries, or APIs
External Service      — Quirks of third-party services and APIs
```

### Practical Logging Workflow

How to log during active development:

```
DURING WORK:
1. You encounter something non-obvious
2. Spend 30 seconds writing a log entry (2-4 lines)
3. Include the category, a descriptive title, and affected files
4. Continue working — the entry is captured, detail can be added later

ENTRY QUALITY LEVELS:
Quick (during work):  Date | Category | Title + 1-line description + files
Full (if time allows): Date | Category | Title + full description + resolution + files

A quick entry is infinitely better than no entry.
```

### Log vs. Memory vs. Handoff

Distinguish between the three knowledge stores:

```
MEMORY.md (via self-correction-loop):
- Contains: Prescriptive rules ("always do X", "never do Y")
- Source: User corrections, promoted learning log entries
- Lifespan: Permanent until proven wrong
- Format: Category → bullet point rules

.claude/learning-log.md (this skill):
- Contains: Descriptive insights ("X happens because Y")
- Source: Organic discoveries during development
- Lifespan: 3-6 months, then archive or promote
- Format: Date | Category | Title | Description | Files

.claude/handoff.md (via wrap-up-ritual):
- Contains: Session state (done/pending/learned)
- Source: End of each session
- Lifespan: Until next session overwrites it
- Format: Completed / Pending / Learned sections
```

## Anti-patterns

### Logging Everything

```
// BAD — low-value entries that add noise
## 2025-07-15 | Pattern Found | Used Primary Constructors
Used primary constructors for the OrderService class.
**Files:** src/Orders/OrderService.cs

// GOOD — only log when it's non-obvious or surprising
## 2025-07-15 | Gotcha | Primary Constructor Parameters Captured as Fields
Primary constructor parameters in C# 14 are implicitly captured as fields.
If you also declare an explicit field with the same name, you get a compiler
warning but no error — and the two can silently diverge.
**Files:** src/Orders/OrderService.cs:5
```

### No Categorization

```
// BAD — entries without categories are unsearchable
## 2025-07-15 | Compiled queries don't support Include()
## 2025-07-14 | MassTransit consumer ordering matters
## 2025-07-13 | Orders module uses VSA, Identity uses CA

// GOOD — categories enable filtering and pattern detection
## 2025-07-15 | Performance Discovery | Compiled Queries Don't Support Include()
## 2025-07-14 | Gotcha | MassTransit Consumer Registration Order Matters
## 2025-07-13 | Architecture Decision | Why Orders Uses VSA While Identity Uses CA
```

### Write-Only Log (Never Reviewed)

```
// BAD — 100 entries, never reviewed
.claude/learning-log.md grows to 500 lines
Same gotchas keep appearing because no one reads the log
No entries are promoted to MEMORY.md

// GOOD — monthly reviews extract value
Every 20 entries, scan for patterns
Promote recurring findings to MEMORY.md as preventive rules
Archive stale entries
The log stays lean and the rules get stronger
```

### Duplicating MEMORY.md Content

```
// BAD — restating a MEMORY.md rule as a log entry
MEMORY.md: "Always use TimeProvider instead of DateTime.Now"
learning-log.md: "## Gotcha | DateTime.Now Is Not Testable" ← redundant

// GOOD — log adds a concrete incident the rule doesn't capture
learning-log.md: "## Bug Root Cause | Flaky Test Due to DateTime.Now
  OrderExpiry test failed intermittently — DateTime.Now crossed midnight during run."
```

## Decision Guide

| Scenario | Action |
|----------|--------|
| Found a non-obvious bug root cause | Log it — category: Bug Root Cause |
| Discovered why code is structured a certain way | Log it — category: Architecture Decision |
| Framework behaved unexpectedly | Log it — category: Gotcha |
| Performance surprise (good or bad) | Log it — category: Performance Discovery |
| Found a reusable pattern in the codebase | Log it — category: Pattern Found |
| External API behaved differently than docs say | Log it — category: External Service |
| User corrected Claude's code | Don't log — use `self-correction-loop` for MEMORY.md |
| Routine code change, nothing surprising | Don't log — only log insights |
| Same gotcha appeared 3+ times in the log | Promote to MEMORY.md as a preventive rule |
| Learning log exceeds 50 entries | Monthly review — archive old, promote recurring |
| Starting a new session | Scan recent log entries for context on the working area |