---
name: aprender-de-git-diff
description: >
  Extrae una lección dominante (máximo 2-3) desde git history — branch diff
  contra main, últimos N commits, o un commit específico. Mapea los cambios
  observados a principios de ingeniería catalogados en `~/.claude/rules/` y
  `reglas/`. Cargar cuando el usuario pide "qué aprendimos aquí", "reflexión
  sobre el código", "engineering takeaway", o tras un cierre de sesión
  productiva donde valga capturar el patrón validado. Adaptación de
  `lesson-learned` de agent-toolkit. NO escribe APRENDIZAJES.md por sí solo
  — propone la entrada para que el usuario apruebe vía `/swl:aprender`.
version: "1.0.0"
herramientasPermitidas: [Read, Grep, Glob, Bash]
exclusiones:
  - "No cargar si el rango de análisis son <5 LOC o un solo commit de typo/rename/formato — no hay lección que extraer."
  - "No cargar para extraer aprendizaje de feedback verbal del usuario; ese flujo es `/swl:aprender` (triggered por feedback, no por git)."
  - "No cargar para análisis de codebase completo o auditoría — usar `mapear-codebase` o `revisor-codigo-swl`."
  - "No cargar para sesiones sin commits realizados todavía; primero realizar el trabajo, luego analizarlo."
evolvable: true
---

# Habilidad: Aprender desde git diff

## Propósito

Convertir el código que el usuario acaba de escribir en un espejo de los
principios de ingeniería que ya está aplicando (o que omite). No es una
lección abstracta — es la lectura del propio diff con vocabulario de
principios. El skill triggered por git complementa `/swl:aprender`
(triggered por feedback) cubriendo el vector "el código habla por sí
mismo".

## Cuándo cargar

- Usuario pregunta "¿qué lección hay aquí?", "¿qué aprendimos?",
  "engineering takeaway".
- Tras un cierre de sesión con commits sustantivos donde valga reforzar el
  patrón validado.
- Al final de una rama de feature, antes del merge, para capturar el
  principio dominante.
- Para revisar el propio trabajo del agente al cierre de un PR.

## Cuándo NO cargar

Listado en `exclusiones` del frontmatter — incluye rangos triviales,
feedback verbal sin código (esa es `/swl:aprender`), auditoría de codebase
completo y sesiones sin commits.

---

## Fases del análisis

### Fase 1 — Determinar scope

Preguntar al usuario o inferir del contexto:

| Scope | Comandos git | Cuándo aplicar |
|---|---|---|
| Branch feature | `git log main..HEAD --oneline` + `git diff main...HEAD` | Rama no-main (default) |
| Últimos N commits | `git log --oneline -N` + `git diff HEAD~N..HEAD` | Usuario da rango, o estamos en main (N=5 default) |
| Commit específico | `git show <sha>` | Usuario referencia commit |
| Working changes | `git diff` + `git diff --cached` | Usuario dice "estos cambios" antes de commit |

**Default**: si estamos en rama feature, analizar branch vs main. Si en
main, últimos 5 commits.

### Fase 2 — Recolectar cambios

- `git log` para mensajes de commit (los mensajes contienen intent que el
  diff puro pierde).
- `git diff` para los cambios.
- Si el diff supera 500 líneas: `git diff --stat` primero, luego leer
  selectivamente los 3-5 archivos con más cambios.
- **Solo leer archivos cambiados**. No expandir a todo el repo.

### Fase 3 — Analizar y mapear a principios

Identificar el **patrón dominante** — la cosa más instructiva sobre estos
cambios. Buscar:

- **Decisiones estructurales**: ¿cómo se organizó? ¿por qué esas
  fronteras?
- **Trade-offs hechos**: ¿qué se ganó vs sacrificó? (legibilidad vs
  rendimiento, DRY vs claridad, velocidad vs corrección).
- **Problemas resueltos**: ¿qué cambió del antes al después?
- **Oportunidades perdidas**: ¿dónde podría mejorar? (presentar como
  "la próxima vez, considera...").

**Mapeo a catálogo de SWL** — usar como referencia:

1. `~/.claude/rules/estilo-codigo.md` — DRY, KISS, funciones cortas,
   early return, sin código muerto.
2. `~/.claude/rules/arquitectura.md` — SOLID, módulos profundos, DI,
   separación de concerns, patrones reconocidos.
3. `~/.claude/rules/pruebas.md` — AAA, factories sobre fixtures, tests
   deterministas, edge cases.
4. `~/.claude/rules/seguridad.md`, `seguridad-agentes.md` — OWASP,
   privilegio mínimo, anti-fallback.
5. `~/.claude/rules/arreglar-al-detectar.md` — detectar→informar→
   arreglar, anti-deuda silenciosa.
6. `reglas/` del proyecto — convenciones locales.
7. `.planning/APRENDIZAJES.md` — patrones ya validados (no repetir).

Ser **específico**: citar archivo:línea concreto, no afirmaciones vagas.

### Fase 4 — Presentar la lección

Plantilla obligatoria:

```markdown
## Lección: [Nombre del principio]

**Qué pasó en el código:**
[2-3 oraciones describiendo el cambio específico, con archivos y commits]

**El principio en acción:**
[1-2 oraciones explicando el principio de ingeniería, citando la regla
SWL si aplica: `reglas/X.md § sección`]

**Por qué importa:**
[1-2 oraciones sobre la consecuencia práctica — qué saldría mal sin esto,
qué sale bien gracias a esto]

**Para próxima vez:**
[Una oración accionable y concreta]
```

Si hay una segunda lección que vale la pena (máximo 2 adicionales):

```markdown
---

### También digno de mención: [Principio]

**En el código:** [1 oración]
**El principio:** [1 oración]
**Para próxima vez:** [1 oración]
```

### Fase 5 — Propuesta de entrada en APRENDIZAJES.md

Tras presentar la lección al usuario, ofrecer la entrada que se podría
agregar a `.planning/APRENDIZAJES.md`:

```markdown
### [YYYY-MM-DD] <Título corto>

**rating**: HIGH / MEDIUM / LOW
**fuente**: git commits <sha-corto>..<sha-corto>
**principio**: <referencia a regla SWL>

**Contexto**: <qué hacíamos>
**Lección aplicada**: <lo extraído>
**Evidencia**: <archivo:línea principal>
```

El usuario decide si la entrada se añade vía `/swl:aprender`. Este skill
**NO escribe directamente APRENDIZAJES.md** — propone, el usuario aprueba.

---

## Qué NO hacer

| Evitar | Por qué | En su lugar |
|---|---|---|
| Listar cada principio que vagamente aplica | Abrumador y genérico | Elegir 1-2 más relevantes |
| Analizar archivos no cambiados | Scope creep | Stick al diff |
| Ignorar commit messages | Tienen intent que el diff pierde | Leerlos como contexto primario |
| Consejo abstracto desconectado del código | No accionable | Siempre referenciar archivo:línea |
| Feedback solo negativo | Desmoralizante | Liderar con qué funciona, luego sugerir |
| Más de 3 lecciones | Diluye el insight | Una bien fundada vence siete vagas |

---

## Reglas obligatorias

1. **Reflexivo, no prescriptivo**: usar el código del usuario como
   evidencia primaria. **Por qué**: si el agente da consejo abstracto,
   no usa el material que ya tiene a la vista — desperdicia la
   especificidad del diff.

2. **Nunca decir "deberías haber..."**: usar "el enfoque aquí muestra..."
   o "la próxima vez que enfrentes esto, considera...". **Por qué**:
   tono de auditor erosiona la conversación; el skill es espejo, no juez.

3. **Si el código es bueno, decirlo**: no toda lección es sobre lo que
   salió mal. Reconocer patrones buenos los refuerza. **Por qué**:
   feedback solo negativo desmoraliza y oculta el valor del trabajo
   completado.

4. **Si los cambios son triviales, decirlo**: "Estos cambios son
   directos — no hay lección profunda aquí, solo buen mantenimiento".
   **Por qué**: forzar una lección donde no la hay es ruido.

5. **Específico, no genérico**: cada claim apunta a un cambio concreto
   de código con archivo:línea o sha. **Por qué**: consejo genérico ya
   está en las reglas — el valor de este skill es la conexión con el
   diff concreto.

6. **Una lección dominante, máximo 3**: priorizar. **Por qué**: 7
   lecciones tibias no equivalen a 1 lección con peso.

7. **No escribir APRENDIZAJES.md directamente**: proponer la entrada,
   el usuario aprueba vía `/swl:aprender`. **Por qué**: APRENDIZAJES.md
   es memoria curada del usuario — escritura automática diluye su
   calidad.

---

## Relación con otras herramientas SWL

- **`/swl:aprender`**: triggered por feedback verbal del usuario.
  Este skill es triggered por git history. Vectores complementarios.
- **`revisor-codigo-swl`**: emite veredicto de calidad con score y
  hallazgos. Este skill extrae **principios**, no hallazgos. Pueden
  ejecutarse en secuencia.
- **`/swl:compactar`** + **`/swl:checkpoint`**: cierran sesión preservando
  estado. Este skill puede invocarse durante el cierre para capturar
  el aprendizaje antes de compactar.
- **Skill `meta-skills-estandar`**: catálogo de principios para crear
  skills. Este skill consume principios para reportar; meta-skills los
  define para producir.

---

## Ejemplo de uso

Usuario tras una sesión con 4 commits: *"¿qué aprendimos aquí?"*.

Agente carga este skill:

```
## Lección: Detección y prevención coordinadas

**Qué pasó en el código:**
Los 4 commits añadieron `tests/_helpers/sandbox.js` con auto-cleanup
vía `node:test after()` y refactorizaron 16 tests existentes para
usarlo (PR #35). El bug original — 5,800+ carpetas huérfanas en %TEMP%
— era acumulación de `fs.mkdtempSync` sin `rmSync`.

**El principio en acción:**
Fix sistemático en lugar de fix por archivo, alineado con
`reglas/arquitectura.md § Módulos profundos` (interfaz pequeña,
implementación rica). El helper expone 3 funciones (`create`, `list`,
`cleanup`) que ocultan la mecánica de `mkdtempSync`/`rmSync` y el
registro automático de `after()`.

**Por qué importa:**
Sin el helper, el patrón se hubiera "olvidado" en el siguiente test
nuevo — la misma causa raíz se hubiera reintroducido. Con el helper,
el nuevo test simplemente llama `sandboxes.create()`; el cleanup es
automático y no negociable.

**Para próxima vez:**
Al detectar un patrón roto en >3 archivos, pausar el fix por archivo
y diseñar el helper que lo previene estructuralmente.

---

### También digno de mención: separación FIFO de teardowns

**En el código:** `singleton-guard.test.js` y `nudge-tracker.test.js`
añadieron `after(() => process.chdir(repoRoot))` ANTES de
`setupSandboxes()` para que el restore de CWD ocurra antes del
cleanup, evitando EBUSY en Windows.
**El principio:** ordering explícito de teardowns donde el cleanup
depende de estado externo. `node:test` ejecuta los `after()` en FIFO,
así que el orden de declaración importa.
**Para próxima vez:** cuando un test cambia CWD, restaurar CWD ANTES
de cualquier cleanup de filesystem que dependa de ese CWD.

---

**Entrada propuesta para APRENDIZAJES.md** (aprueba con `/swl:aprender` o ignora):

### [2026-05-17] Helper estructural para prevenir patrón roto

**rating**: HIGH
**fuente**: commits bff27bb..b431360 (PR #35-#36)
**principio**: `reglas/arquitectura.md § Módulos profundos`

**Contexto**: 16 tests usaban mkdtempSync sin cleanup, acumulando 5,800
carpetas en %TEMP% tras ~76 corridas.
**Lección aplicada**: cuando >3 archivos repiten un patrón roto,
diseñar helper que lo prevenga estructuralmente en lugar de fix por archivo.
**Evidencia**: `tests/_helpers/sandbox.js:14-30` (3 funciones públicas
encapsulando 1 cleanup automático).
```
