gvozdb/semantic-spec-writer-skill

Semantic Spec Writer (Redactor de Especificaciones Semánticas)

Produce archivos .plan.ctx y .spec.ctx que un agente de implementación puede usar sin cargar esta habilidad.

Modo

• Documento nuevo: escribe el artefacto semántico final directamente a partir de la solicitud y los hechos fundamentados del repositorio. No crees primero un borrador en prosa.
• Documento existente: conviértelo solo según lo solicitado, preservando el significado original y los identificadores. El artefacto final debe ser más corto que la fuente.
• Transferencia o uso repetido: optimiza para la ejecución independiente por parte de otro agente o en una ejecución posterior.
• Paquete de ejecución de repositorio: cuando el usuario quiera una transferencia de codificación y el código base esté disponible, lee references/execution-packets.md. Fundamenta una ruta mínima de lectura/edición antes de escribir el paquete.

No afirmes que la conversión ahorra tokens totales para una implementación única. Agrega un paso de autoría; su economía proviene de un contexto reutilizable más pequeño y menos ambigüedad en la implementación.

Objetivo

Optimiza el ciclo completo de implementación, no solo el recuento de caracteres:

• preserva cada comportamiento, restricción, caso extremo e identificador exacto;
• elimina narrativa, repetición, metadatos decorativos y consejos genéricos;
• expone la ruta confiable más corta desde el requisito hasta la edición y verificación;
• prefiere el lenguaje directo sobre las abreviaturas que requieren interpretación.

Un archivo más pequeño es útil solo cuando sigue siendo más rápido de ejecutar correctamente. Al convertir un documento existente, planifica la estructura compacta antes de escribir y evita expandir la fuente. No agregues bucles de herramientas o reescrituras repetidas solo para reducir el tamaño del archivo.

Disciplina de tokens

• Lee cada fuente proporcionada una sola vez, a menos que falte un hecho que requiera una búsqueda específica.
• Inspecciona solo los archivos necesarios para fundamentar el alcance, las interfaces y la verificación.
• Escribe un único artefacto final. Hazlo más corto en la escritura inicial. Para conversiones, ejecuta scripts/check_conversion.py SOURCE OUTPUT desde este directorio de habilidad una vez. Cuando se conozca el tokenizador de destino y tiktoken esté disponible, pasa --encoding NAME. Si la verificación falla, elimina la redundancia una vez y ejecútala una vez más; nunca continúes un bucle de reducción de tamaño. No emitas un esquema, borrador, notas de conversión, informe de tamaño o explicación a menos que se solicite.
• No copies hechos del repositorio que el agente de implementación pueda obtener del archivo de destino exacto sin buscar. Incluye hechos que eviten una edición incorrecta o un descubrimiento adicional.
• Prefiere rutas exactas y un comando de verificación ejecutable sobre consejos de implementación genéricos.
• Para un paquete de ejecución, dedica esfuerzo de autoría solo a los hechos que eliminen el descubrimiento posterior o eviten una edición incorrecta. No conviertas el paquete en un volcado del repositorio.
• Proporciona a los paquetes de ejecución el bucle canónico acotado posterior de la referencia: una lectura enrutada, un pase de implementación, una verificación declarada, luego detente en caso de éxito. La expansión requiere una contradicción o fallo concreto.

Formato

• Comienza con plan o spec sin formato.
• Usa .plan.ctx para planes y .spec.ctx para especificaciones a menos que el proyecto tenga otra convención.
• Usa nombres de bloque locales obvios. Son etiquetas, no palabras clave reservadas del lenguaje.
• Incluye solo bloques que contengan información. No emitas secciones vacías.
• Combina hechos de alcance, objetivo y contrato cuando bloques separados repetirían la misma información.
• Preserva exactamente rutas de archivo, símbolos, rutas de API, campos, tablas, variables de entorno, comandos, estados, roles y texto de error.
• Preserva exactamente la propiedad y anidación de campos. Adapta la notación de campo al lenguaje de implementación: para Python JSON/mapas usa event["payment_id"], no event.payment_id. Nunca inventes un contenedor data, payload u otro que la fuente no defina.
• Trata .ctx como texto plano, no Markdown. No envuelvas identificadores comunes en comillas invertidas, negrita u otro formato de presentación. Usa comillas invertidas solo para comandos ejecutables bajo verify.
• Define un término local solo cuando elimine repeticiones reales. Prefiere términos descriptivos; evita alias de una letra y notación inventada.
• Agrega IDs solo cuando otro elemento los referencie.
• Usa expresiones familiares como x=true, x in [a,b] y condition -> result. No te bases en sintaxis oculta.
• Usa un comentario corto con # solo cuando los campos estructurados perderían matices críticos.
• Agrupa validaciones paralelas, campos de salida y errores exactos bajo un mapeo compacto en lugar de repetir la misma estructura de oración.
• Después de establecer la propiedad del campo, usa etiquetas cortas y sin ambigüedad en los mapas de validación y error en lugar de repetir la ruta completa del propietario.
• En un mapa de errores, deja que el bloque lleve la gramática repetida. Prefiere campo: condición | TipoError "mensaje exacto" sobre repetir owner.campo inválido -> TipoError en cada línea.
• Mantén una regla comprobable de forma independiente por línea. Un mapeo compartido puede contener casos de campo relacionados cuando su gramática sea consistente.
• Usa IDs con formato A* solo una vez, bajo acceptance. No reutilices IDs de aceptación como IDs de regla o tarea.

Fundamentación

Cuando un código base esté disponible, inspecciónalo antes de escribir. Captura el alcance de edición conocido, las interfaces existentes, las restricciones y los comandos de verificación ejecutables. Incluye verify solo para un comando exacto o una verificación nombrada existente; no inventes escenarios de verificación. No adivines nombres de archivo o arquitectura.

Las decisiones desconocidas pertenecen a open_questions. Omite ese bloque cuando no haya incógnitas.

Orden de la información

Coloca la información en el orden que un agente de implementación la necesita. Usa solo las partes relevantes:

1. objetivo o meta, incluido el alcance de edición exacto cuando se conozca;
2. contratos no establecidos ya por el objetivo;
3. reglas, invariantes, estados o flujos;
4. trabajo ordenado solo donde las dependencias importen;
5. comandos de verificación y aceptación observable;
6. preguntas no resueltas.

El alcance exacto y la verificación generalmente ahorran más trabajo del agente que la compresión agresiva de la prosa.

Reglas de compresión

• Expresa cada hecho una vez.
• Fusiona requisitos duplicados.
• Omite un bloque cuando su contenido ya esté cubierto por otra línea.
• Haz que la aceptación haga referencia a IDs de reglas, contratos y verificación existentes en lugar de reafirmar su prosa.
• Mantén la aceptación solo como referencias cuando los bloques referenciados ya establezcan el comportamiento observable.
• Mantén las razones solo cuando cambien una decisión de implementación.
• Reemplaza verbos vagos como mejorar, soportar, manejar, optimizar y corregir con resultados observables.
• Mantén casos extremos raros pero consecuentes. Nunca los elimines para hacer el archivo más corto.
• No codifiques requisitos ordinarios como fórmulas solo para reducir palabras.
• Prefiere una fórmula entera exacta derivada de la fuente sobre una descripción en prosa más larga cuando sea más fácil de ejecutar correctamente.

Ejemplos

Especificación de implementación:

spec
target: [src/payments.ts,tests/payments.test.ts] :: hacer POST /payments idempotente mediante Idempotency-Key
keep: esquema de respuesta, comportamiento de autenticación

rules:
  R1: el alcance de la clave es user_id
  R2: mismo usuario + misma clave + mismo cuerpo -> repetir estado y cuerpo original
  R3: persistir resultado antes de devolver éxito

errors:
  E1: falta Idempotency-Key -> 400 idempotency_key_required
  E2: misma clave + cuerpo diferente -> 409 idempotency_conflict

verify:
  V1: `pnpm test tests/payments.test.ts`

acceptance:
  A1: R1,R2,R3,E1,E2 -> V1

Mapa de validación paralela:

validation:
  retries: int>=0 | ValueError "retries must be non-negative"
  timeout: int>0 | ValueError "timeout must be positive"

Plan de implementación:

plan
goal: mover el almacenamiento de sesiones de memoria a Redis sin cambiar el comportamiento de la API

facts:
  store actual: src/session/memory.ts
  pruebas de contrato: tests/session.contract.test.ts

tasks:
  T1: agregar adaptador Redis detrás de la interfaz SessionStore existente
  T2: ejecutar pruebas de contrato contra los adaptadores de memoria y Redis
  T3: cambiar el raíz de composición después de que T2 pase

verify:
  V1: `pnpm test tests/session.contract.test.ts`

Compuerta de calidad

Antes de finalizar, verifica:

• un nuevo agente de implementación puede actuar sin esta habilidad o contexto no declarado;
• cada línea cambia el alcance, el comportamiento, el orden de implementación o la verificación;
• ningún requisito está duplicado o reemplazado por una abreviatura no definida;
• los archivos, interfaces y comandos conocidos son exactos;
• la aceptación es observable y se remonta al contrato establecido;
• cada campo aún tiene el mismo propietario y anidación que en la fuente;
• el resultado es más corto al eliminar redundancia, no al oscurecer el significado.

Genera primero el documento semántico. Agrega notas separadas solo para decisiones no resueltas que bloqueen materialmente la implementación.