Session Learning Auto

The Session Learning Auto command captures insights, patterns, corrections, and discoveries made during development sessions and integrates them into project memory for future reference. It identifies moments where understanding changed, problems were solved through non-obvious approaches, or important project-specific knowledge was revealed. Execute this command at the end of a development session to preserve valuable context that would otherwise be lost.

When to Use This Command

Run this command when...

• You have completed a development session where significant debugging, architectural decisions, or non-obvious solutions occurred
• You discovered project-specific behavior, undocumented APIs, or environmental quirks that future developers should know about
• You corrected a misunderstanding about how a system works and want to document the correct understanding
• You found a workaround for a known issue and want to capture it before the context fades from memory
• You want to build a cumulative knowledge base that makes each subsequent development session more productive

Consider alternatives when...

• You are documenting formal architectural decisions, which the memory command handles with structured decision records
• You need to update code documentation rather than session-level project memory
• Your learnings are general programming knowledge rather than project-specific discoveries

Quick Start

Copy
# learning-capture.yml
capture:
  auto-detect: true
  categories:
    - debugging-insights
    - architectural-discoveries
    - environment-quirks
    - workarounds
    - corrections
integration:
  memory-file: "CLAUDE.md"
  append-mode: true
  deduplicate: true
session:
  review-before-save: true

Example invocation:

Copy
/session-learning-auto --review --integrate

Example output:

Session Learning Capture
=========================
Session duration: 2.5 hours
Learnings identified: 4

1. [Debugging Insight]
   "DynamoDB TTL field must be epoch seconds, not milliseconds"
   Context: Spent 40 minutes debugging why expired items persisted
   Integration: Added to CLAUDE.md under DynamoDB Tables section

2. [Environment Quirk]
   "pnpm workspace requires --filter flag for scripts in sub-packages"
   Context: npm run build failed silently without --filter
   Integration: Added to CLAUDE.md under Environment section

3. [Workaround]
   "Vitest mock of $app/stores needs writable() wrapper, not plain object"
   Context: Component tests failed with store subscription errors
   Integration: Added to CLAUDE.md under Testing section

4. [Correction]
   "UserMemberships table is checked per-request, not cached"
   Context: Assumed membership data was cached; found it queries DynamoDB each time
   Integration: Updated existing DynamoDB Tables entry in CLAUDE.md

Memory updated: 4 entries added/modified
Knowledge base: 52 total entries

Core Concepts

Concept	Purpose	Details
Learning Detection	Identify knowledge moments	Recognizes when debugging sessions, error corrections, or discovery patterns indicate new project-specific knowledge worth capturing
Categorized Capture	Organize by learning type	Classifies learnings as debugging insights, architectural discoveries, environment quirks, workarounds, or corrections for targeted retrieval
Memory Integration	Persist to project files	Writes captured learnings into project memory files like CLAUDE.md, organizing them under relevant sections and deduplicating against existing entries
Session Context	Preserve discovery circumstances	Records not just the learning itself but the context in which it was discovered, making the entry more useful for future developers facing similar situations
Cumulative Knowledge	Build over time	Each session adds to the project knowledge base, making subsequent sessions progressively more productive as developers start with richer context

Architecture: Learning Capture
=================================

+-------------------+     +---------------------+     +------------------+
| Session Scanner   | --> | Learning Detector   | --> | Categorizer      |
| (activity review) |     | (pattern matching)  |     | (classify type)  |
+-------------------+     +---------------------+     +------------------+
                                                             |
                          +----------------------------------+
                          v
              +---------------------+     +-------------------+
              | Memory Integrator   | --> | Dedup Checker     |
              | (file writer)       |     | (existing entries) |
              +---------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
review	boolean	true	Present captured learnings for review before integrating them into memory files
integrate	boolean	true	Write approved learnings into the project memory file
memory-file	string	"CLAUDE.md"	Path to the memory file where learnings should be integrated
categories	string[]	["all"]	Categories of learnings to capture: debugging, architecture, environment, workarounds, or corrections
session-scope	string	"current"	Scope of session to analyze: current session, today, or a specific time range

Best Practices

1. Capture learnings immediately, not at the end of the week. The context surrounding a discovery fades rapidly. Running the capture at the end of each session preserves the debugging steps, environmental conditions, and reasoning that make the learning entry useful for future reference.

2. Include the context that led to the discovery. A bare fact like "DynamoDB TTL uses epoch seconds" is less useful than "DynamoDB TTL uses epoch seconds, not milliseconds; items were persisting because the TTL value was interpreted as a date in the year 53,000." Context helps future developers recognize when they are facing the same situation.

3. Review captured learnings before integration. Automatic detection may identify false positives or capture information that is too specific to be reusable. Review each learning entry to ensure it represents genuinely reusable project knowledge before committing it to the memory file.

4. Deduplicate against existing memory entries. Before adding a new learning, check whether the information already exists in the memory file. If it does, update the existing entry with any new details rather than creating a duplicate that fragments the knowledge.

5. Organize learnings under the most relevant memory section. Place each learning in the memory file section where a developer would naturally look for it. A DynamoDB discovery belongs under the DynamoDB section, not under a generic "learnings" dump, so that it surfaces when someone is working with that specific technology.

Common Issues

Auto-detection captures trivial observations alongside important insights. Not every observation during a session warrants a memory entry. The detection heuristic may flag routine debugging steps as learning moments. Use the review step to filter out trivial entries and preserve only genuinely reusable knowledge.

Memory file grows too large to be useful. Over many sessions, the memory file can accumulate hundreds of entries that become difficult to navigate. Periodically review and consolidate entries, archiving obsolete information and merging related entries into concise summaries.

Learning entries lack enough context for future developers. Entries captured in a hurry may omit the circumstances that make them useful. When reviewing entries, ensure each one includes what the correct behavior is, what the incorrect assumption was, and how to recognize the situation in the future.