softaworks/agent-toolkit / skills/lesson-learned
lesson-learned
VerifiedAnalyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.7 KB |
| SKILL.md | skill md | 4.6 KB |
| references/anti-patterns.md | markdown | 2.8 KB |
| references/se-principles.md | markdown | 5.7 KB |
README.md
View on GitHub# 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
1. **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.
2. **Gather changes** -- Reads git log, diffs, and commit messages. For large diffs, selectively reads the most-changed files.
3. **Analyze patterns** -- Identifies structural decisions, trade-offs, and problems solved. Maps observations to named SE principles.
4. **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
```markdown
## 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 catalog
- `references/anti-patterns.md` -- Common anti-patterns to detect in diffs
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |