request-refactor-plan

Descripción general de la skill request-refactor-plan

Qué hace request-refactor-plan

La skill request-refactor-plan te ayuda a convertir una petición de refactor poco precisa en un plan estructurado con commits pequeños, y luego empaquetar ese plan como un issue de GitHub. Está pensada para request-refactor-plan for Refactoring cuando el objetivo es mejorar el código con seguridad, no rediseñarlo desde cero.

Quién debería usarla

Usa esta request-refactor-plan skill si eres ingeniero, tech lead o un agente que prepara un RFC de refactor, un plan de implementación o un issue que necesita un alcance claro. Es especialmente útil cuando el codebase es real, el cambio no es trivial y quieres menos sorpresas antes de editar.

Qué la diferencia

Esta skill hace más que redactar un prompt genérico. Empuja a hacer una entrevista al usuario, verificar el repo, delimitar el alcance, revisar la cobertura de tests y desglosar el trabajo commit por commit. Eso mejora el resultado para planificar refactors incrementales donde la reversibilidad y la capacidad de revisión importan.

Cómo usar la skill request-refactor-plan

Instálala y actívala

Usa el flujo request-refactor-plan install desde tu gestor de skills, o instálala desde la ruta del repositorio si tu herramienta requiere una fuente directa. La ubicación del repo es mattpocock/skills dentro de skills/deprecated/request-refactor-plan, así que confirma que tu cargador local todavía puede resolver skills obsoletas antes de depender de ella en trabajo de producción.

Dale un brief preparado para refactor

La skill funciona mejor cuando tu entrada inicial incluye: el problema que quieres resolver, el comportamiento actual, las partes del codebase implicadas, las restricciones y cualquier idea que ya hayas considerado. Un buen prompt sería: “Refactoriza el flujo de reintentos de billing para reducir el acoplamiento, mantener sin cambios las respuestas de la API, conservar los tests existentes y evitar cambios en el esquema de la base de datos.”

Sigue el flujo de trabajo que espera la skill

El patrón de uso de request-refactor-plan usage es: describir el problema con detalle, verificar el estado del repo, discutir alternativas, definir un alcance exacto, revisar los tests y luego dividir el trabajo en commits pequeños. Si omites estos insumos, el plan suele quedar demasiado amplio o demasiado cauteloso para ser útil.

Lee primero estos archivos

Empieza con SKILL.md, y luego revisa README.md, AGENTS.md, metadata.json y cualquier carpeta rules/, resources/, references/ o scripts/ si existen en tu entorno. En este repositorio, el principal valor de decisión está concentrado en SKILL.md, así que hay poco material complementario que contrastar.

Preguntas frecuentes sobre la skill request-refactor-plan

¿Sirve para trabajo ordinario de funcionalidades?

No. La request-refactor-plan skill está orientada al refactor y al control del alcance, no al descubrimiento de funcionalidades. Si necesitas una especificación de feature, una propuesta de arquitectura o una hoja de ruta, te convendrá más otra skill de planificación o un prompt normal.

¿Necesito mucho detalle técnico para usarla?

No necesitas un diseño perfecto, pero sí suficiente contexto para entrevistar bien el problema. Si tu brief solo dice “limpia esto”, el resultado probablemente será genérico; si puedes nombrar archivos, comportamientos, riesgos y restricciones, el plan se vuelve mucho más accionable.

¿Cuándo no debería usarla?

No la uses cuando el cambio sea pequeño, obvio o ya esté completamente acotado. También encaja peor cuando no puedes inspeccionar el repo, no puedes confirmar la cobertura de tests o no quieres la sobrecarga de un issue formal y un plan paso a paso.

¿En qué se diferencia de un prompt normal?

Un prompt normal puede darte una lista de verificación de refactor, pero request-refactor-plan añade disciplina de proceso: verificación, revisión de alternativas, fijación del alcance, preguntas sobre testing y commits pequeños. Eso reduce el riesgo de sobrefactorizar o pasar por alto acoplamientos ocultos.

Cómo mejorar la skill request-refactor-plan

Aporta insumos más precisos desde el primer intento

La forma más rápida de mejorar los resultados es decir cuál es el dolor actual, el estado final deseado y los no objetivos explícitos. Por ejemplo: “Reduce la lógica de validación duplicada en src/payments/*, mantén estables las APIs públicas, no renombres funciones exportadas y conserva los mensajes de error actuales.” Eso le da a la guía request-refactor-plan suficiente estructura para evitar suposiciones.

Incluye contexto de tests y riesgos

La skill pregunta por la cobertura por una razón: los tests débiles cambian el plan. Dile qué tests ya protegen esa zona, qué fallos serían inaceptables y si puedes añadir tests antes o después del refactor. Si omites esto, el plan puede volverse demasiado agresivo o demasiado conservador.

Vigila los modos de fallo más comunes

Los fallos más habituales son subacotar, sobracotar y dejar ambiguo el estado final. Si la primera salida te parece demasiado amplia, responde acotando los archivos objetivo, nombrando el comportamiento exacto que debe permanecer igual y pidiendo una secuencia de commits más pequeña. Si parece demasiado tímida, añade el motivo de negocio del refactor y los criterios de aceptación que justifican el cambio.

Itera usando el borrador del issue

Trata el issue de GitHub generado como un borrador de trabajo, no como la palabra final. Mejora los resultados de request-refactor-plan for Refactoring revisando la formulación del problema, eliminando pasos especulativos y ajustando la lista de commits hasta que cada paso pueda revisarse de forma independiente.