speclet-learn
Generate explanatory lessons after completing speclet stories to develop mechanical coding fluency
When & Why to Use This Skill
Speclet-learn is a specialized developer education tool that transforms completed coding tasks into structured, personalized lessons. By analyzing recently modified files and technical stories, it generates comprehensive study guides that explain architectural decisions, categorize code complexity (from basic syntax to advanced patterns like Async or Dependency Injection), and provide 'no-LLM' practice exercises to build genuine mechanical coding fluency.
Use Cases
- Post-Implementation Review: Automatically generate a technical breakdown after completing a feature to reinforce the logic and patterns used in the production code.
- Technical Skill Upskilling: Use the complexity-based explanations to master intermediate and advanced concepts like decorators, context managers, or custom generators encountered during daily work.
- Deliberate Practice Routine: Incorporate 15-minute 'no-LLM' coding challenges into a pre-work routine to build muscle memory and reduce over-reliance on AI assistants.
- Knowledge Retention for Teams: Create a library of lessons based on successfully completed 'stories' to help junior developers understand the technical 'why' behind specific implementation choices.
| name | speclet-learn |
|---|---|
| description | Generate explanatory lessons after completing speclet stories to develop mechanical coding fluency |
| license | MIT |
| compatibility | opencode |
| workflow | speclet |
| audience | developers-learning |
Speclet Learn Skill
Genera lecciones explicativas después de cada story completada para desarrollar fluidez mecánica.
What I Do
- Leo spec.json y encuentro la última story con
passes: true - Analizo los archivos modificados en esa story
- Genero una lección en
.speclet/lessons/STORY-X.mdcon:- Decisiones técnicas (por qué X y no Y)
- Conceptos explicados según complejidad detectada
- Código anotado
- Errores comunes
- Ejercicio de práctica (10-15 min, sin LLM)
When to Use Me
Después de completar stories con speclet-loop:
/speclet-learn
Ideal para tu rutina de 30 min de práctica antes del trabajo.
Your Task
Step 1: Find Last Completed Story
Lee .speclet/spec.json y encuentra la última story con "passes": true.
# Busca la story con passes: true y el priority más alto (última completada)
Si no hay stories con passes: true, responde:
❌ No hay stories completadas aún. Primero completa al menos una story con /speclet-loop.
Step 2: Read Modified Files
Lee los archivos del campo "files" de esa story.
Analiza:
- Qué patrones se usaron
- Qué conceptos están presentes
- Nivel de complejidad
Step 3: Detect Complexity
Clasifica cada concepto encontrado según la Tabla de Complejidad:
🟢 Nivel Básico (explicación mínima: 1-2 líneas)
| Patrón | Ejemplo |
|---|---|
| Variables y tipos | name: str = "valor" |
| Condicionales | if x > 0: |
| Loops básicos | for item in list: |
| Funciones simples | def foo(x): return x + 1 |
| Imports | from x import y |
| F-strings | f"Hola {nombre}" |
| Diccionarios/Listas | data = {"key": "value"} |
Acción: Mención breve. "Ya conoces esto."
🟡 Nivel Intermedio (explicación media: 5-10 líneas + ejemplo)
| Patrón | Ejemplo |
|---|---|
| Clases | class Product: |
| Decoradores básicos | @router.get("/") |
| List/Dict comprehensions | [x*2 for x in items] |
| Type hints | def foo(x: str) -> int: |
| Context managers | with open(file) as f: |
| Excepciones | try/except/finally |
| Args/Kwargs | def foo(*args, **kwargs): |
| Properties | @property |
Acción: Explicar qué hace, por qué se usa, ejemplo comentado.
🔴 Nivel Avanzado (explicación profunda: 10-20 líneas + múltiples ejemplos)
| Patrón | Ejemplo |
|---|---|
| Async/Await | async def fetch(): |
| Decoradores personalizados | def my_decorator(func): |
| Closures | Función que retorna función |
| Generadores | yield |
| Metaclasses | class Meta(type): |
| Descriptors | __get__, __set__ |
| Generic types | List[T], TypeVar |
| Dependency Injection | Depends() |
| SQLAlchemy/SQLModel | Sesiones, queries, relaciones |
Acción: Explicar en profundidad: qué es, cómo funciona internamente, cuándo usarlo, errores comunes.
Step 4: Generate Lesson
Crea .speclet/lessons/STORY-X.md con la estructura definida en la sección Lesson Template.
Step 5: Confirm
Responde:
✅ Lección generada: .speclet/lessons/STORY-X.md
📚 Conceptos cubiertos:
- [Concepto 1] (🟢 básico)
- [Concepto 2] (🟡 intermedio)
- [Concepto 3] (🔴 avanzado)
⏱️ Ejercicio de práctica: [Descripción breve] (15 min, sin LLM)
Cuando termines el ejercicio, compara tu código con los archivos reales:
- [archivo1.py]
- [archivo2.py]
Lesson Template
Genera .speclet/lessons/STORY-X.md con esta estructura exacta:
# Lección: STORY-X — [Título de la Story]
**Fecha:** YYYY-MM-DD
**Archivos:** [lista de archivos modificados]
**Complejidad detectada:** 🟢/🟡/🔴 [Nivel predominante] ([conceptos principales])
---
## Resumen
[2-3 oraciones: Qué se implementó y por qué importa]
---
## Decisiones Técnicas
### ¿Por qué [decisión 1]?
**Alternativas consideradas:**
1. [Alternativa A] → [Por qué no]
2. [Alternativa B] → [Por qué no]
3. **[Lo que elegimos]** → [Por qué sí] ✅
[Explicación de 3-5 líneas]
### ¿Por qué [decisión 2]?
[Mismo formato...]
---
## Conceptos Explicados
### [Concepto 1] (🟢/🟡/🔴)
[Explicación según nivel de complejidad]
```python
# Ejemplo de código comentado
[Concepto 2] (🟢/🟡/🔴)
[Explicación según nivel...]
Errores Comunes
❌ [Error 1]
# MAL
[código incorrecto]
# BIEN
[código correcto]
Por qué falla: [Explicación breve]
❌ [Error 2]
[Mismo formato...]
Ejercicio de Práctica
Tiempo: 10-15 minutos Regla: SIN LLM. Solo docs oficiales si te trabas.
El Reto
[Descripción clara del ejercicio relacionado con la story]
- [Paso 1]
- [Paso 2]
- [Paso 3]
Archivo a crear: [path/to/exercise_file.py] (no toques el código real)
Hints (solo si te trabas)
Hint 1 (estructura general)
# Esqueleto básico sin la lógica
Hint 2 (concepto clave)
[Pista sobre el concepto principal que necesitas]
Hint 3 (casi la respuesta)
# Código más completo, falta un detalle
Próximo Paso
Cuando termines (o después de 15 min intentando), compara con:
[archivo_real_1.py][archivo_real_2.py]
Pregúntate:
- ¿Qué hice diferente?
- ¿Por qué el código real eligió esa estructura?
- ¿Qué concepto me falta entender mejor?
---
## Language Rules
- **Código:** Siempre en inglés (variables, funciones, comentarios de código)
- **Explicaciones:** En español
- **Prioridad de profundidad:** Python > TypeScript (explicar más Python)
---
## Exercise Generation Rules
El ejercicio debe:
1. **Estar relacionado con la story** — Mismo dominio, conceptos similares
2. **Ser alcanzable en 10-15 min** — No más complejo que la story original
3. **Forzar práctica sin LLM** — El punto es desarrollar fluidez mecánica
4. **Tener 3 hints progresivos:**
- Hint 1: Estructura general (esqueleto)
- Hint 2: Concepto clave (pista conceptual)
- Hint 3: Casi la respuesta (código parcial)
5. **NO incluir solución completa** — El usuario debe comparar con código real
### Ejemplos de Buenos Ejercicios
| Story Implementada | Ejercicio Propuesto |
|--------------------|---------------------|
| Endpoint GET /products | Crea POST /products con validación |
| Servicio de búsqueda | Agrega filtro por categoría |
| Modelo SQLModel | Agrega campo con relación FK |
| Componente React | Crea variante del mismo componente |
---
## What NOT To Do
- ❌ NO modifiques ningún archivo de código de producción
- ❌ NO agregues comentarios de enseñanza al código real
- ❌ NO incluyas soluciones completas a ejercicios
- ❌ NO expliques conceptos básicos en detalle (sé breve)
- ❌ NO generes lecciones para stories que no están completadas
- ❌ NO uses el skill automáticamente — solo cuando el usuario lo invoca
## Global Rules
### Always Show Recommendation + Reason
When asking questions with options, ALWAYS:
1. Mark the recommended option with ⭐
2. Add `**Reason for recommendation:**` explaining why
**Example format:**
[Question]? A. Option A B. Option B ⭐ Recommended — [brief reason] C. Option C
Reason for recommendation: [Detailed explanation of why B is best]