Capturing Learning from Completed Work

Overview

Context is lost rapidly without systematic capture. After completing work, engineers move to the next task and forget valuable lessons, discarded approaches, and subtle issues discovered. This skill provides a systematic retrospective workflow to capture learning while context is fresh.

When to Use

Use this skill when:

• Completing significant features or complex bugfixes
• After debugging sessions (especially multi-hour sessions)
• Work took longer than expected
• Multiple approaches were tried and discarded
• Subtle bugs or non-obvious issues were discovered
• Before moving to next task (capture fresh context)
• Sprint/iteration retrospectives

When NOT to use:

• Trivial changes (typo fixes, formatting)
• Work that went exactly as expected with no learnings
• When learning is already documented elsewhere

Critical Principle

Exhaustion after completion is when capture matters most.

The harder the work, the more valuable the lessons. "Too tired" means the learning is significant enough to warrant documentation.

Common Rationalizations (And Why They're Wrong)

None of these are valid reasons to skip capturing learning.

What to Capture

✅ MUST document:

• Brief description of what was accomplished
• Key decisions made (and why)
• Approaches that were tried and discarded (and why they didn't work)
• Non-obvious issues discovered (and how they were solved)
• Time spent vs. initial estimate (if significantly different, why?)
• Things that worked well (worth repeating)
• Things that didn't work well (worth avoiding)
• Open questions or follow-up needed

Common blind spots:

• Discarded approaches (most valuable learning often comes from what DIDN'T work)
• Subtle issues (small bugs that took disproportionate time)
• Implicit knowledge (things you learned but didn't realize were non-obvious)

Implementation

Step 1: Review the Work

Before writing, review what was done:

• Check git diff to see all changes
• Review commit messages for key decisions
• List approaches tried (including failed ones)
• Note time spent and estimates

Step 2: Capture in Structure

Create or update summary in appropriate location:

For work tracking systems:

• Use project's work directory structure
• Common: docs/work/summary.md or iteration-specific file

For non-tracked work:

• Add to CLAUDE.md under relevant section
• Or create dated file in docs/learning/YYYY-MM-DD-topic.md

Minimal structure:

## [Work Item / Feature Name]

**What:** Brief description (1-2 sentences)

**Key Decisions:**
- Decision 1 (why)
- Decision 2 (why)

**What Didn't Work:**
- Approach X (why it failed, what we learned)
- Approach Y (why it failed)

**Issues Discovered:**
- Issue 1 (how solved)
- Issue 2 (how solved)

**Time Notes:**
Estimated X hours, took Y hours. [Explain if significant difference]

**Open Questions:**
- Question 1
- Question 2

Step 3: Link to Implementation

Connect learning to codebase:

• Reference key files modified
• Link to commits or PRs
• Cross-reference to CLAUDE.md if patterns emerged

Step 4: Make it Searchable

Ensure future discoverability:

• Use descriptive headings
• Include error messages if debugging
• Tag with relevant technology/pattern names

Real-World Impact

Without systematic capture:

• Repeat same failed approaches (waste time)
• Forget subtle issues (encounter again later)
• Lose context on decisions (question past choices)
• Can't transfer knowledge to team
• Learning stays with individual

With this workflow:

• Failed approaches documented (others avoid same path)
• Subtle issues captured (searchable solutions)
• Decision rationale preserved (future maintenance easier)
• Knowledge shared across team
• Organization builds learning repository

Integration with Commands/Agents

This skill can be invoked by:

• /summarise command for retrospective capture
• Pre-merge checklist item
• Sprint/iteration retrospective workflows
• Code review requirements

Commands should provide context about where to save summaries and reference this skill for methodology.