Communitygithub.com

Especificador de características (Reels Blocker)

Identifica áreas subespecificadas en la especificación de una característica haciendo hasta 5 preguntas de aclaración altamente dirigidas y codificando las respuestas de vuelta en la especificación.

¿Qué es Especificador de características (Reels Blocker)?

Esta habilidad (skill) analiza sistemáticamente un archivo de especificación de características en busca de ambigüedades, lagunas y puntos de decisión faltantes. En lugar de adivinar, hace hasta cinco preguntas de aclaración muy enfocadas al usuario, una por una, en un bucle interactivo. Cada pregunta está diseñada para tener un alto impacto en la arquitectura, el modelo de datos, las pruebas o la preparación operativa. Una vez que el usuario responde, la habilidad codifica automáticamente esa clarificación de nuevo en el archivo de especificación, actualizando secciones como requisitos funcionales, modelo de datos o criterios de éxito. También gestiona ganchos de extensión antes de la clarificación, carga una constitución del proyecto si existe y ejecuta una validación posterior para garantizar la coherencia. Esto reduce drásticamente el retrabajo posterior y las pruebas de aceptación desalineadas, ahorrando tiempo a los desarrolladores y propietarios de producto.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangjuyo/reels-blocker/tree/HEAD/.claude/skills/speckit-clarify

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Entrada del usuario

$ARGUMENTS

DEBES considerar la entrada del usuario antes de continuar (si no está vacía).

Comprobaciones previas a la ejecución

Verificar ganchos de extensión (antes de la clarificación):

  • Comprueba si existe .specify/extensions.yml en la raíz del proyecto.
  • Si existe, léelo y busca entradas bajo la clave hooks.before_clarify.
  • Si el YAML no se puede analizar o no es válido, no lo omitas en silencio: informa al usuario de que .specify/extensions.yml no se pudo leer (incluye el error del analizador) y que no se comprobaron ganchos, incluidos los obligatorios (optional: false) registrados allí, luego continúa normalmente.
  • Filtra los ganchos donde enabled sea explícitamente false. Trata los ganchos sin un campo enabled como habilitados por defecto.
  • Para cada gancho restante, no intentes interpretar o evaluar las expresiones de condition del gancho:
    • Si el gancho no tiene un campo condition, o es nulo/vacío, trata el gancho como ejecutable.
    • Si el gancho define una condition no vacía, omítelo y deja la evaluación de la condición a la implementación de HookExecutor.
  • Al construir invocaciones de comandos a partir de nombres de comando de gancho, reemplaza los puntos (.) con guiones (-). Por ejemplo, speckit.git.commit → /speckit-git-commit.
  • Para cada gancho ejecutable, muestra lo siguiente según su indicador optional:
    • Gancho opcional (optional: true):
      ## Extension Hooks
      
      **Optional Pre-Hook**: {extension}
      Command: `/{command}`
      Description: {description}
      
      Prompt: {prompt}
      To execute: `/{command}`
      
    • Gancho obligatorio (optional: false):
      ## Extension Hooks
      
      **Automatic Pre-Hook**: {extension}
      Executing: `/{command}`
      EXECUTE_COMMAND: {command}
      
      Wait for the result of the hook command before proceeding to the Outline.
      
      Después de emitir el bloque anterior, DEBES invocar el gancho y esperar a que termine antes de continuar. Ejecútalo de la misma manera que ejecutarías el comando tú mismo en este agente/sesión (la invocación puede diferir del id {command} literal mostrado arriba, por ejemplo, un agente en modo skills lo ejecuta como /skill:speckit-... o $speckit-...). Emitir el bloque solo no ejecuta el gancho.
  • Si no hay ganchos registrados o no existe .specify/extensions.yml, omítelo en silencio.

Esquema

Objetivo: Detectar y reducir la ambigüedad o los puntos de decisión faltantes en la especificación activa de la característica y registrar las aclaraciones directamente en el archivo de especificación.

Nota: Se espera que este flujo de trabajo de aclaración se ejecute (y se complete) ANTES de invocar /speckit-plan. Si el usuario indica explícitamente que está omitiendo la aclaración (por ejemplo, un spike exploratorio), puedes continuar, pero debes advertir que aumenta el riesgo de retrabajo posterior.

Pasos de ejecución:

  1. Ejecuta .specify/scripts/bash/check-prerequisites.sh --json --paths-only desde la raíz del repositorio una vez (modo combinado --json --paths-only / -Json -PathsOnly). Analiza los campos mínimos de la carga útil JSON:

    • FEATURE_DIR
    • FEATURE_SPEC
    • (Opcionalmente, captura IMPL_PLAN, TASKS para flujos encadenados futuros).
    • Si el análisis JSON falla, aborta e indica al usuario que vuelva a ejecutar /speckit-specify o que verifique el entorno de la rama de la característica.
    • Para comillas simples en argumentos como "I'm Groot", usa la sintaxis de escape: ej. 'I'''m Groot' (o entre comillas dobles si es posible: "I'm Groot").
  2. SI EXISTE: Carga .specify/memory/constitution.md para conocer los principios del proyecto y las restricciones de gobierno.

  3. Carga el archivo de especificación actual. Realiza un escaneo estructurado de ambigüedad y cobertura utilizando esta taxonomía. Para cada categoría, marca el estado: Claro / Parcial / Ausente. Produce un mapa de cobertura interno utilizado para la priorización (no muestres el mapa sin procesar a menos que no se hagan preguntas).

    Alcance funcional y comportamiento:

    • Objetivos principales del usuario y criterios de éxito
    • Declaraciones explícitas fuera del alcance
    • Roles de usuario / diferenciación de personas

    Modelo de dominio y datos:

    • Entidades, atributos, relaciones
    • Reglas de identidad y unicidad
    • Transiciones de ciclo de vida/estado
    • Suposiciones de volumen de datos/escala

    Interacción y flujo de UX:

    • Recorridos/secuencias de usuario críticos
    • Estados de error/vacío/carga
    • Notas de accesibilidad o localización

    Atributos de calidad no funcionales:

    • Rendimiento (objetivos de latencia, rendimiento)
    • Escalabilidad (horizontal/vertical, límites)
    • Fiabilidad y disponibilidad (tiempo de actividad, expectativas de recuperación)
    • Observabilidad (señales de registro, métricas, trazado)
    • Seguridad y privacidad (autenticación/autorización, protección de datos, suposiciones de amenazas)
    • Restricciones de cumplimiento/regulatorias (si las hay)

    Integración y dependencias externas:

    • Servicios/API externos y modos de fallo
    • Formatos de importación/exportación de datos
    • Suposiciones de protocolo/versionado

    Casos extremos y manejo de fallos:

    • Escenarios negativos
    • Límite de velocidad / estrangulamiento
    • Resolución de conflictos (ej., ediciones concurrentes)

    Restricciones y compensaciones:

    • Restricciones técnicas (lenguaje, almacenamiento, alojamiento)
    • Compensaciones explícitas o alternativas rechazadas

    Terminología y coherencia:

    • Términos del glosario canónico
    • Sinónimos evitados / términos obsoletos

    Señales de finalización:

    • Capacidad de prueba de los criterios de aceptación
    • Indicadores medibles de estilo Definición de Hecho

    Varios / Marcadores de posición:

    • Marcadores TODO / decisiones no resueltas
    • Adjetivos ambiguos ("robusto", "intuitivo") que carecen de cuantificación

    Para cada categoría con estado Parcial o Ausente, agrega una oportunidad de pregunta candidata a menos que:

    • La aclaración no cambie materialmente la estrategia de implementación o validación.
    • El elemento se trate específicamente sobre el método de implementación, la comparación de pilas tecnológicas o el desglose de tareas (anótalo internamente).
  4. Genera (internamente) una cola priorizada de preguntas de aclaración candidatas (máximo 5). NO las muestres todas a la vez. Aplica estas restricciones:

    • Máximo de 5 preguntas en total en toda la sesión.
    • Cada pregunta debe poder responderse con:
      • Una selección breve de opción múltiple (2–5 opciones distintas y mutuamente excluyentes), O
      • Una respuesta de una palabra / frase corta (restringe explícitamente: "Responde en <=5 palabras").
    • Solo incluye preguntas cuyas respuestas impacten materialmente en la arquitectura, el modelado de datos, el desglose de tareas, el diseño de pruebas, el comportamiento de UX, la preparación operativa o la validación de cumplimiento.
    • Asegura un equilibrio de cobertura de categorías: intenta cubrir primero las categorías no resueltas de mayor impacto; evita hacer dos preguntas de bajo impacto cuando una sola área de alto impacto (ej., postura de seguridad) no está resuelta.
    • Excluye preguntas ya respondidas, preferencias estilísticas triviales o detalles de ejecución a nivel de plan (a menos que bloqueen la corrección).
    • Favorece las aclaraciones que reduzcan el riesgo de retrabajo posterior o eviten pruebas de aceptación desalineadas.
    • Si más de 5 categorías permanecen sin resolver, selecciona las 5 principales según la heurística (Impacto * Incertidumbre).
  5. Bucle de preguntas secuencial (interactivo):

    • Presenta EXACTAMENTE UNA pregunta a la vez.

    • Calidad de redacción de la pregunta (se aplica a cada pregunta, de opción múltiple o respuesta corta):

      • Comienza con **Pregunta:** seguido de una interrogativa completa que termine con ?. El texto de la pregunta antes del ? debe tener sentido por sí mismo.
      • NUNCA uses una etiqueta de tema, un encabezado de sección o un id de requisito como la pregunta en sí. Por ejemplo, Matriz de dispositivo/tiempo de ejecución de aceptación (FR-023) es INVÁLIDO: es una etiqueta, no una pregunta.
      • Después del ?, el único sufijo permitido es un id de requisito/pregunta opcional entre paréntesis. Formato exacto: **Pregunta:** <interrogativa>? o **Pregunta:** <interrogativa>? (FR-023). Nunca pongas el id antes del ?, y nunca uses el id (solo o con una etiqueta de tema) como todo el aviso.
      • Inmediatamente después de la línea de la pregunta, agrega una oración en lenguaje sencillo de "Por qué es importante" (la apuesta por la aceptación o el lanzamiento) antes de la recomendación/opciones.
      • Usa redacción cotidiana; introduce jerga solo si se define en la misma oración. Autocomprobación: un lector que no conozca Spec Kit debe poder responder solo con la línea de la pregunta. La brevedad está bien; las etiquetas crípticas no.
    • Para preguntas de opción múltiple:

      • Analiza todas las opciones y determina la opción más adecuada en función de:
        • Mejores prácticas para el tipo de proyecto
        • Patrones comunes en implementaciones similares
        • Reducción de riesgos (seguridad, rendimiento, mantenibilidad)
        • Alineación con los objetivos o restricciones explícitos del proyecto visibles en la especificación
      • Presenta tu opción recomendada de manera prominente en la parte superior con un razonamiento claro (1-2 oraciones que expliquen por qué esta es la mejor opción).
      • Formatéalo como: **Recomendada:** Opción [X] - <razonamiento>
      • Luego renderiza todas las opciones como una tabla de Markdown:
      OpciónDescripción
      A<Descripción de la opción A>
      B<Descripción de la opción B>
      C<Descripción de la opción C> (agrega D/E según sea necesario hasta 5)
      CortaProporciona una respuesta corta diferente (<=5 palabras) (Incluir solo si la alternativa de formato libre es apropiada)
      • Después de la tabla, agrega: Puedes responder con la letra de la opción (ej., "A"), aceptar la recomendación diciendo "sí" o "recomendada", o proporcionar tu propia respuesta corta.
    • Para el estilo de respuesta corta (sin opciones discretas significativas):

      • Proporciona tu respuesta sugerida según las mejores prácticas y el contexto.
      • Formatéalo como: **Sugerida:** <tu respuesta propuesta> - <razonamiento breve>
      • Luego muestra: Formato: Respuesta corta (<=5 palabras). Puedes aceptar la sugerencia diciendo "sí" o "sugerida", o proporcionar tu propia respuesta.
    • Después de que el usuario responda:

      • Si el usuario responde con "sí", "recomendada" o "sugerida", usa tu recomendación/sugerencia previamente indicada como respuesta.
      • De lo contrario, valida que la respuesta se asigne a una opción o cumpla con la restricción de <=5 palabras.
      • Si es ambiguo, pide una desambiguación rápida (el conteo aún pertenece a la misma pregunta; no avances).
      • Una vez satisfactoria, regístrala en la memoria de trabajo (aún no la escribas en el disco) y pasa a la siguiente pregunta en cola.
    • Deja de hacer más preguntas cuando:

      • Todas las ambigüedades críticas se resuelvan temprano (los elementos restantes en cola se vuelven innecesarios), O
      • El usuario indique finalización ("hecho", "bien", "no más"), O
      • Llegues a 5 preguntas formuladas.
    • Nunca reveles las preguntas futuras en cola con anticipación.

    • Si no existen preguntas válidas al inicio, informa inmediatamente que no hay ambigüedades críticas.

  6. Integración después de CADA respuesta aceptada (enfoque de actualización incremental):

    • Mantén una representación en memoria de la especificación (cargada una vez al inicio) más el contenido del archivo sin procesar.
    • Para la primera respuesta integrada en esta sesión:
      • Asegúrate de que exista una sección ## Aclaraciones (crea justo después de la sección contextual/de descripción general de más alto nivel según la plantilla de especificación si falta).
      • Debajo de ella, crea (si no está presente) un subtítulo ### Sesión YYYY-MM-DD para hoy.
    • Agrega una línea de viñeta inmediatamente después de la aceptación: - P: <pregunta> → R: <respuesta final>.
    • Luego aplica inmediatamente la aclaración a la(s) sección(es) más apropiada(s):
      • Ambigüedad funcional → Actualiza o agrega una viñeta en Requisitos funcionales.
      • Interacción del usuario / distinción de actor → Actualiza las subsecciones de Historias de usuario o Actores (si están presentes) con el rol, la restricción o el escenario aclarados.
      • Forma de datos / entidades → Actualiza el Modelo de datos (agrega campos, tipos, relaciones) conservando el orden; anota las restricciones agregadas de manera concisa.
      • Restricción no funcional → Agrega/modifica criterios medibles en Criterios de éxito > Resultados medibles (convierte el adjetivo vago en métrica o objetivo explícito).
      • Caso extremo / flujo negativo → Agrega una nueva viñeta bajo Casos extremos / Manejo de errores (o crea dicha subsección si la plantilla proporciona un marcador de posición para ella).
      • Conflicto de terminología → Normaliza el término en toda la especificación; conserva el original solo si es necesario agregando (anteriormente conocido como "X") una vez.
    • Si la aclaración invalida una declaración ambigua anterior, reemplaza esa declaración en lugar de duplicarla; no dejes texto obsoleto contradictorio.
    • Guarda el archivo de especificación DESPUÉS de cada integración para minimizar el riesgo de pérdida de contexto (sobrescritura atómica).
    • Conserva el formato: no reordenes secciones no relacionadas; mantén la jerarquía de encabezados intacta.
    • Mantén cada aclaración insertada mínima y comprobable (evita la deriva narrativa).
  7. Validación (realizada después de CADA escritura más una pasada final):

    • La sesión de aclaraciones contiene exactamente una viñeta por respuesta aceptada (sin duplicados).
    • Total de preguntas formuladas (aceptadas) ≤ 5.
    • Las secciones actualizadas no contienen marcadores de posición vagos persistentes que la nueva respuesta debía resolver.
    • No queda ninguna declaración contradictoria anterior (revisa si hay opciones alternativas ahora inválidas eliminadas).
    • Estructura de Markdown válida; solo se permiten nuevos encabezados: ## Aclaraciones, ### Sesión YYYY-MM-DD.
    • Coherencia terminológica: se usa el mismo término canónico en todas las secciones actualizadas.
  8. Escribe la especificación actualizada de nuevo en FEATURE_SPEC.

  9. Revalidar la lista de verificación de calidad de la especificación (si existe):

    • Comprueba si existe FEATURE_DIR/checklists/requirements.md.
    • Si NO existe, omite este paso en silencio.
    • Si existe:
      1. Lee el archivo de la lista de verificación.
      2. Identifica todas las líneas de casillas de verificación de lista de tareas de GitHub: líneas que coinciden con - [ ], - [x] o - [X] (sin distinción entre mayúsculas y minúsculas, tolerante con espacios en blanco iniciales para elementos anidados) fuera de los bloques de código. Ignora todo el otro contenido (encabezados, notas, viñetas que no sean casillas de verificación, metadatos).
      3. Para cada línea de casilla de verificación, registra su estado de marcador actual (marcada o desmarcada) y el texto del elemento en una lista de instantánea anterior.
      4. Reevalúa cada elemento de la casilla de verificación contra la especificación actualizada (la versión recién guardada en el paso 7).
      5. Para cada elemento de la casilla de verificación, actualiza solo si el estado marcado/desmarcado cambia realmente:
        • Si el elemento ahora pasa y estaba desmarcado: cambia [ ] a [x].
        • Si el elemento ahora falla y estaba marcado: cambia [x]/[X] a [ ].
        • Si el estado no cambia:

…

[truncado para la traducción]

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

Skills relacionados