Planes de redacción

Resumen

Redacta planes de implementación exhaustivos partiendo de la base de que el ingeniero no tiene ningún conocimiento previo sobre nuestro código y que su gusto es cuestionable. Documenta todo lo que necesite saber: qué archivos debe modificar para cada tarea, el código, las pruebas y la documentación que podría necesitar consultar, y cómo realizar las pruebas. Preséntale el plan completo en forma de tareas breves y manejables. DRY. YAGNI. TDD. Commit frecuentes.

Asume que es un desarrollador cualificado, pero que no sabe prácticamente nada sobre nuestro conjunto de herramientas ni sobre el ámbito del problema. Asume que no domina bien el diseño de buenas pruebas.

Anuncia al principio: «Estoy utilizando la habilidad « writing-plans » para crear el plan de implementación».

Contexto: si se trabaja en un árbol de trabajo aislado, este debería haberse creado mediante la habilidad «superpowers:using-git-worktrees» en el momento de la ejecución.

Guarda los planes en: docs/superpowers/plans/AAAA-MM-DD-.md

• (Las preferencias del usuario sobre la ubicación del plan prevalecen sobre este valor predeterminado)

Comprobación del alcance

Si la especificación abarca varios subsistemas independientes, debería haberse dividido en especificaciones de subproyectos durante la sesión de lluvia de ideas. Si no fue así, sugiere dividirla en planes separados: uno por subsistema. Cada plan debe producir, por sí solo, un software funcional y susceptible de ser probado.

Estructura de archivos

Antes de definir las tareas, planifica qué archivos se crearán o modificarán y cuál es la función de cada uno. Aquí es donde se concretan las decisiones de descomposición.

• Diseña unidades con límites claros e interfaces bien definidas. Cada archivo debe tener una responsabilidad clara.
• Se razona mejor sobre el código que se puede tener en contexto de una sola vez, y las modificaciones son más fiables cuando los archivos están centrados en un tema concreto. Es preferible optar por archivos más pequeños y específicos en lugar de archivos grandes que abarquen demasiado.
• Los archivos que cambian juntos deben estar juntos. Divídelos por responsabilidad, no por capa técnica.
• En bases de código existentes, sigue los patrones establecidos. Si la base de código utiliza archivos grandes, no la reestructures de forma unilateral; pero si un archivo que estás modificando se ha vuelto difícil de manejar, es razonable incluir una división en el plan.

Esta estructura determina la descomposición de las tareas. Cada tarea debe producir cambios autónomos que tengan sentido por sí mismos.

Dimensionamiento adecuado de las tareas

Una tarea es la unidad más pequeña que cuenta con su propio ciclo de pruebas y merece una revisión por parte de un revisor independiente. Al definir los límites de las tareas: integra los pasos de preparación, configuración, andamiaje y documentación en la tarea cuyo resultado final los requiera; divide únicamente cuando un revisor pueda rechazar de forma justificada una tarea mientras aprueba la contigua. Cada tarea termina con un resultado final que se puede probar de forma independiente.

Granularidad de las tareas en «porciones pequeñas»

Cada paso es una acción (2-5 minutos):

• «Escribir la prueba que falla» —paso
• «Ejecutarla para asegurarte 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
• «Confirmar» —paso

Encabezado del documento del plan

Todo plan DEBE comenzar con este encabezado:

# [Nombre de la función] Plan de implementación

> **Para trabajadores agenticos:** SUBCOMPETENCIA OBLIGATORIA: Utiliza superpowers:subagent-driven-development (recomendado) o superpowers:executing-plans para implementar este plan tarea por tarea. Los pasos utilizan la sintaxis de casilla de verificación (`- [ ]`) para su seguimiento.

**Objetivo:** [Una frase que describa qué se crea con esto]

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

**Pila tecnológica:** [Tecnologías/bibliotecas clave]

## Restricciones globales

[Los requisitos de la especificación para todo el proyecto —versiones mínimas, límites de dependencias,
normas de nomenclatura y texto, requisitos de plataforma— en una línea cada uno, con los valores exactos
copiados textualmente de la especificación. Los requisitos de cada tarea incluyen implícitamente
esta sección.]

---

Estructura de la tarea

### Tarea N: [Nombre del componente]

**Archivos:**
- Crear: `ruta/exacta/al/archivo.py`
- Modificar: `ruta/exacta/a/existing.py:123-145`
- Probar: `tests/ruta/exacta/a/test.py`

**Interfaces:**
- Consume: [lo que esta tarea utiliza de tareas anteriores — firmas exactas]
- Produce: [en qué se basan las tareas posteriores — nombres exactos de funciones, tipos de parámetros
  y de retorno. El implementador de una tarea solo ve su propia tarea; este
  bloque le permite conocer los nombres y tipos que utilizan las tareas adyacentes.]

- [ ] **Paso 1: Escribe la prueba que falla**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Paso 2: Ejecuta la prueba para comprobar que falla**

Ejecuta: `pytest tests/path/test.py::test_name -v`
Resultado esperado: FALLO con el mensaje «función no definida»

- [ ] **Paso 3: Escribe una implementación mínima**

```python
def function(input):
    return expected
```

- [ ] **Paso 4: Ejecuta la prueba para comprobar que pasa**

Ejecuta: `pytest tests/path/test.py::test_name -v`
Resultado esperado: PASA

- [ ] **Paso 5: Realizar el commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: añadir característica específica"
```

Sin marcadores de posición

Cada paso debe contener el contenido real que necesita un ingeniero. Estos son errores de planificación; nunca los escribas:

• «Por determinar», «Pendiente», «implementar más adelante», «rellenar detalles»
• «Añadir el manejo de errores adecuado» / «añadir validación» / «gestionar casos extremos»
• «Escribir pruebas para lo anterior» (sin código de prueba real)
• «Similar a la tarea N» (repetir el código; el ingeniero podría estar leyendo las tareas sin seguir el orden)
• Pasos que describen qué hacer sin mostrar cómo (se requieren bloques de código para los pasos de programación)
• Referencias a tipos, funciones o métodos no definidos en ninguna tarea

Recuerda

• Indica siempre las rutas exactas de los archivos
• Código completo en cada paso: si un paso modifica el código, muestra el código
• Comandos exactos con el resultado esperado
• DRY, YAGNI, TDD, confirmaciones frecuentes

Autorevisión

Tras redactar el plan completo, revisa las especificaciones con una mirada fresca y compara el plan con ellas. Se trata de una lista de comprobación que debes realizar tú mismo, no una tarea delegada a un subagente.

1. Cobertura de las especificaciones: ojea cada sección o requisito de las especificaciones. ¿Puedes señalar una tarea que lo implemente? Enumera las lagunas.

2. Revisión de marcadores de posición: busca en tu plan señales de alerta —cualquiera de los patrones de la sección «Sin marcadores de posición» anterior—. Corrígelos.

3. Coherencia de tipos: ¿Coinciden los tipos, las firmas de los métodos y los nombres de las propiedades que has utilizado en tareas posteriores con lo que definiste en tareas anteriores? Una función llamada clearLayers() en la Tarea 3, pero clearFullLayers() en la Tarea 7, es un error.

Si encuentras problemas, corrígelos directamente en el código. No hace falta volver a revisarlo: simplemente corrígelo y sigue adelante. Si encuentras un requisito de las especificaciones para el que no hay ninguna tarea, añade la tarea.

Traspaso de la ejecución

Tras guardar el plan, ofrece la opción de ejecución:

«Plan completado y guardado en docs/superpowers/plans/.md. Dos opciones de ejecución:

1. Dirigida por subagentes (recomendada): envío un subagente nuevo por cada tarea, reviso entre tareas, iteración rápida

2. Ejecución en línea: ejecuta las tareas en esta sesión utilizando executing-plans, ejecución por lotes con puntos de control

¿Qué enfoque eliges?»

Si se elige «Impulsado por subagentes»:

• HABILIDAD SECUNDARIA REQUERIDA: Utilizar «superpowers:subagent-driven-development»
• Un subagente nuevo por tarea + revisión en dos fases

Si se elige «Ejecución en línea»:

• SUBHABILIDAD REQUERIDA: Usar superpoderes:ejecución-de-planes
• Ejecución por lotes con puntos de control para la revisión