Analyzes recent git commits or diffs to identify and articulate specific software engineering principles demonstrated by the code changes. It produces a reflective summary that maps observed patterns to established SE concepts, providing actionable takeaways for future development.
Say it in your own words; the assistant finds this recipe by itself. Examples:
Use this skill when the user wants to reflect on recent code changes to extract engineering insights or lessons. It is appropriate when the user asks questions like 'what can I learn from this?', 'what is the engineering takeaway here?', or 'reflect on my recent commits.' It is ideal for post-commit or pre-merge reviews where the goal is educational rather than bug-finding.
Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.
Load the principles reference first.
references/se-principles.md to have the principle catalog availablereferences/anti-patterns.md if you suspect the changes include areas for improvementDo not proceed until you've loaded at least se-principles.md.
Ask the user or infer from context what to analyze.
| Scope | Git Commands | When to Use |
|---|---|---|
| Feature branch | git log main..HEAD --oneline + git diff main...HEAD |
User is on a non-main branch (default) |
| Last N commits | git log --oneline -N + git diff HEAD~N..HEAD |
User specifies a range, or on main (default N=5) |
| Specific commit | git show <sha> |
User references a specific commit |
| Working changes | git diff + git diff --cached |
User says "what about these changes?" before committing |
Default behavior: - If on a feature branch: analyze branch commits vs main - If on main: analyze the last 5 commits - If the user provides a different scope, use that
git log with the determined scope to get the commit list and messagesgit diff for the full diff of the scopegit diff --stat first, then selectively read the top 3-5 most-changed filesIdentify the dominant pattern -- the single most instructive thing about these changes.
Look for: - Structural decisions -- How was the code organized? Why those boundaries? - Trade-offs made -- What was gained vs. sacrificed? (readability vs. performance, DRY vs. clarity, speed vs. correctness) - Problems solved -- What was the before/after? What made the "after" better? - Missed opportunities -- Where could the code improve? (present gently as "next time, consider...")
Map findings to specific principles from references/se-principles.md. Be specific -- quote actual code, reference actual file names and line changes.
Use this template:
## Lesson: [Principle Name]
**What happened in the code:**
[2-3 sentences describing the specific change, referencing files and commits]
**The principle at work:**
[1-2 sentences explaining the SE principle]
**Why it matters:**
[1-2 sentences on the practical consequence -- what would go wrong without this, or what goes right because of it]
**Takeaway for next time:**
[One concrete, actionable sentence the user can apply to future work]
If there is a second lesson worth noting (maximum 2 additional):
---
### Also worth noting: [Principle Name]
**In the code:** [1 sentence]
**The principle:** [1 sentence]
**Takeaway:** [1 sentence]
| Avoid | Why | Instead |
|---|---|---|
| Listing every principle that vaguely applies | Overwhelming and generic | Pick the 1-2 most relevant |
| Analyzing files that were not changed | Scope creep | Stick to the diff |
| Ignoring commit messages | They contain intent that diffs miss | Read them as primary context |
| Abstract advice disconnected from the code | Not actionable | Always reference specific files/lines |
| Negative-only feedback | Demoralizing | Lead with what works, then suggest improvements |
| More than 3 lessons | Dilutes the insight | One well-grounded lesson beats seven vague ones |
LICENSEREADME.mdSKILL.mdreferences/anti-patterns.mdreferences/se-principles.mdVendored from softaworks/agent-toolkit, commit 3027f20f3181, path skills/lesson-learned, licence MIT. The upstream licence file ships inside the skill.