lesson-learned

Visión general de la skill lesson-learned

La skill lesson-learned convierte la actividad reciente de Git en aprendizajes concretos de ingeniería de software. En lugar de dar consejos abstractos, inspecciona diffs reales, el historial de commits y los archivos modificados, y luego relaciona lo ocurrido con principios con nombre como SRP, DRY, KISS, YAGNI y anti-patterns afines. Por eso, lesson-learned resulta especialmente útil para desarrolladores que ya hicieron cambios en el código y quieren responder a preguntas como: ¿qué nos enseñó este trabajo?, ¿qué trade-off aceptamos? y ¿qué conviene repetir o evitar la próxima vez?

Para quién es la skill lesson-learned

Encaja mejor para:

• desarrolladores que están cerrando una feature, un refactor, una corrección de bug o una tarea de limpieza
• reviewers que quieren un resumen orientado al aprendizaje después de una PR
• team leads que quieren crear hábitos ligeros de reflexión de ingeniería
• agentes que necesitan explicar el principio detrás de cambios recientes en el código

Si buscas una reflexión de diseño apoyada en el historial real del repositorio, la lesson-learned skill es mejor opción que un prompt genérico de “review this code”.

Qué trabajo hace realmente esta skill

Su función principal no es hacer code review en el sentido habitual de aprobado/rechazado. lesson-learned mira hacia atrás, sobre trabajo terminado o en curso, y extrae entre 1 y 3 aprendizajes respaldados por el diff. Las buenas salidas suelen incluir:

• el nombre del principio
• cómo lo demuestra el cambio
• por qué importa
• una recomendación de siguiente paso

Ese enfoque la vuelve especialmente útil para retrospectivas, mentoría y notas de aprendizaje en PRs.

Qué diferencia a lesson-learned de un prompt genérico

Hay dos factores clave:

1. Está guiada por el historial de Git, así que analiza cambios reales en vez de fragmentos hipotéticos.
2. Requiere un catálogo de principios, especialmente references/se-principles.md, que le da al modelo un vocabulario para nombrar patrones de forma consistente.

Esa combinación ayuda a que la skill produzca aprendizajes que realmente se desprenden del código, y no que parezcan copiados de un manual de ingeniería de software.

Cuándo no conviene elegir lesson-learned

No uses lesson-learned si tu objetivo real es:

• encontrar bugs línea por línea antes del merge
• hacer una auditoría de seguridad
• recibir feedback de lint o estilo únicamente
• planificar arquitectura cuando todavía no hay cambios de código
• revisar un codebase grande sin un alcance claro

En esos casos, suele ser mejor empezar con una skill de code review, seguridad o diseño.

Cómo usar la skill lesson-learned

Contexto de instalación de lesson-learned

El repositorio no publica un comando de instalación dedicado dentro de skills/lesson-learned/SKILL.md, así que la instalación depende de cómo cargues skills desde softaworks/agent-toolkit. Si tu entorno permite añadir una skill desde ese repositorio, el patrón más común es:

npx skills add softaworks/agent-toolkit --skill lesson-learned

Si tu agente carga skills directamente desde el repo, usa la ruta de la skill:

skills/lesson-learned

En ambos casos, conviene tratar SKILL.md como la especificación de comportamiento en tiempo de ejecución, no solo como un README.

Lee estos archivos antes del primer uso

Para empezar rápido y con pocas suposiciones, lee los archivos en este orden:

1. skills/lesson-learned/SKILL.md
2. skills/lesson-learned/references/se-principles.md
3. skills/lesson-learned/references/anti-patterns.md
4. skills/lesson-learned/README.md

El detalle más importante para adoptarla, y fácil de pasar por alto, es que la skill dice explícitamente que no se debe continuar sin cargar antes se-principles.md.

Qué entrada necesita la skill lesson-learned

lesson-learned usage funciona mejor cuando el modelo puede acceder a:

• un repositorio con historial de Git
• el nombre de la rama actual o un objetivo de comparación con nombre, como main
• un rango de commits, un SHA de commit, un diff entre ramas o un diff del working tree
• suficiente contexto de archivos para inspeccionar los archivos con más cambios

Sin contexto de Git, la salida se vuelve genérica muy rápido.

Elige primero el alcance correcto del análisis

Esta skill solo es tan buena como el alcance que le des. El repositorio define valores prácticos por defecto:

• feature branch: comparar el trabajo de la rama contra main
• main branch: analizar los últimos 5 commits
• specific commit: inspeccionar un único SHA
• working changes: inspeccionar los diffs staged y unstaged

Una buena lesson-learned guide empieza forzando esa elección desde el principio. Si el alcance es difuso, el resultado suele mezclar aprendizajes que no tienen relación entre sí.

Comandos de Git útiles para un mejor uso de lesson-learned

El propio flujo de la skill se apoya en vistas comunes de Git como:

• git log main..HEAD --oneline
• git diff main...HEAD
• git log --oneline -5
• git diff HEAD~5..HEAD
• git show <sha>
• git diff
• git diff --cached

No necesitas usar todos los comandos cada vez. Elige el que mejor encaje con la historia que quieres que la skill explique.

Cómo convertir una petición vaga en un prompt sólido

Prompt débil:

“Reflect on my recent work.”

Prompt más sólido:

“Use lesson-learned on my feature branch versus main. Read references/se-principles.md first. Focus on the 3 files with the largest behavioral changes. Give me 2 lessons grounded in the diff, each with the principle name, code evidence, trade-off, and one thing I should repeat in future PRs.”

Por qué funciona:

• define el alcance
• nombra el archivo de referencia del que depende la skill
• limita la superficie de análisis
• especifica el formato de salida

Patrón de prompt para lesson-learned for Code Review

lesson-learned for Code Review funciona mejor como una capa de reflexión después del review normal, no como sustituto. Un prompt práctico sería:

“Run lesson-learned on this PR branch against main. Summarize the engineering lesson behind the changes, not just defects. Highlight 1 positive principle demonstrated, 1 anti-pattern risk if relevant, and cite the changed files that support each point.”

Esto resulta útil cuando quieres un comentario de review que enseñe, y no solo bloquee.

Formato de salida recomendado para pedir

Pide una estructura compacta como:

• Lesson
• Principle
• Evidence from changes
• Why it matters
• Next step

Esto encaja con la intención del repositorio y reduce el relleno genérico.

Cómo manejar diffs grandes

En PRs grandes, no le pidas a la skill que “analice todo”. En su lugar:

• identifica los archivos con más cambios
• agrupa los cambios por tema
• ignora las ediciones mecánicas evidentes
• pide solo entre 1 y 3 aprendizajes

La skill funciona mejor extrayendo patrones que catalogando de forma exhaustiva cada cambio de archivo.

Flujo habitual que ahorra tiempo

Un flujo fiable es:

1. cargar se-principles.md
2. elegir el alcance
3. inspeccionar el log y el diff de Git
4. leer los archivos con más cambios
5. cargar opcionalmente anti-patterns.md
6. generar entre 1 y 3 aprendizajes con evidencia
7. refinar si el resultado es demasiado amplio o demasiado moralizante

Este orden importa porque el catálogo de principios le da al análisis un vocabulario más preciso.

Preguntas frecuentes sobre la skill lesson-learned

¿La skill lesson-learned es buena para principiantes?

Sí, siempre que la persona principiante tenga cambios reales para analizar. La skill explica principios a partir de trabajo que acaba de hacer, y eso suele ser más fácil de asimilar que empezar leyendo teoría. Es bastante menos útil para alguien sin acceso al repo o sin diffs recientes.

¿lesson-learned es lo mismo que code review?

No. lesson-learned es retrospectiva y está orientada a principios. El code review suele estar orientado a corrección, riesgo y mantenibilidad. Hay solapamiento, pero el objetivo de la salida es distinto.

¿La skill lesson-learned necesita acceso a Git?

Para obtener buenos resultados, sí. El repositorio está diseñado alrededor del historial de Git y los diffs. Si solo pegas un fragmento de código, el modelo aún puede comentar principios, pero ya no está usando la skill en su modo más fuerte.

¿Qué hace que lesson-learned sea mejor que un prompt común?

La ventaja está en la estructura: selección explícita del alcance, referencias obligatorias de principios y un flujo que conecta los aprendizajes con señales concretas del código. Los prompts comunes suelen saltar directamente a “best practices” genéricas.

¿Puedo usar lesson-learned sobre cambios sin commit?

Sí. La skill admite working changes mediante git diff y git diff --cached. Eso es útil antes de hacer commit, cuando quieres entender el aprendizaje o el trade-off de lo que estás a punto de enviar.

¿Cuándo encaja mal lesson-learned?

Evítala cuando:

• no hay cambios recientes con sustancia
• el diff es principalmente ruido generado o de formato
• necesitas triage de defectos más que reflexión
• la rama mezcla muchas tareas sin relación

En esos casos, reduce el alcance o usa primero otra skill.

Cómo mejorar la skill lesson-learned

Dale a lesson-learned una historia más acotada

La mayor palanca de calidad es el alcance. “Mi trabajo del último mes” es demasiado amplio. “Este refactor que separó las llamadas a la API del renderizado de la UI” es mejor. Un alcance acotado produce aprendizajes con principios más claros y evidencia más sólida.

Carga siempre la referencia de principios

Aquí el repositorio es inusualmente explícito: references/se-principles.md debe cargarse antes del análisis. Si te lo saltas, el modelo aún puede producir observaciones, pero será menos probable que etiquete patrones de forma consistente o que los conecte con principios reconocidos.

Usa anti-patterns para equilibrar, no para volverlo negativo

references/anti-patterns.md ayuda más cuando el diff contiene señales de riesgo como ediciones dispersas, sobreabstracción o módulos “god” en crecimiento. Pide un tono suave para que el resultado siga siendo útil y no suene punitivo.

Pide evidencia vinculada a los archivos modificados

Un fallo común es obtener consejos de alto nivel sin pruebas. Para mejorar la salida de lesson-learned, pide:

• archivos modificados implicados
• qué cambio estructural ocurrió
• qué trade-off implica
• por qué eso corresponde a un principio concreto

La evidencia es lo que separa un aprendizaje real de un comentario genérico.

Limita la cantidad de aprendizajes

Más aprendizajes suele significar aprendizajes más débiles. Pide solo entre 1 y 3 conclusiones. Eso obliga a priorizar y hace que la salida sea más creíble y más fácil de usar en notas de PR, retrospectivas o coaching.

Dile a la skill qué tipo de aprendizaje quieres

Puedes orientar el análisis añadiendo una lente:

• maintainability lesson
• refactoring lesson
• bug-fix lesson
• design trade-off lesson
• team process lesson tied to code changes

Esto mejora la relevancia sin ir contra el flujo previsto de la skill.

Corrige borradores genéricos con una segunda pasada

Si el primer resultado es vago, no vuelvas a ejecutarlo desde cero de inmediato. Mejor pide:

• “Tie each lesson to a specific file or diff hunk.”
• “Replace general advice with what this branch actually demonstrates.”
• “Name the principle only if the code evidence clearly supports it.”
• “Drop any lesson that is not visible in the diff.”

Esto suele mejorar la salida más rápido que relanzar un prompt amplio.

Vigila estos modos de fallo de lesson-learned

Las salidas flojas suelen incluir:

• principios nombrados sin evidencia de código
• demasiados aprendizajes a partir de un solo diff
• confundir defectos de code review con conclusiones de aprendizaje
• lenguaje moralizante en lugar de trade-offs prácticos
• intentar resumir cambios no relacionados como si fueran un único aprendizaje

Detectarlos pronto hace que iterar sea mucho más sencillo.

Mejor camino de mejora para un uso repetido en equipo

Si un equipo planea usar lesson-learned de forma habitual, conviene estandarizar una plantilla de prompt con:

• regla de alcance
• objetivo de comparación
• número máximo de aprendizajes
• formato de evidencia obligatorio
• comprobación opcional de anti-patterns

Eso reduce la inconsistencia y hace que la lesson-learned skill sea mucho más fiable en PRs y retrospectivas.