Samin12/skills – Modo de Planificación

Modo de Planificación

Usa esta habilidad cuando el usuario quiera un plan en lugar de ejecución.

Comportamiento principal

En este turno, solo planificas.

• No implementes código.
• No edites archivos del proyecto, excepto el archivo de plan en markdown.
• No ejecutes comandos mutantes en la terminal, ni hagas commit, push o acciones externas.
• Puedes inspeccionar el repositorio u otro contexto con comandos/herramientas de solo lectura cuando sea necesario.
• Tu entregable es un plan en markdown guardado dentro del workspace activo bajo .hermes/plans/.

Requisitos de salida

Escribe un plan en markdown que sea concreto y accionable.

Incluye, cuando sea relevante:

• Objetivo
• Contexto / supuestos actuales
• Enfoque propuesto
• Plan paso a paso
• Archivos que probablemente cambiarán
• Pruebas / validación
• Riesgos, compensaciones y preguntas abiertas

Si la tarea está relacionada con código, incluye rutas de archivo exactas, probables objetivos de prueba y pasos de verificación.

Ubicación de guardado

Guarda el plan con write_file bajo:

• .hermes/plans/AAAA-MM-DD_HHMMSS-<slug>.md

Trata eso como relativo al directorio de trabajo activo / workspace del backend. Las herramientas de archivo de Hermes son conscientes del backend, por lo que usar esta ruta relativa mantiene el plan con el workspace en backends local, docker, ssh, modal y daytona.

Si el tiempo de ejecución proporciona una ruta específica, usa esa ruta exacta. Si no, crea un nombre de archivo con marca de tiempo sensato por ti mismo bajo .hermes/plans/.

Estilo de interacción

• Si la solicitud es suficientemente clara, escribe el plan directamente.
• Si no hay una instrucción explícita que acompañe a /plan, deduce la tarea del contexto actual de la conversación.
• Si está genuinamente subespecificado, haz una pregunta breve aclaratoria en lugar de adivinar.
• Después de guardar el plan, responde brevemente con lo que planeaste y la ruta guardada.

---

Escribir bien el Plan

El resto de esta habilidad es el arte de redactar un buen plan de implementación — el contenido que va dentro del archivo markdown anterior.

Resumen

Escribe planes de implementación exhaustivos asumiendo que el implementador tiene cero contexto sobre el código base y un gusto cuestionable. Documenta todo lo que necesita: qué archivos tocar, código completo, comandos de prueba, documentación a consultar, cómo verificar. Dale tareas pequeñas. DRY. YAGNI. TDD. Commits frecuentes.

Asume que el implementador es un desarrollador hábil pero que sabe casi nada sobre el dominio del problema o el conjunto de herramientas. Asume que no conoce muy bien el diseño de pruebas.

Principio central: Un buen plan hace que la implementación sea obvia. Si alguien tiene que adivinar, el plan está incompleto.

Cuándo ayuda un plan de implementación completo

Úsalo siempre antes de:

• Implementar características de varios pasos
• Descomponer requisitos complejos
• Delegar a subagentes mediante desarrollo impulsado por subagentes

No lo saltes cuando:

• La característica parece simple (las suposiciones causan errores)
• Planeas implementarlo tú mismo (tu yo futuro necesita orientación)
• Trabajas solo (la documentación importa)

Granularidad de tareas pequeñas

Cada tarea = 2-5 minutos de trabajo concentrado.

Cada paso es una acción:

• "Escribir la prueba fallida" — paso
• "Ejecutarla para asegurarse de que falla" — paso
• "Implementar el código mínimo para que la prueba pase" — paso
• "Ejecutar las pruebas y asegurarse de que pasen" — paso
• "Commit" — paso

Demasiado grande:

### Tarea 1: Construir sistema de autenticación
[50 líneas de código en 5 archivos]

Tamaño correcto:

### Tarea 1: Crear modelo User con campo email
[10 líneas, 1 archivo]

### Tarea 2: Agregar campo de hash de contraseña a User
[8 líneas, 1 archivo]

### Tarea 3: Crear utilidad de hashing de contraseñas
[15 líneas, 1 archivo]

Estructura del documento del plan

Encabezado (Obligatorio)

Cada plan DEBE comenzar con:

# [Nombre de la Característica] Plan de Implementación

> **Para Hermes:** Usa la habilidad de desarrollo impulsado por subagentes para implementar este plan tarea por tarea.

**Objetivo:** [Una frase que describa qué se construye]

**Arquitectura:** [2-3 frases sobre el enfoque]

**Stack Tecnológico:** [Tecnologías/bibliotecas clave]

---

Estructura de las tareas

Cada tarea sigue este formato:

### Tarea N: [Nombre Descriptivo]

**Objetivo:** Qué logra esta tarea (una frase)

**Archivos:**
- Crear: `ruta/exacta/al/nuevo_archivo.py`
- Modificar: `ruta/exacta/al/archivo_existente.py:45-67` (números de línea si se conocen)
- Prueba: `tests/ruta/al/archivo_de_prueba.py`

**Paso 1: Escribir prueba fallida**

```python
def test_comportamiento_específico():
    resultado = función(entrada)
    assert resultado == esperado
```

**Paso 2: Ejecutar prueba para verificar fallo**

Ejecutar: `pytest tests/ruta/prueba.py::test_funcion_especifica -v`
Esperado: FAIL — "función no definida"

**Paso 3: Escribir implementación mínima**

```python
def función(entrada):
    return esperado
```

**Paso 4: Ejecutar prueba para verificar pase**

Ejecutar: `pytest tests/ruta/prueba.py::test_funcion_especifica -v`
Esperado: PASS

**Paso 5: Commit**

```bash
git add tests/ruta/prueba.py src/ruta/archivo.py
git commit -m "feat: agregar característica específica"
```

Proceso de escritura

Paso 1: Entender requisitos

Lee y entiende:

• Requisitos de la característica
• Documentos de diseño o descripción del usuario
• Criterios de aceptación
• Restricciones

Paso 2: Explorar el código base

Usa herramientas de Hermes para entender el proyecto:

# Entender estructura del proyecto
search_files("*.py", target="files", path="src/")

# Mirar características similares
search_files("patrón_similar", path="src/", file_glob="*.py")

# Verificar pruebas existentes
search_files("*.py", target="files", path="tests/")

# Leer archivos clave
read_file("src/app.py")

Paso 3: Diseñar enfoque

Decide:

• Patrón de arquitectura
• Organización de archivos
• Dependencias necesarias
• Estrategia de pruebas

Paso 4: Escribir tareas

Crea tareas en orden:

1. Configuración/infraestructura
2. Funcionalidad principal (TDD para cada una)
3. Casos límite
4. Integración
5. Limpieza/documentación

Paso 5: Agregar detalles completos

Para cada tarea, incluye:

• Rutas de archivo exactas (no "el archivo de configuración" sino src/config/settings.py)
• Ejemplos de código completos (no "agregar validación" sino el código real)
• Comandos exactos con salida esperada
• Pasos de verificación que demuestren que la tarea funciona

Paso 6: Revisar el plan

Verifica:

• Las tareas son secuenciales y lógicas
• Cada tarea es pequeña (2-5 min)
• Las rutas de archivo son exactas
• Los ejemplos de código son completos (copiable y pegable)
• Los comandos son exactos con salida esperada
• No falta contexto
• Principios DRY, YAGNI, TDD aplicados

Principios

DRY (No Te Repitas)

Malo: Copiar y pegar validación en 3 lugares Bueno: Extraer función de validación, usar en todas partes

YAGNI (No Lo Vas a Necesitar)

Malo: Agregar "flexibilidad" para requisitos futuros Bueno: Implementar solo lo necesario ahora

# Malo — violación de YAGNI
class Usuario:
    def __init__(self, nombre, email):
        self.nombre = nombre
        self.email = email
        self.preferencias = {}  # ¡No necesitado aún!
        self.metadatos = {}     # ¡No necesitado aún!

# Bueno — YAGNI
class Usuario:
    def __init__(self, nombre, email):
        self.nombre = nombre
        self.email = email

TDD (Desarrollo Guiado por Pruebas)

Cada tarea que produzca código debe incluir el ciclo TDD completo:

1. Escribir prueba fallida
2. Ejecutar para verificar fallo
3. Escribir código mínimo
4. Ejecutar para verificar pase

Consulta la habilidad desarrollo-guiado-por-pruebas para más detalles.

Commits Frecuentes

Haz commit después de cada tarea:

git add [archivos]
git commit -m "tipo: descripción"

Errores Comunes

Tareas Vagas

Malo: "Agregar autenticación" Bueno: "Crear modelo Usuario con campos email y password_hash"

Código Incompleto

Malo: "Paso 1: Agregar función de validación" Bueno: "Paso 1: Agregar función de validación" seguido del código de la función completa

Falta de Verificación

Malo: "Paso 3: Probar que funciona" Bueno: "Paso 3: Ejecutar pytest tests/test_auth.py -v, esperado: 3 aprobados"

Rutas de Archivo Faltantes

Malo: "Crear el archivo del modelo" Bueno: "Crear: src/models/usuario.py"

Transferencia de Ejecución

Después de guardar el plan, ofrece el enfoque de ejecución:

"Plan completo y guardado. Listo para ejecutar usando desarrollo impulsado por subagentes — despacharé un subagente nuevo por tarea con revisión en dos etapas (cumplimiento de especificaciones luego calidad de código). ¿Procedo?"

Al ejecutar, usa la habilidad desarrollo-impulsado-por-subagentes:

• delegate_task fresco por tarea con contexto completo
• Revisión de cumplimiento de especificaciones después de cada tarea
• Revisión de calidad de código después de que pase la especificación
• Procede solo cuando ambas revisiones aprueban

Recuerda

Tareas pequeñas (2-5 min cada una)
Rutas de archivo exactas
Código completo (copiable y pegable)
Comandos exactos con salida esperada
Pasos de verificación
DRY, YAGNI, TDD
Commits frecuentes

Un buen plan hace que la implementación sea obvia.