Capturing Learning from Completed Work

What this skill does

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

| Rationalization | Reality |
|----------------|---------|
| "I remember what happened" | Memory fades in days. Future you won't remember details. |
| "Too tired to write it up" | Most tired = most learning. 10 minutes now saves hours later. |
| "It's all in the commits" | Commits show WHAT changed, not WHY you chose this approach. |
| "Not worth documenting" | If you spent >30 min on it, someone else will too. Document it. |
| "It was too simple/small" | If it wasn't obvious to you at first, it won't be obvious to others. |
| "Anyone could figure this out" | You didn't know it before. Document for past-you. |
| "Nothing significant happened" | Every task teaches something. Capture incremental learning. |
| "User wants to move on" | User wants quality. Learning capture ensures it. |

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

Decide where to capture based on these criteria:

**Add to CLAUDE.md/AGENTS.md when:**
- Universal lesson (applies to most tasks in this repo)
- Instruction file is <200 lines (check with `wc -l`)
- Quick pattern/anti-pattern (1-3 lines)
- Example: "Always run tests before committing"

**Create separate file `docs/learning/YYYY-MM-DD-topic.md` when:**
- Instruction file is >200 lines (approaching limit)
- Edge case or specific scenario (not universal)
- Detailed explanation needed (>5 lines)
- Example: debugging a specific integration issue

**Bloat warning:** Retrospective content can quickly bloat instruction files. Prefer docs/learning/ for detailed write-ups. Only add to instruction files if the lesson is truly universal.

**Before adding to instruction files:**
1. Check current size: `wc -l CLAUDE.md`
2. Ask: "Will this apply to most tasks?" If no → docs/learning/
3. Use `cipherpowers:maintaining-instruction-files` skill for quality verification

**Minimal structure:**
```markdown
## [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:
- `/cipherpowers: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.