Plan Mode — skill de planificación accionable

Modo Plan

Usa este skill 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 markdown del plan.
• No ejecutes comandos de terminal mutantes, no hagas commit, push ni realices acciones externas.
• Puedes inspeccionar el repositorio u otro contexto con comandos/herramientas de solo lectura cuando sea necesario.
• Tu entregable es un plan markdown guardado dentro del espacio de trabajo activo bajo .hermes/plans/.

Requisitos de salida

Escribe un plan markdown que sea concreto y accionable.

Incluye, cuando sea relevante:

• Objetivo
• Contexto actual / suposiciones
• 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 exactas de archivos, objetivos de prueba probables y pasos de verificación.

Ubicación de guardado

Guarda el plan con write_file en:

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

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

Si el runtime proporciona una ruta específica, usa esa ruta exacta. Si no, crea un nombre de archivo con marca temporal sensato por tu cuenta 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, infiere la tarea del contexto de la conversación actual.
• Si está genuinamente subespecificado, haz una breve pregunta aclaratoria en lugar de adivinar.
• Después de guardar el plan, responde brevemente con lo que planificaste y la ruta guardada.

---

Escribir el Plan Correctamente

El resto de este skill 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 completos asumiendo que el implementador tiene cero contexto sobre la base de código y un gusto cuestionable. Documenta todo lo que necesitan: qué archivos tocar, código completo, comandos de prueba, documentación que consultar, cómo verificar. Dales tareas pequeñas. DRY. YAGNI. TDD. Commits frecuentes.

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

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

Cuándo es útil un Plan de Implementación Completo

Úsalo siempre antes de:

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

No lo omitas cuando:

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

Granularidad de Tareas Pequeñas

Cada tarea = 2-5 minutos de trabajo enfocado.

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 pasan" — paso
• "Hacer 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 hash de contraseña a User
[8 líneas, 1 archivo]

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

Estructura del Documento del Plan

Encabezado (Requerido)

Todo plan DEBE comenzar con:

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

> **Para Hermes:** Usa el skill de desarrollo dirigido por subagentes para implementar este plan tarea por tarea.

**Objetivo:** [Una oración describiendo qué construye esto]

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

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

---

Estructura de la Tarea

Cada tarea sigue este formato:

### Tarea N: [Nombre Descriptivo]

**Objetivo:** Lo que esta tarea logra (una oración)

**Archivos:**
- Crear: `ruta/exacta/al/archivo_nuevo.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_especifico():
    resultado = funcion(entrada)
    assert resultado == esperado
```

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

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

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

```python
def funcion(entrada):
    return esperado
```

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

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

**Paso 5: Hacer 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 comprende:

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

Paso 2: Explorar la Base de Código

Usa herramientas de Hermes para entender el proyecto:

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

# Buscar características similares
search_files("patron_similar", path="src/", file_glob="*.py")

# Revisar 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 borde
4. Integración
5. Limpieza/documentación

Paso 5: Agregar Detalles Completos

Para cada tarea, incluye:

• Rutas exactas de archivos (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 prueben 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 archivos son exactas
• Los ejemplos de código son completos (copiables y pegables)
• Los comandos son exactos con salida esperada
• No falta contexto
• Se aplican principios DRY, YAGNI, TDD

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 que se necesita ahora

# Malo — violación YAGNI
class Usuario:
    def __init__(self, nombre, email):
        self.nombre = nombre
        self.email = email
        self.preferencias = {}  # ¡No necesario aún!
        self.metadatos = {}     # ¡No necesario 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 genere 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 el skill test-driven-development 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 User 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 completo de la función

Falta de Verificación

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

Rutas de Archivos Faltantes

Malo: "Crear el archivo de modelo" Bueno: "Crear: src/models/user.py"

Transferencia de Ejecución

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

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

Al ejecutar, usa el skill subagent-driven-development:

• delegate_task nuevo 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
• Proceder solo cuando ambas revisiones aprueben

Recuerda

Tareas pequeñas (2-5 min cada una)
Rutas exactas de archivos
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.