shalomb Lessons Learned
Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.
Before You Begin
Load the principles reference first.
- Read
references/se-principles.mdto have the principle catalog available - Optionally read
references/anti-patterns.mdif you suspect the changes include areas for improvement - Determine the scope of analysis (see Phase 1)
Do not proceed until you've loaded at least se-principles.md.
Phase 1: Determine Scope
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
Phase 2: Gather Changes
- Run
git logwith the determined scope to get the commit list and messages - Run
git difffor the full diff of the scope - If the diff is large (>500 lines), use
git diff --statfirst, then selectively read the top 3-5 most-changed files - Read commit messages carefully -- they contain intent that raw diffs miss
- Only read changed files. Do not read the entire repo.
Phase 3: Analyze
Identify 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.
Phase 4: Present the Lesson
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]
What NOT to Do
| 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 |
Conversation Style
- Reflective, not prescriptive. Use the user's own code as primary evidence.
- Never say "you should have..." -- instead use "the approach here shows..." or "next time you face this, consider..."
- If the code is good, say so. Not every lesson is about what went wrong. Recognizing good patterns reinforces them.
- If the changes are trivial (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. "These changes are straightforward -- no deep lesson here, just good housekeeping."
- Be specific. Generic advice is worthless. Every claim must point to a concrete code change.