writing-plans

Descripción general

Qué hace la skill writing-plans

La skill writing-plans te ayuda a convertir una especificación de producto o un documento de requisitos técnicos en un plan completo y listo para implementar antes de que nadie toque código. Está diseñada para situaciones en las que tienes una funcionalidad o cambio de varios pasos que quieres desplegar, y necesitas un plan claro y descompuesto que otra persona ingeniera pueda seguir sin contexto previo.

Con writing-plans, generas un plan que:

• Asume que quien implementa es una persona desarrolladora competente pero nueva en tu base de código y dominio.
• Detalla qué archivos crear o modificar en cada parte del trabajo.
• Señala las pruebas, actualizaciones de documentación y verificaciones manuales necesarias.
• Divide el trabajo en tareas pequeñas y publicables con límites claros.

Esto facilita delegar trabajo, revisar el plan y evitar desvíos de alcance o casos límite ocultos. Refleja prácticas como DRY, YAGNI, TDD y commits frecuentes, pero se centra en la planificación de proyectos y la descomposición de tareas, no en la generación de código.

Para quién es writing-plans

Usa la skill writing-plans si eres:

• Tech lead o responsable de ingeniería y necesitas una forma repetible de planificar funcionalidades y refactors.
• Desarrollador/a individual que quiere aclarar su enfoque antes de implementar cambios arriesgados o transversales.
• Equipo que usa subagents o trabajo distribuido y requiere planes escritos claros para coordinar a las personas colaboradoras.

Es especialmente adecuada cuando:

• Tienes una spec o requisitos para una funcionalidad, migración o integración.
• El trabajo afecta a múltiples archivos, componentes o servicios.
• Quieres que otra persona pueda implementar el trabajo sin tener que hacerte preguntas constantemente.

No es la mejor opción cuando:

• Aún estás ideando el problema o la solución (usa primero una skill de ideación/brainstorming).
• La tarea es mínima (p. ej., un fix de una sola línea) y no necesita un plan formal.
• Buscas sobre todo code review o generación de código, no planificación.

Cómo encaja en tu flujo de trabajo

El repositorio espera que writing-plans se use después de una fase de brainstorming y en un worktree dedicado para el proyecto. El flujo habitual es:

1. Hacer brainstorming y aclarar la spec (fuera de esta skill).
2. Crear o abrir un worktree dedicado para la funcionalidad.
3. Ejecutar la skill writing-plans para producir el plan de implementación.
4. Guardar el plan (por defecto) en:
   • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
   • o en la ubicación de planes que definas según tu preferencia.
5. Opcionalmente, lanzar un plan document reviewer subagent usando la plantilla proporcionada para validar el plan antes de implementarlo.

Cómo usarla

Instalación y configuración

1. Instalar la skill writing-plans

Puedes instalar la skill directamente desde el repositorio obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill writing-plans

Esto incorpora la definición de la skill writing-plans y sus prompts de soporte para que puedas usarla en tus propios proyectos.

2. Revisar los archivos principales

Tras la instalación, revisa estos archivos clave para entender y adaptar el flujo de trabajo:

• skills/writing-plans/SKILL.md – Descripción principal del comportamiento esperado de la skill, incluido el alcance, la estructura del plan y las suposiciones sobre la persona ingeniera.
• skills/writing-plans/plan-document-reviewer-prompt.md – Plantilla de prompt reutilizable para un subagent que revisa tu plan finalizado.

Las rutas locales pueden variar según dónde tengas versionado o espejado el repositorio, pero los nombres de archivo son los mismos.

Preparar la ejecución de writing-plans

3. Confirmar tu spec y el alcance

Antes de usar writing-plans, asegúrate de tener:

• Una spec o documento de requisitos claro para la funcionalidad o cambio.
• Suficiente detalle para identificar los componentes principales, integraciones y restricciones.

La skill incluye un paso de Scope Check: si tu spec abarca varios subsistemas independientes, asume que ese trabajo se ha dividido en specs de subproyectos separados durante el brainstorming. Si eso no ha ocurrido, deberías:

• Dividir el trabajo en planes separados, uno por subsistema.
• Garantizar que cada plan pueda producir software funcional y comprobable por sí mismo.

Esto evita que un único plan se vuelva inmanejable y ayuda a alinear el trabajo con unidades desplegables.

4. Preparar un worktree y el archivo del plan

La guía upstream asume que:

• Trabajas en un worktree dedicado para la funcionalidad (configurado durante el brainstorming).

• Guardas el plan de implementación resultante como:

  • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Puedes cambiar esta ubicación si tu equipo prefiere otra estructura de directorios, como docs/plans/ o planning/. Lo importante es que el plan esté bajo control de versiones, versionado junto con el código y sea fácil de localizar después.

Ejecutar la skill y redactar el plan

5. Anunciar e iniciar la sesión de planificación

Cuando invoques la skill o inicies tu conversación de planificación, la recomendación es declarar explícitamente:

"I'm using the writing-plans skill to create the implementation plan."

Esto deja claro que el objetivo es un plan de implementación estructurado, no explorar diseños ni generar código.

6. Mapear primero la estructura de archivos

Antes de listar tareas, writing-plans hace hincapié en la descomposición a nivel de archivos:

• Identificar qué archivos se crearán o modificarán.
• Asignar a cada archivo una responsabilidad única y clara.
• Diseñar unidades con interfaces y límites bien definidos.

En esta fase, el plan debería responder:

• ¿Dónde vivirá la nueva lógica?
• ¿Qué archivos existentes se tocan y por qué?
• ¿Cómo interactúan esos archivos a alto nivel?

Fijar una estructura de archivos sensata desde el principio facilita la descomposición en tareas, las revisiones y futuros refactors.

7. Dividir el trabajo en tareas pequeñas

Una vez que tengas el mapa de archivos, usa writing-plans para convertir la spec en una secuencia de tareas pequeñas y comprensibles de forma independiente. La guía upstream enfatiza:

• Cada tarea debe tener un objetivo claro y ser accionable.
• Las tareas deben ser lo bastante pequeñas como para permitir commits frecuentes.
• El plan debe ser DRY (sin instrucciones redundantes) y evitar trabajo YAGNI (sin tareas especulativas).

Para cada tarea, el plan debería indicar:

• Qué archivos afecta.
• Qué cambios de código o configuración se requieren a alto nivel.
• Qué pruebas hay que añadir o actualizar.
• Qué documentación debe actualizarse.

El objetivo es que una persona ingeniera con contexto mínimo pueda tomar cualquier tarea y completarla con confianza.

8. Planificar pruebas y documentación

writing-plans espera que incorpores pruebas y documentación directamente en el plan:

• Identificar las unit tests, pruebas de integración o end-to-end que deban añadirse o actualizarse.
• Indicar cómo ejecutar las pruebas (p. ej., comandos, puntos de entrada de test) cuando sea relevante.
• Especificar las actualizaciones de documentación necesarias, como secciones de README, guías de usuario o API docs.

Así te aseguras de que la calidad y la mantenibilidad sean parte central del plan, no algo añadido al final.

Revisar e iterar sobre el plan

9. Usar la plantilla de plan document reviewer (opcional pero recomendado)

El archivo plan-document-reviewer-prompt.md proporciona un prompt estructurado para un plan document reviewer subagent. Su finalidad es:

• Comprobar que el plan esté completo y se ajuste a la spec.
• Validar que la descomposición en tareas sea realista y accionable.
• Confirmar que una persona ingeniera pueda implementar el plan sin atascarse.

La plantilla lista categorías que la persona revisora debe comprobar, incluyendo:

• Completez – Que no haya TODOs, marcadores de posición ni pasos faltantes en requisitos importantes.
• Alineación con la spec – Que el plan cubra la spec sin un aumento de alcance significativo.
• Descomposición de tareas – Que las tareas tengan límites claros y sean implementables.
• Construibilidad – Que una persona ingeniera competente pueda seguir el plan de principio a fin.

A la persona revisora se le indica que se centre en problemas que puedan causar problemas reales de implementación, no en matices de redacción o estilo.

Puedes integrar este paso de revisión en tu CI, en tus flujos de code review o como revisión manual.

10. Iterar a partir del feedback

Si la persona revisora (humana o subagent) detecta problemas como requisitos ausentes, pasos contradictorios o tareas demasiado vagas:

• Actualiza el archivo del plan con las correcciones.
• Vuelve a ejecutar o relanzar la revisión si es necesario.
• Una vez aprobado el plan, trátalo como la fuente de verdad para la implementación.

Adaptar writing-plans a tu equipo

11. Personalizar estructura y convenciones

Aunque la skill upstream define comportamientos y valores por defecto claros, puedes adaptarla:

• Cambiando la ubicación del archivo de plan para ajustarla a la estructura de tu repositorio.
• Añadiendo checklists específicas de tu equipo (p. ej., revisión de seguridad, pruebas de rendimiento) como tareas recurrentes.
• Integrando el plan con tu issue tracker mapeando las tareas a tickets.

Como writing-plans trata principalmente de flujo de trabajo estructurado y gestión de proyectos, se traslada bien entre distintos lenguajes, frameworks y dominios.

FAQ

¿Cuándo debería usar la skill writing-plans?

Usa writing-plans siempre que tengas una funcionalidad, refactor o integración de varios pasos y una spec razonablemente clara, y quieras un plan de implementación escrito que otra persona ingeniera pueda ejecutar sin contexto previo. Es especialmente útil antes de cambios complejos que afectan a múltiples archivos o subsistemas.

¿Cuándo no es buena opción writing-plans?

writing-plans no es ideal cuando:

• Todavía estás explorando soluciones y la spec es inestable.
• El trabajo es tan pequeño que un plan formal sería sobrecarga.
• Solo buscas generación de código o code review, en lugar de descomposición de tareas y planificación de proyecto.

En esos casos, usa mejor skills centradas en brainstorming, diseño o codificación.

¿Tengo que usar la ruta por defecto docs/superpowers/plans/?

No. La guía upstream sugiere guardar los planes en:

• docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Pero también indica explícitamente que las preferencias de la persona usuaria sobre la ubicación de los planes tienen prioridad sobre este valor por defecto. Puedes guardar los planes en cualquier directorio o esquema de nombres que encaje con tu repositorio y tus estándares de documentación.

¿Puedo usar writing-plans para proyectos sin código?

La skill está pensada para proyectos de software y bases de código, incluyendo mapeo de archivos y pruebas. Sin embargo, las ideas de fondo —dividir el trabajo en tareas pequeñas, mapear responsabilidades y comprobar la completez— pueden adaptarse a otros flujos de trabajo técnicos. Será más efectiva allí donde exista al menos alguna noción de archivos, pruebas o documentación que actualizar.

¿Cómo ayuda writing-plans con el onboarding y los handoffs?

Como writing-plans asume que quien implementa tiene cero contexto sobre tu base de código y gusto cuestionable, te anima a:

• Explicar dónde debe vivir el código y por qué.
• Hacer explícitas las pruebas y la documentación.
• Eliminar la ambigüedad de las tareas.

Esto facilita mucho delegar trabajo a nuevas personas del equipo, contratistas o subagents. Pueden seguir el plan directamente en lugar de tener que deducir la intención a partir de la spec.

¿Cómo se relaciona writing-plans con las herramientas de gestión de proyectos?

writing-plans complementa, en lugar de sustituir, a las herramientas de gestión de proyectos:

• Te proporciona un plan escrito y estructurado que explica cómo implementar una spec a nivel de código y archivos.
• Después puedes mapear las tareas del plan a herramientas como Jira, GitHub Issues o Linear.

La skill se sitúa en la intersección entre gestión de proyectos, plantillas de flujo de trabajo y redacción técnica, y te da un patrón reutilizable para planes de implementación consistentes.

¿Puedo usar solo el reviewer prompt sin la skill completa?

Sí. El archivo plan-document-reviewer-prompt.md puede usarse de forma independiente como plantilla de revisión para cualquier documento tipo plan. Puedes lanzarlo como prompt de un subagent para:

• Revisar planes escritos con writing-plans.
• Comprobar planes creados mediante otros procesos o herramientas.

Sin embargo, obtendrás resultados más consistentes cuando tanto el plan como la revisión estén alineados con el flujo de trabajo de writing-plans.