RaamPrashathT/spec-it

¿Qué hace spec-it?

Convierte $ARGUMENTS en una especificación a partir de la cual un agente de codificación pueda construir sin preguntas de seguimiento, más maquetas que muestren cada requisito y caso extremo.

Idea → 1. Contexto (sin preguntas) → 2. Preguntas de producto → 3. Preguntas técnicas
     → 4. REQUIREMENTS.md → 5. Maquetas → 6. Verificación

Las rutas como references/… son relativas a ${CLAUDE_SKILL_DIR}. La salida va a spec-it/<nombre-en-kebab>/:

spec-it/<nombre>/
├── REQUIREMENTS.md      el entregable único: intención, decisiones, fases, RFs, CEs, asunciones
└── mockups/             index.html + pantallas, o api.html + openapi.yaml, o cli.html + transcripts.md
    └── assets/          theme.css, fixtures.js, app.js

Reglas

1. Los hechos son tuyos, las decisiones son de ellos. Nunca preguntes lo que el repo, los archivos adjuntos, la web o un estándar pueden responder. Nunca decidas alcance, prioridades o concesiones por el desarrollador.
2. Toda pregunta debe ganarse su lugar. Ejecuta la puerta de preguntas en references/questions.md antes de cada una. Un detalle con un default estándar defendible es una asunción (A-n), no una pregunta.
3. Sin cuota. No hay mínimo. Las ejecuciones típicas hacen 5–12 preguntas. Detente cuando puedas predecir las próximas respuestas del desarrollador.
4. Pregunta a través del selector (AskUserQuestion; texto numerado simple sin él). Hasta 3 preguntas independientes por llamada; nunca agrupes una pregunta cuyas opciones dependen de otra no respondida.
5. Cada pregunta se muestra una vez, como lo último en tu mensaje. Sin resumen posterior.
6. Escribe el estado en disco. Después del paso de contexto, mantén REQUIREMENTS.md como archivo de trabajo: redacta §1–2 temprano, rellena las decisiones a medida que se toman. Después de una compactación de contexto, vuelve a leerlo antes de actuar.
7. Las maquetas funcionan offline. Sin CDN, red ni fuentes web.
8. El script de verificación controla la finalización: node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<nombre> sale con 0.

IDs: FR-n requisito, CE-n caso extremo, D-n decisión, A-n asunción. Con módulos, FR/CE/A toman un prefijo de módulo (LIBRO-FR-3). Los IDs son permanentes: nunca renumerar; retirar con "(eliminado)".

1. Contexto (aún sin preguntas)

Haz esto antes de preguntar nada. Ejecuta ambas búsquedas en paralelo, con subagentes de contexto fresco cuando estén disponibles:

• Escaneo del código base (saltar si la carpeta está vacía): stack, funcionalidades existentes que se superponen con la idea, modelos de datos, autenticación, kit de UI y tokens de diseño, convenciones de API y CLI, cualquier cosa a medio construir. Máximo 25 líneas de vuelta.
• Escaneo de arte previo (búsqueda web, 2–4 búsquedas): cómo 2–3 productos o estándares establecidos resuelven esto; los problemas conocidos del dominio (las cosas que salen mal en uso real); el conjunto de funcionalidades estándar; cualquier especificación relevante (RFC, clig.dev, WCAG, reglas de pago o privacidad). Máximo 25 líneas de vuelta, con enlaces a las fuentes.

Luego muestra al desarrollador un resumen de contexto, de máximo 15 líneas:

Lo que encontré
- Repo: <lo que existe que esto toca o reutiliza>
- Cómo lo hacen otros: <el producto A hace X, el producto B hace Y>
- Problemas difíciles en este dominio: <2–4, ej. las ausencias dejan habitaciones vacías; reservas recurrentes>
- Mi lectura: <hipótesis de una frase de lo que quieres y por qué> · confianza <n>%

Clasifica el tipo (UI, API, CLI, mixto) y crea REQUIREMENTS.md desde assets/requirements-template.md con §1 y la sección de Contexto rellenada. Los problemas difíciles que encontraste son la materia prima para tus mejores preguntas.

2. Preguntas de producto

Lee references/questions.md. Trabaja desde el desconocido más riesgoso hacia abajo: ¿es este el problema correcto?, ¿para quién?, ¿qué se envía primero?, ¿qué queda fuera?, luego los problemas difíciles del dominio como escenarios concretos. Registra cada respuesta como D-n en §Decisiones a medida que se recibe.

Cambia a preguntas técnicas cuando se cumplan las tres:

• puedes escribir el replanteo (resultado, usuario, por qué ahora, éxito, fuera de alcance) en las propias palabras del desarrollador;
• el alcance de la Fase 1 y los no-objetivos están acordados;
• lo que queda es sobre cómo, no qué, quién o por qué.

Excepción: una restricción dura que cambie el alcance ("debe funcionar offline", "reutilizar nuestro inquilino de Auth0", "los datos se quedan en la UE") se pregunta tan pronto como surge, porque remodela las preguntas de producto.

3. Preguntas técnicas

Solo en puntos de bifurcación: lugares donde el repo y los estándares no lo resuelven, y la respuesta cambia el modelo de datos, un contrato o el comportamiento visible para el usuario. La lista está en references/questions.md § Técnicas. Muchas ejecuciones necesitan 0–4. Nunca preguntes sobre hosting, CI, framework o elecciones de proveedor que el repo ya fija.

Puerta de confirmación. Un mensaje: el replanteo (6 líneas), luego cada asunción que tomaste (A-n, una línea cada una, con su default). Pregunta: confirmar, o nombrar las que cambiar. Incorpora los cambios. Escribe Estado: Confirmado en la línea de estado de la especificación solo después de un sí explícito.

Fases y módulos

Fases (siempre consideradas). La pregunta de producto "qué se envía primero" las decide. La Fase 1 es la porción más delgada donde un usuario completa el trabajo central de principio a fin (esqueleto funcional). Si el desarrollador lo quiere todo de una vez, hay una sola fase. Cada FR lleva Fase: n. La Fase 1 se especifica por completo; las fases posteriores son un bullet por capacidad en §Plan de entrega hasta que --next-phase las detalle.

Módulos (solo con señales). Trata un área como módulo solo cuando cumple dos o más de: diferentes personas o vocabulario; posee sus propios datos; útil si se envía solo; necesitaría sus propias 10+ preguntas. Con 2+ áreas que califican, pregunta una vez: una especificación con secciones de módulo (recomendado), o especifica el módulo más importante ahora y bosqueja el resto. Nunca infieras módulos por lo grande que suena la idea. Los módulos permanecen en el mismo REQUIREMENTS.md como secciones ## dentro de §Requisitos funcionales, con prefijos de ID.

Límite de tamaño. Si la Fase 1 supera aproximadamente 25 FRs Obligatorios o 12 artefactos de maqueta, pregunta cuáles mover a la Fase 2.

4. Escribir REQUIREMENTS.md

Rellena la plantilla. Cada FR tiene un ID, prioridad, fase, Dado/Cuando/Entonces, y Fuente: IDs de decisiones; cada caso extremo planteado se convierte en un CE-n con valores de fixture concretos. Los FRs dicen lo que el usuario observa; la tecnología va en §Decisiones técnicas. Luego haz una autoevaluación una vez contra esta lista y corrige lo que falle:

• Dos afirmaciones que no puedan sostenerse juntas; una regla establecida dos veces.
• Un FR que un desarrollador podría construir de dos maneras diferentes (falta límite, unidad, rol o comportamiento de fallo).
• Un criterio que no pueda pasar o fallar por observación, o una palabra vaga sin número.
• Un rol, entidad o flujo sin FR; una decisión citada por nada.
• Una palabra usada contra el glosario.

5. Maquetas

Enumera los artefactos (pantallas, grupos de endpoints o grupos de comandos), máximo 12, cada uno con sus estados y cada CE mapeado a un estado. Muestra la lista en un mensaje y continúa a menos que el desarrollador objete. Luego lee references/screens.md (UI) o references/api-cli.md (API, CLI) y construye:

1. Escribe mockups/assets/fixtures.js primero: cada nombre, ID, cantidad y fecha que muestre cualquier artefacto.
2. UI: escribe la dirección de diseño en §Dirección de diseño. Si el repo tiene un sistema de diseño o tokens, síguelo y salta la pregunta de diseño; de lo contrario haz una pregunta de dirección de diseño con bocetos ASCII en las vistas previas de las opciones.
3. Copia ${CLAUDE_SKILL_DIR}/assets/theme.css y app.js en mockups/assets/, establece los tokens y ejecuta la verificación hasta que el contraste pase.
4. Construye cada artefacto desde references/renderer.md: con 4+ artefactos y una herramienta de subagente, un subagente por artefacto en paralelo; de lo contrario uno a la vez aquí. CLI: escribe mockups/transcripts.md, luego node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<nombre>.
5. Rellena mockups/index.html desde ${CLAUDE_SKILL_DIR}/assets/index.html.
6. UI con una herramienta de navegador: opcionalmente ejecuta references/critic.md y aplica sus mejores correcciones una vez.

6. Verificar e informar

Ejecuta el script de verificación hasta que salga con 0; trata las advertencias de ambigüedad como redacción a mejorar. Informa en máximo 10 líneas: la ruta, conteos (preguntas hechas, FRs, CEs, asunciones, artefactos), la línea de resumen de la verificación, cómo ver las maquetas (abrir mockups/index.html, o node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<nombre>), y la siguiente fase si la hay. node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<nombre> escribe copias de un solo archivo para compartir, bajo petición.

Ejecuciones posteriores

• --next-phase: lee la especificación, toma los bullets de la siguiente fase, ejecuta los pasos 2–6 solo para ellos (las preguntas comienzan desde lo que la Fase 1 dejó abierto). Los nuevos FRs continúan la numeración; los IDs anteriores nunca cambian.
• --revise (o una solicitud de cambio): registra la nueva decisión, actualiza los FRs y CEs afectados, vuelve a renderizar solo los artefactos afectados, ejecuta la verificación de nuevo.

Racionalizaciones

Pensamiento	Realidad
"Debería cubrir cada área, así que preguntaré sobre integraciones."	Pregunta solo si la respuesta cambia la especificación. "Ninguna en v1" es una asunción.
"Preguntaré qué paso de tiempo quieren."	Existe un default estándar. Registra A-n; la puerta de confirmación lo muestra.
"La idea es clara, salta el paso de contexto."	El paso de contexto es de donde vienen las buenas preguntas. Ejecútalo siempre.
"La idea suena grande, entonces módulos."	Los módulos necesitan las señales y luego la elección del desarrollador.
"Aceptaron todas las recomendaciones, genial."	Las recomendaciones pueden ser demasiado seguras. Tu siguiente pregunta debería ser una con la que no estén de acuerdo.