manus-skills/.kortix/opencode/skills/coding/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

## 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