Lesson Learned

# 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


---
description: Common anti-patterns to detect in code diffs. Use alongside se-principles.md for balanced analysis -- principles show what's good, anti-patterns show what to watch for.
---

# Anti-Patterns

When analyzing a diff, check for these signals. Present findings gently -- as opportunities, not failures.

## God Object / God Class

One module doing too much.
**Diff signals:** A single file with many unrelated changes. One class/module imported everywhere. A file over 500 lines that keeps growing.
**Suggest:** Extract responsibilities into focused modules (SRP).

## Shotgun Surgery

One logical change scattered across many files.
**Diff signals:** 10+ files changed for a single feature or fix. The same type of edit repeated in many places. A rename or config change touching dozens of files.
**Suggest:** Consolidate the scattered logic. If one change requires editing many files, the abstraction boundaries may be wrong.

## Feature Envy

A function that uses another module's data more than its own.
**Diff signals:** Heavy cross-module imports. A function reaching deep into another object's properties. Utility functions that only serve one caller in a different module.
**Suggest:** Move the function closer