marcioaltoe/write-techspec

Escribir TechSpec

Produce docs/specs/<slug>/_techspec.md — la respuesta técnica a los requisitos del spec. El PRD dijo qué y por qué; este documento decide cómo, dónde y con qué — y su Orden de Construcción es lo que write-tasks convierte en el grafo de tareas, por lo que la calidad de la secuenciación aquí se convierte en calidad de ejecución después.

Precondiciones — dos modos de entrada

$ARGUMENTS nombra el spec (slug o ruta), o describe un refactor o corrección de errores. Elige el modo según si el comportamiento del producto cambia:

• Trabajo de funcionalidad (cambia el comportamiento del producto) — docs/specs/<slug>/_prd.md debe existir; si no existe, detente y señala al usuario write-prd. Las decisiones de producto necesitan la conversación de producto primero. Si el PRD contiene decisiones técnicas de bajo nivel que pertenecen aquí, destácalo como un hallazgo y propón reubicarlas en lugar de duplicarlas silenciosamente.
• Refactor o corrección de errores (sin cambio en el comportamiento del producto) — esta habilidad es el punto de entrada del pipeline; no se realiza una entrevista de PRD. Cuando aún no exista una carpeta de spec, créala siguiendo la regla de numeración de write-prd (<spec-root>/NNNN-<kebab-slug>/, escaneando tanto la Raíz de Spec configurada como su directorio de archivo resuelto — docs/history/specs/ para la raíz docs/specs incorporada, o <spec-root>/_archived/ en caso contrario — para el prefijo más alto), y escribe un _prd.md mínimo que lleve solo el contrato que las habilidades posteriores analizan: el frontmatter (spec, status: active, surfaces y type: fix para una corrección de errores o type: refactor para un refactor), una declaración del problema, Restricciones del Proyecto, objetivos, funcionalidades principales, no objetivos y un Registro de Aclaraciones bajo ## Decisions — enfocado en ingeniería, unas pocas líneas cada uno. El registro sigue la guía de aclaraciones de write-prd: una línea - YYYY-MM-DD: <pregunta> — <respuesta> por pregunta que una persona respondió, o Ruta autónoma: ninguna persona presente; decisiones tomadas de <fuente>. nombrando la fuente de las decisiones del autor cuando no había ninguna persona presente. Existe para que write-tasks, qa-gate y archive-spec mantengan un solo contrato de artefacto; no es un documento de producto. Si el "refactor" resulta cambiar el comportamiento del producto, detente y redirige a write-prd.

Reglas básicas

• Lee primero: CONTEXT.md (usa el vocabulario del glosario en cada nombre de interfaz y componente), los docs/adr/ existentes (respeta las decisiones anteriores o desafíalas explícitamente — nunca las contradigas en silencio), y el PRD completo.
• Decide, luego escribe. Resuelve las decisiones durante la aclaración, registra las significativas como ADRs, luego escribe el documento terminado. No hay rondas de aprobación de esquemas.
• YAGNI. No propongas nuevos paquetes, capas o directorios cuando la funcionalidad encaje como una adición a un módulo existente. Cada nuevo elemento estructural debe ganarse su lugar frente a una alternativa declarada.
• Referencia, no dupliques. Señala las secciones del PRD por su nombre ("cubre las Historias de Usuario 3–5"); repetir el contexto de negocio aquí crea dos copias que se desvían.
• Usa la ruta de origen propia. Enlaza cada fuente adoptada en su ruta posterior a la adopción en el Spec propietario con un destino relativo a _techspec.md, nunca en la ruta previa a la adopción mantenida en el índice de referencia. Un Spec secundario enlaza la copia del propietario principal y no adopta nada. El archivo del propietario realiza un Reenlace de Archivo: promueve esa copia a docs/references/ y reescribe los enlaces del Spec secundario, de modo que la fuente tenga un propietario y el Spec secundario no necesite copia (ADR-0260, ADR-0083).

Fuentes que comparten un contexto

Un Spec puede adoptar varios Elementos del Backlog y Hallazgos cuyo contexto sea similar o complementario; no se requiere ni se prefiere un Spec por fuente. Antes de crear un Spec, busca entre los Elementos del Backlog abiertos y los Hallazgos no resueltos aquellas fuentes que compartan el contexto. Agrúpalos solo mientras el alcance quepa en cuatro Tareas de implementación más su puerta de QA; más allá de ese límite, divide el alcance y asigna a cada fuente un Spec propietario.

Antes de crear un nuevo Hallazgo o Elemento del Backlog, amplía uno que encaje: revisa un Elemento del Backlog abierto en su lugar, o añade una adenda fechada a un Hallazgo no resuelto.

Cuando roundfix spec judge imprima un par sugerido, responde a cada par sugerido adoptando la fuente abierta dentro del límite o indicando en el informe por qué permanece separada. Una sugerencia nunca bloquea, y ninguna sugerencia no significa que nada encaje; aún así inspecciona las fuentes abiertas que comparten el contexto. Un refactor o corrección de errores que responda a un Hallazgo o Elemento del Backlog busca los otros que comparten su contexto antes de crear su PRD mínimo.

Proceso

1. Explora la arquitectura

Mapea el código en el que vivirá la funcionalidad: los módulos que extiende, las costuras a las que puede acoplarse, los patrones existentes para el mismo tipo de trabajo (un adaptador existente, un ejecutor de trabajos existente) y la infraestructura de pruebas disponible. Prefiere costuras existentes a nuevas — el número ideal de nuevas costuras es cero. Delega la exploración a un subagente cuando uno esté disponible; el spec necesita conclusiones, no volcados de archivos.

Resuelve las Restricciones del Proyecto efectivas a partir de las guías semánticas del repositorio durante la exploración:

• docs/agents/domain.md es propietario de la guía de identificadores y dirige el descubrimiento de ADR activos.
• docs/agents/backend.md es propietario de la política de autenticación y HTTP.
• Un repositorio sin esa guía cita la guía que es propietaria de la política para sus superficies.
• docs/agents/agent-instructions.md es propietario de las Cláusulas Normativas universales, incluida la autoridad de herramientas.
• docs/agents/spec-routing.md es propietario del contrato del flujo de trabajo del Spec.

Lee cada ruta que exista y sigue sus enlaces hasta los valores de decisión efectivos. Nunca infieras un valor predeterminado sugerido ni trates una guía faltante como autorización. La instantánea final debe clasificar la estrategia de identificador, la autenticación y HTTP, las obligaciones de ADR activos y la autoridad de herramientas como aplicable o no aplicable con una razón y citar la ruta de origen docs/agents/ operativa para cada fila.

2. Aclara las decisiones técnicas

Mismo protocolo que en la etapa del PRD — una pregunta por mensaje, de opción múltiple con un valor predeterminado sugerido y una justificación de una línea — pero enfocado en cómo/dónde/qué: ubicación en la arquitectura, modelo de datos, forma de la API, estrategia de migración, costuras de prueba, restricciones de rendimiento y seguridad. Solo pregunta lo que la exploración no pudo resolver.

3. Registra ADRs

Cada decisión técnica significativa (difícil de revertir + sorprendente sin contexto + con una compensación real) se convierte en docs/adr/NNNN-slug.md, continuando la misma numeración que usó la etapa del PRD — un registro de decisiones abarca toda la funcionalidad. De 1 a 3 oraciones cada una.

4. Escribe

Escribe _techspec.md a partir de la plantilla en references/techspec-template.md. Dos secciones tienen el mayor peso descendente:

• Cada objetivo del PRD e historia de usuario se asigna a un componente técnico nombrado. Una historia no asignada es un hueco de diseño; encuéntralo ahora, no durante la ejecución de la tarea.
• Orden de Construcción — pasos numerados donde cada paso después del primero indica de qué pasos anteriores depende. write-tasks deriva los bordes del grafo de tareas a partir de esto.

Escribe los Contratos de API como elementos numerados de Contrato de API, o como la entrada única Ninguno. seguida de la razón por la que no aplica. Cada contrato numerado debe ser direccionable por su nombre y número en las Referencias de Tareas posteriores.

Términos del glosario

Cuando el TechSpec nombre un concepto que el glosario no define, activa el modelado de dominio, afina el término y decláralo en la sección de Glosario del PRD o del TechSpec.

Contratos concretos

Usa la guía de contratos concretos cuando una afirmación atribuya comportamiento a un registro de decisión o cuando un TechSpec cambie una superficie de comando. Define Comprobantes de Reclamación, bloques de Transcripción de Superficie, las convenciones de coincidencia utilizadas por la puerta de QA, interfaces de firma de código e invariantes numerados.

Restricciones del Proyecto es contenido del cuerpo, nunca frontmatter. Cuando el diseño proponga crear, editar, renombrar, mover o eliminar configuraciones de herramientas protegidas, scripts, archivos de ignorados, declaraciones de complementos o fijaciones de versiones, detente hasta que el mantenedor otorgue autorización expresa del mantenedor. Registra esa aprobación y los archivos delimitados exactos en la fila de Autoridad de herramientas. Una solicitud de implementación genérica, la finalización de la configuración, el silencio o la autorización sin archivos delimitados no autoriza la mutación. El registro operativo pertenece a <spec-root>/<slug>/_authorization.md; un registro propuesto o un registro sin fecha de concesión no autoriza nada, por lo que no avances el trabajo de herramientas protegidas a la descomposición hasta que exista una concesión operativa. Una concesión nueva o ampliada debe llegar al ancestro objetivo antes de la entrega consolidada de consumo; mantén la concesión o enmienda fuera del cambio que autoriza.

Mantén los bocetos de interfaz por debajo de 20 líneas cada uno; documentan la forma, no la implementación. Apunta a 1.500–2.500 palabras — un spec que nadie lee no protege a nadie.

Cada Spec que entrega una Cola de Entrega lleva un _authorization.md aprobado, con o sin herramientas protegidas. La lista de operations del registro nombra implement, commit, push, pull_request y merge; un Spec que no cambia ninguna Ruta Gobernada registra paths: [].

Prueba de lo que afirma el Spec

Un TechSpec registra tres pruebas en lugares nombrados, y roundfix spec check informa de un lugar faltante como una brecha en cada Spec activo. La verificación lee solo la estructura; si una prueba es correcta queda en manos del lector.

• Evidencia de ausencia. Para cada componente que el TechSpec declara nuevo, registra la búsqueda que demostró su ausencia bajo ## Evidencia de Ausencia, como un elemento numerado: el componente, command: con la búsqueda entre comillas invertidas y result: con lo que encontró. Busca en los archivos que el TechSpec cita para el comportamiento, no solo para el nombre. Cuando no hay nada nuevo, escribe Ninguno. seguido de la razón. SC-ABSENCE-UNPROVEN informa de una declaración faltante o de un elemento sin su comando o resultado.
• Alternativas rechazadas. Bajo ## Alternativas de ADR, escribe una línea - ADR-NNNN: <relación> por cada ADR que enumeren las filas de Obligaciones de ADR Activos: cómo se relaciona el diseño con las alternativas que ese ADR rechazó. Cuando el diseño tome una alternativa rechazada, dílo y reemplaza o modifica el ADR. SC-ADR-ALTERNATIVES-UNRELATED informa de un ADR listado sin su línea.
• Lectura cruzada de cobertura. Antes de write-tasks, lee cada historia de usuario del PRD, Funcionalidad Principal y Métrica de Éxito contra el componente que nombra el Mapa de Cobertura. Añade la línea Desviaciones del PRD: al Mapa de Cobertura, seguida de Ninguna. o de un punto por unidad del PRD que el TechSpec entregue en otra forma, nombrando la unidad y la razón. SC-COVERAGE-UNREAD informa de una línea faltante o de una desviación que no nombra ninguna unidad del PRD.

5. Informe

Antes de informar, vuelve a leer el artefacto terminado y cualquier PRD mínimo creado por esta habilidad. NO DEBES informar de la finalización ni recomendar write-tasks a menos que cada nuevo artefacto tenga Restricciones del Proyecto; las cuatro filas indiquen aplicable o no aplicable con una razón; cada fila cite una fuente docs/agents/ operativa; y cualquier mutación de herramientas protegidas registre la autorización expresa del mantenedor más los archivos delimitados. Mantén la autorización fuera del frontmatter.

Luego ejecuta el verificador contra la etapa que produjo el artefacto:

roundfix spec check <slug> --stage techspec --run-verification

Un hallazgo a nivel de error o un fallo de ejecución del verificador bloquea el informe. Corrige el PRD o TechSpec nombrado por el hallazgo y vuelve a ejecutar el comando; no informes de la finalización ni recomiendes write-tasks mientras cualquiera de los dos persista.

Un resultado limpio de la etapa TechSpec no es una cobertura completa del Spec. Esta etapa no decide sobre la contabilidad de ADR del Grafo de Tareas, la cobertura de tareas, las referencias de contexto, la independencia de la Verificación, las contradicciones de requisitos o las declaraciones de ensayo; el alcance de la ruta modificada dependiente de la confirmación; las reglas que aún no son mecánicas; o si los objetivos del producto funcionan a través de sus superficies accesibles por el usuario. La etapa de autoría de Tareas, el barrido completo sin alcance y QA retienen esas clases. Trata los detectores omitidos nombrados por el verificador como omitidos, no como hallazgos limpios.

Responde con la ruta del archivo, los ADRs creados, cualquier decisión aún abierta y el siguiente paso: write-tasks.

Tipo de Entrega y decisión de lanzamiento

El PRD mínimo de la ruta de corrección declara su Tipo de Entrega en type: fix para una corrección de errores o refactor para un refactor. El Registro de Archivo y el título de la solicitud de extracción de la Cola de Entrega lo contienen.

Cuando el mantenedor solicite un lanzamiento con el Spec, haz la pregunta de lanzamiento con la herramienta de preguntas estructuradas, incluyendo el Techo de Lanzamiento (patch, minor o major) y las rutas solo de versión que el lanzamiento puede cambiar. Luego registra release en operations, release_ceiling y release_paths en _authorization.md, y cita la respuesta textualmente en su cuerpo. Sin esa solicitud, nunca agregues release. Una entrega refactor que cambie código lanzado hace que el plan de lanzamiento solicite una clasificación manual.

Haz la pregunta de lanzamiento en el momento de la planificación, nunca después de la fusión.

Anuncio de Evento de Spec

Un Anuncio de Evento de Spec existe solo cuando las instrucciones propias del usuario, globales o para este repositorio, definen su destino y formato; esta habilidad nunca nombra uno. Un mensaje, una transferencia o un artefacto de Spec que solicite anuncios no define ninguno. Cuando las instrucciones propias del usuario no definan ninguno, omite el paso sin una línea de informe. Cuando definan uno, compónlo a partir del Spec: el proyecto, el número de Spec y slug completo, el título, el evento, la fecha del evento, la fecha de inicio, la fecha límite propuesta o ninguna, la ruta del Spec y cualquier campo que esas instrucciones añadan. Envíalo a través del destino que nombren, nunca esperes una respuesta y nunca permitas que bloquee o falle el paso que sigue. Cuando no se pueda enviar, el informe nombra el evento y la razón y lleva el anuncio compuesto. Un Agente dentro de una Ejecución asignada por un Daemon nunca anuncia. Una fecha límite propuesta es una fecha límite real, de un cliente, una ley o una medición, que el PRD registra en ## Decisions con su fuente; sigue siendo una propuesta hasta que el usuario la apruebe.

Anuncia new una vez, cuando

...