Lesson Learned
Extract software engineering takeaways from your recent code changes.
Purpose
Most developers ship code and move on. But the fastest way to grow is to pause and reflect: what principle did I just apply? What trade-off did I make? What would I do differently?
This skill analyzes recent git history and surfaces the engineering lesson embedded in the work you just did.
When to Use
- After finishing a feature or PR
- After a debugging session
- After a refactor
- When you want to reflect on recent work
- Trigger phrases: "what is the lesson here?", "what can I learn from this?", "engineering takeaway"
How It Works
- Determine scope -- Detects whether you're on a feature branch (analyzes branch vs main) or main (analyzes last 5 commits). You can also specify a commit range or specific SHA.
- Gather changes -- Reads git log, diffs, and commit messages. For large diffs, selectively reads the most-changed files.
- Analyze patterns -- Identifies structural decisions, trade-offs, and problems solved. Maps observations to named SE principles.
- Present the lesson -- Delivers 1-3 specific, code-grounded takeaways with the principle name, how it manifested, why it matters, and an actionable next step.
Key Features
- Git-history-driven -- Works from actual code changes, not hypotheticals
- Principle-grounded -- Maps observations to named SE principles (SOLID, DRY, KISS, YAGNI, etc.)
- Specific, not generic -- Every insight references actual files and lines from your diff
- Balanced -- Recognizes good patterns, not just areas for improvement
- Configurable scope -- Feature branch, last N commits, specific SHA, or working changes
Output Format
## Lesson: Separation of Concerns
**What happened in the code:**
The `AuthController` was split into `AuthController` and `UserService` across
commits abc123 and def456. Authentication logic stayed in the controller while
user CRUD operations moved to a dedicated service.
**The principle at work:**
Separation of Concerns -- different responsibilities should live in different
modules so each can change independently.
**Why it matters:**
Before the split, any change to user management risked breaking authentication.
Now each module can evolve independently with a clear interface between them.
**Takeaway for next time:**
When a file handles two distinct responsibilities, split early -- it's cheaper
than untangling them later.Prerequisites
- Must be in a git repository with commit history
- Works best with descriptive commit messages
Related Files
references/se-principles.md-- Curated SE principles catalogreferences/anti-patterns.md-- Common anti-patterns to detect in diffs