Learning Log

What it does

When your agent uses it

• Asks about learnings
• What did we learn
• Document this finding

Example prompts

• “learnings”
• “discoveries”
• “gotchas”
• “/learning-log”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

1. 1Log insights, not rules — MEMORY.md stores corrective rules ("always use X instead of Y"). The learning log stores discoveries ("X behaves…
2. 2Structure enables searchability — Every entry has a date, category, title, description, and affected files. Consistent structure means you…
3. 3Log during work, not after — Capture insights the moment they occur. Waiting until the end of a session means half the detail is lost. A…
4. 4Periodic review extracts patterns — A monthly scan of the learning log reveals recurring themes. Three "gotcha" entries about the same…
5. 5Distinct from handoff notes — The wrap-up-ritual handoff captures session state (done/pending/learned). The learning log is a persistent…

What it can do on your machine

Read from SKILL.md and the folder at commit a31015f. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Learning Log loads about 2.2k tokens when it runs. Until then it costs about 143 tokens; SKILL.md has 370 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~143

When it runs · the whole SKILL.md, loaded when a task matches

~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Resgrid/Core at commit a31015f, republished under its Apache-2.0 licence (© Resgrid). 370 words, ~2,179 tokens.

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

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

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.

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

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.

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

// 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

// 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

// 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

// 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."

© Resgrid, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .forge/skills/learning-log of Resgrid/Core.

Open the folder on GitHubat commit a31015f