unravel-lessons

name	unravel-lessons
description	Captures user corrections and recurring mistakes into tasks/lessons.md and proposes rule or skill updates for UnravelEngine. Use after any user correction, rejected approach, or repeated mistake pattern.
disable-model-invocation	true

Unravel Lessons

Turn corrections into durable project memory.

When to run

• User says the approach was wrong
• User rejects a diff or reverts a pattern
• Same mistake appears twice in a session
• A non-obvious engine convention is clarified

Workflow

1. Append to lessons file

Add one entry to tasks/lessons.md (create file if missing):

## YYYY-MM-DD — Short title

**Context:** What task was being done
**Mistake:** What went wrong
**Correct pattern:** What to do instead
**Files:** Key paths involved

Keep entries concise. One pattern per entry.

2. Evaluate escalation

Symptom	Action
Style/naming violation	Already covered by AGENTS.md - cite the section in the lesson only
Repeated domain mistake	Propose addition to relevant .agents/skills/unravel-*/SKILL.md
Universal workflow issue	Propose addition to AGENTS.md
One-off edge case	Lesson entry only

3. Propose skill/rule update

When escalating, draft a minimal addition (1-5 lines) — do not rewrite entire skills.

Ask user before modifying rules/skills unless they explicitly requested autonomous lesson integration.

Entry template

## 2026-07-09 — Menu bar alignment needs frame padding

**Context:** Right-aligning Stats toggle in viewport menu bar
**Mistake:** Used `CalcTextSize` only; MenuItem wider than label text
**Correct pattern:** `item_width = text_width + FramePadding.x * 2`; subtract `FramePadding.x` from avail width for `AlignedItem`
**Files:** `editor/editor/hub/panels/viewport_stats_overlay.cpp`

Hard rules

• Never delete existing lessons
• Do not duplicate lessons already captured
• Lessons are factual patterns, not opinions
• Review tasks/lessons.md at session start for tasks in the same domain