Error Learning — Register, Generalize, Prevent

You made a mistake and the user corrected you. This is valuable signal. Your job is to turn this correction into a reusable lesson that prevents you — and future agents — from repeating it.

1. Analyze the Error

When the user points out a correction, identify EXACTLY what went wrong. Classify the root cause:

Cause	Description	Example
wrong-assumption	Assumed something without verifying	"Assumi que a API aceitava array mas aceita string"
missing-context	Didn't read/search before acting	"Editei sem ler o estado atual do arquivo"
unknown-pattern	Didn't know the correct pattern	"Não sabia que PS 5.1 não suporta ternary"
wrong-scope	Solved the wrong problem	"Corrigi o sintoma, não a causa raiz"
skipped-verification	Didn't test/validate before delivering	"Não rodei os testes antes de commitar"

Be honest. The cause determines how useful the lesson will be.

2. Generalize

Transform the specific case into a generic rule that covers SIMILAR scenarios:

• Specific: "errei neste regex de conventional commits"
• Generic: "sempre validar regex contra spec oficial quando envolve padrão público"

The generalization must cover more than the exact case. Ask yourself: "In what other situations would this same mistake happen?" — that's the scope of your rule.

Bad generalization: "não errar em conventional commits regex" (too narrow — just restates the error). Good generalization: "validar qualquer regex-based matching contra a spec/fonte autoritativa antes de usar" (covers all pattern-matching against public standards).

3. Persist as Lesson

Create a lesson file:

• Location: ~/.copilot/lessons/ (create directory if it doesn't exist)
• Name: L{NNN}-{slug}.md — NNN is zero-padded sequential, slug is kebab-case of the title
• Before creating: check existing files to determine the next sequential ID

Template

---
id: L{NNN}
tags: [{action}, {domain}]
confidence: 0.7
created: {YYYY-MM-DD}
cause: {cause-classification}
---

# {Title — imperative, max 60 chars}

## Resumo
{Max 2 lines. This is what gets injected into agent context by the lesson-injector hook.
Keep it dense and actionable — the hook injects ONLY this.}

## Registro
- **O que aconteceu**: {describe the concrete error}
- **Causa raiz**: {classification} — {explanation of why it happened}
- **Correção aplicada**: {what the user corrected}
- **Generalização**: {generic rule derived from this case}

Rules for the Template

• The Resumo MUST be max 2 lines — it's the injected payload. Dense and actionable.
• The id is sequential — list ~/.copilot/lessons/L*.md and increment from the highest found. Start at L001 if no lessons exist.
• confidence starts at 0.7 for direct user corrections. Higher confidence (0.8-0.9) is reserved for lessons confirmed by multiple occurrences.

4. Assign Tags

Tags determine when the lesson-injector hook surfaces this lesson. Use relevant combinations:

Action tags (what the agent was doing): create, modify, delete, search, configure, fix

Domain tags (what area was involved): file-operations, git, regex, api, testing, hooks, agents, skills, shell, cross-platform, yaml, json, markdown, dependencies

Assign 2-4 tags per lesson. At least one action tag and one domain tag.

5. Confirm with the User

Before saving the lesson file, present:

1. The generalization you derived
2. The tags you chose
3. The resumo (2-line summary)

Ask: "Essa generalização faz sentido? Cobre bem o cenário?"

Only save after the user confirms or adjusts.

6. Consolidation (30+ lessons)

When the lessons directory has 30 or more active lessons:

1. Identify clusters — lessons with the same cause classification or overlapping tags
2. Propose merges — combine similar lessons into one broader lesson with higher confidence
3. Archive absorbed lessons — move merged originals to ~/.copilot/lessons/archive/
4. Resequence is NOT needed — IDs are permanent identifiers, gaps are fine

Merge Example

Before:

• L003 — "Ler arquivo antes de editar" (tags: modify, file-operations)
• L012 — "Verificar estado do git antes de commit" (tags: modify, git)
• L018 — "Checar config existente antes de alterar" (tags: modify, configure)

After merge:

• L031 — "Sempre verificar estado atual antes de qualquer modificação" (tags: modify, file-operations, git, configure) — confidence: 0.85

Archived: L003, L012, L018 → ~/.copilot/lessons/archive/

Rules

• NEVER save a lesson without user confirmation of the generalization
• NEVER write a resumo longer than 2 lines — the hook has a 500-char context budget
• ALWAYS check existing IDs before creating a new lesson — avoid ID collision
• ALWAYS classify the root cause — "I made a mistake" is not a classification
• ALWAYS generalize beyond the specific case — a lesson that only covers one scenario is a note, not a lesson
• Confidence starts at 0.7 — only increase when the same lesson prevents a recurrence or the user explicitly validates it as high-value

Integration with lesson-injector Hook

The lesson-injector hook (~/.copilot/hooks/scripts/lesson-injector.ps1) automatically injects relevant lessons from ~/.copilot/lessons/ into the agent's context at PreToolUse. This closes the feedback loop:

1. User corrects agent → error-learning skill creates a lesson
2. Next interaction → lesson-injector hook injects relevant lessons
3. Agent avoids repeating the same mistake

You don't need to manually reference lessons — the hook handles injection based on tags and relevance.