Cómo gestionar el feedback en GitHub Spec Kit antes y después de la implementación

TL;DR

• GitHub Spec Kit es útil para investigar porque convierte una idea vaga en una secuencia de artefactos que se pueden revisar: spec.md, plan.md, tasks.md y verificaciones relacionadas.
• El mejor momento para gestionar la mayor parte del feedback es antes de la implementación, cuando todavía es económico cambiar los requisitos, la arquitectura y el orden de las tareas.
• El feedback previo a la implementación debe dirigirse al artefacto correspondiente:
  • la intención de producto y el comportamiento del usuario van a spec.md
  • la arquitectura y las restricciones van a plan.md
  • la secuencia y las responsabilidades van a tasks.md
• El feedback posterior a la implementación debe clasificarse como:
  • defecto de implementación
  • requisito omitido
  • cambio de requisito
  • documentación desactualizada
  • solicitud de una nueva funcionalidad
• La decisión más importante del equipo es su modelo de persistencia de la especificación:
  • especificación flow-back
  • especificación flow-forward
  • especificación viva
• Mi recomendación por defecto para equipos que reciben muchos comentarios es:
  • usar flow-forward para cambios importantes en los requisitos
  • usar flow-back para los hallazgos de implementación dentro del mismo PR
  • usar una especificación viva solo cuando el equipo esté listo para mantener spec.md como contrato del producto
• Spec Kit no es tu única opción. Según el problema, quizá prefieras Kiro, Tessl, BDD/Gherkin, desarrollo de API contract-first o un flujo más ligero basado en RFC e issues.

Qué aprenderás aquí

• Para qué sirve GitHub Spec Kit durante la investigación
• Cómo usar Spec Kit para explorar alternativas antes de fijar un plan
• Cómo clasificar muchos comentarios sobre spec.md, plan.md y tasks.md
• Cómo gestionar el feedback antes de que comience la implementación
• Cómo gestionar el feedback después de que ya se haya implementado
• Cómo elegir entre especificaciones flow-back, flow-forward y vivas
• Cuándo una alternativa a Spec Kit puede ser más adecuada

La pregunta de investigación

El escenario es muy real:

Creaste los artefactos de Spec Kit para una funcionalidad. Antes de la implementación, los PMs, ingenieros, diseñadores, QA, seguridad y quizá un equipo que trabaja directamente con clientes dejaron muchos comentarios. Luego comenzó la implementación. Después llegó aún más feedback sobre el código, el comportamiento, la cobertura de pruebas y los artefactos de la especificación.

¿Y ahora qué?

La respuesta ingenua es:

Just update the docs and code until everyone is happy.

Suena razonable, pero normalmente genera inconsistencias.

La mejor respuesta es:

Treat every comment as an input to the artifact lifecycle.
Route it to the right phase.
Update the smallest source of truth that can resolve it.
Re-run the relevant Spec Kit gate before moving forward.

Ese es el modelo de trabajo que desarrolla este artículo.

Qué te ofrece realmente GitHub Spec Kit

GitHub describe Spec Kit como un conjunto de herramientas para el desarrollo guiado por especificaciones, en el que las especificaciones se convierten en artefactos activos del proceso de entrega, en lugar de ser documentos que se escriben una vez y se olvidan.

La documentación actual describe el flujo principal así:

Spec -> Plan -> Tasks -> Implement

Para trabajo en producción, la guía de inicio rápido recomienda un recorrido más completo:

/speckit.constitution
  -> /speckit.specify
  -> /speckit.clarify
  -> /speckit.checklist
  -> /speckit.plan
  -> /speckit.tasks
  -> /speckit.analyze
  -> /speckit.implement

Esa secuencia importa porque el feedback corresponde a distintos lugares según el momento en que llega.

Antes de la implementación, atender el feedback es económico porque todavía puede modificar la especificación, el plan y la lista de tareas.

Después de la implementación, atenderlo es más costoso porque puede requerir cambios en el código y las pruebas, reconciliar artefactos o crear un nuevo directorio de funcionalidad.

Cómo usar Spec Kit para investigar

Spec Kit no es solo un flujo de trabajo para desarrollar. Si se usa con cuidado, también sirve para investigar.

La clave está en dejar de tratar la investigación como un prompt gigante como este:

Research this feature and tell me what to build.

En cambio, usa las fases.

question
  -> product intent
  -> open ambiguities
  -> technical options
  -> task shape
  -> consistency check

En la práctica:

1. Usa /speckit.specify para definir el problema y el resultado esperado para el usuario.
2. Usa /speckit.clarify para sacar a la luz las decisiones de producto pendientes.
3. Usa /speckit.plan para comparar enfoques técnicos.
4. Usa /speckit.tasks para ver cuánto costaría cada enfoque.
5. Usa /speckit.analyze para detectar contradicciones antes de empezar a escribir código.

Este es el estilo de prompt que usaría para investigar:

/speckit.plan
Investigate three implementation alternatives before choosing one:

1. Minimal change inside the existing module
2. New internal service boundary
3. Third-party managed service integration

For each option, include:
- product tradeoffs
- engineering complexity
- migration risk
- operational risk
- testing impact
- expected rollback strategy

Do not choose an option until the tradeoff table is complete.

Esto les sirve tanto a ingenieros como a PMs porque la conversación pasa de «¿qué opinas?» a «¿qué compromiso estamos aceptando?».

A dónde debe ir el feedback

Cuando llegan muchos comentarios, no los proceses en orden cronológico.

Procésalos según su destino.

comment
  |
  +-- changes user behavior? -------> spec.md
  |
  +-- changes constraints/design? ---> plan.md
  |
  +-- changes work order/scope? ----> tasks.md
  |
  +-- exposes contradiction? -------> analyze/checklist
  |
  +-- finds code mismatch? ---------> implementation + tests
  |
  +-- asks for new capability? -----> new spec or linked follow-up

Esa clasificación es la primera disciplina. Sin ella, cada artefacto termina convirtiéndose poco a poco en una mezcla de intención de producto, decisiones técnicas, tareas sueltas y notas sobre bugs.

Una tabla para clasificar el feedback

Me gusta usar una tabla pequeña durante la revisión:

Suena básico. En la práctica, marca la diferencia entre una revisión caótica y un registro de decisiones útil.

El flujo ideal para el feedback antes de la implementación

Antes de la implementación, el objetivo es que atender los comentarios sea económico.

Yo gestionaría el feedback así:

draft spec
  -> collect comments
  -> route comments
  -> resolve product ambiguity
  -> update spec
  -> validate checklist
  -> draft plan
  -> collect engineering/security/QA comments
  -> update plan
  -> generate tasks
  -> run analyze
  -> implementation starts

Paso 1: Congela brevemente la versión que se va a revisar

No permitas que el conjunto de artefactos cambie cada cinco minutos mientras los revisores lo leen.

Crea una instantánea para la revisión:

specs/042-billing-export/
  spec.md
  plan.md
  tasks.md
  research.md

Luego pide a los revisores que comenten sobre esa instantánea.

Paso 2: Separa «hay que resolverlo ahora» de «puede quedar para después»

Usa un conjunto simple de etiquetas:

blocker: must resolve before implementation
clarify: answer before plan/tasks are final
plan-change: affects architecture or constraints
task-change: affects sequencing or ownership
follow-up: valid, but not part of this slice
out-of-scope: intentionally excluded

Esto evita que la revisión se convierta en un referéndum sobre todo el roadmap del producto.

Paso 3: Ejecuta /speckit.clarify para los comentarios sobre requisitos

Si los comentarios revelan decisiones de producto pendientes, no pases directamente al plan técnico.

Haz una ronda de aclaraciones:

/speckit.clarify
Review the open comments tagged clarify and blocker.

For each comment:
- identify the missing decision
- propose 2-3 possible answers
- recommend the lowest-risk answer
- update spec.md only after the decision is explicit

Esto mantiene el feedback de los PMs en la capa de producto antes de que los ingenieros ajusten demasiado el diseño a supuestos incompletos.

Paso 4: Ejecuta /speckit.checklist antes de planificar

La guía de inicio rápido oficial recomienda usar /speckit.checklist antes de crear el plan técnico. Ese es exactamente el momento en que yo lo usaría después de una ronda extensa de comentarios.

La checklist es el punto de control para responder «¿estamos listos para diseñar?».

Si no se supera, son buenas noticias. Encontraste a tiempo una confusión que habría salido cara.

Paso 5: Usa /speckit.plan para explorar alternativas

Cuando los ingenieros no estén de acuerdo, lleva el desacuerdo a una tabla de opciones.

/speckit.plan
Based on the reviewed spec, compare these approaches:

A. Extend the current export worker
B. Add a dedicated export orchestration module
C. Use the existing workflow engine

For each approach, include:
- files or modules likely affected
- migration plan
- testing strategy
- operational risk
- reason to reject or accept

Select one recommendation and explain why.

Es aquí donde Spec Kit se vuelve útil para investigar, no solo para documentar.

Paso 6: Ejecuta /speckit.analyze antes de la implementación

La guía de inicio rápido recomienda ejecutar /speckit.analyze antes de /speckit.implement para detectar contradicciones mientras todavía se pueden ajustar las tareas.

Después de una ronda extensa de comentarios, este paso no es opcional en mi flujo de trabajo.

Le pediría que revise:

/speckit.analyze
Audit spec.md, plan.md, and tasks.md after the review updates.

Flag:
- requirement not represented in the plan
- plan decision not represented in tasks
- task with no requirement or plan source
- contradiction between acceptance criteria and implementation plan
- missing test task for a high-risk behavior

Solo entonces debería comenzar la implementación.

El flujo ideal para el feedback después de la implementación

Después de la implementación, la pregunta cambia.

Antes de que exista código, el comentario dice:

What should we build?

Una vez que existe código, el comentario puede significar:

The code failed the spec.
The spec missed reality.
The requirement changed.
The plan was wrong.
The artifact set drifted.

Esos son problemas muy distintos.

Este es el flujo posterior a la implementación que recomiendo:

review comment
  -> classify
  -> choose artifact owner
  -> update code or spec source
  -> update tests
  -> reconcile derived artifacts
  -> re-run checks
  -> decide merge or follow-up

Paso 1: Clasifica el comentario

Usa este árbol de decisión:

Does the implementation violate the approved spec?
  yes -> fix code and tests
  no
    |
    +-- Did the spec miss a real requirement?
    |     yes -> update spec, then plan/tasks/tests
    |
    +-- Did the requirement change after approval?
    |     yes -> decide flow-back vs flow-forward vs living spec
    |
    +-- Is this a new capability?
          yes -> create follow-up spec

Aquí es donde muchos equipos se meten en problemas sin darse cuenta. Tratan todos los comentarios posteriores a la implementación como comentarios de revisión de código, incluso cuando en realidad implican un cambio en la especificación.

Paso 2: Elige el modelo de persistencia adecuado

La documentación actual de Spec Kit dice explícitamente que el conjunto de herramientas no impone una única estrategia de mantenimiento para spec.md, plan.md y tasks.md después de que cambian los requisitos.

La documentación describe tres modelos comunes:

Mi recomendación práctica:

• Usa flow-back para los hallazgos dentro del mismo PR de implementación.
• Usa flow-forward cuando el feedback cambie el alcance aprobado del producto.
• Usa una especificación viva solo cuando el equipo haya acordado que spec.md es el contrato a largo plazo.

Paso 3: No entierres nuevos requisitos en la revisión de código

Si la implementación es correcta pero el stakeholder quiere un comportamiento nuevo, crea un cambio separado.

Ejemplo:

specs/
  042-billing-export/
    spec.md
    plan.md
    tasks.md
  043-scheduled-billing-export/
    spec.md
    plan.md
    tasks.md

Luego vincula su procedencia:

## Relationship to Previous Work

This spec extends `042-billing-export`.

It does not replace the manual export flow.
It adds scheduled export configuration, execution, and audit behavior.

Esto permite que el PR actual siga listo para entregarse y mantiene visible la nueva solicitud.

Paso 4: Alinea las pruebas con el artefacto que prevaleció

Si prevalece la especificación, cambian el código y las pruebas.

Si prevalece el hallazgo de implementación, actualiza la especificación y las pruebas para que quienes las consulten en el futuro entiendan por qué.

Si el nuevo requisito se pospone, agrega una especificación o un issue de seguimiento y mantén las pruebas actuales alineadas con el comportamiento aprobado.

Esta es la parte aburrida. También es la que protege al equipo de situaciones en las que «la documentación dice una cosa, las pruebas dicen otra y producción hace una tercera».

Un protocolo práctico para gestionar comentarios

Si tuviera que incluir esto en un acuerdo de trabajo del equipo, lo mantendría así de simple:

1. Every comment gets classified before it gets fixed.
2. Product behavior comments update spec.md first.
3. Architecture comments update plan.md first.
4. Sequencing comments update tasks.md first.
5. Code comments either fix implementation or trigger explicit spec reconciliation.
6. New scope becomes a follow-up spec unless the team reopens the current scope.
7. /speckit.analyze runs before implementation and after major post-implementation spec changes.

Y agregaría una regla que evita muchos dolores de cabeza:

If reviewers disagree about which artifact owns the comment,
pause and classify it together.

Esa pequeña pausa cuesta mucho menos que permitir que el comentario modifique tres archivos de forma inconsistente.

Ejemplo: antes y después de la implementación

Imagina que la funcionalidad es:

Allow finance admins to export monthly invoices as CSV.

Durante la revisión previa a la implementación, llegan estos comentarios:

PM: Customers need to filter by billing entity.
Security: Exports must be audit logged.
Engineer: The current invoice query cannot handle six-month ranges.
QA: We need failure cases for empty months and partial invoice data.

Dirígelos así:

PM comment --------> spec.md acceptance criteria
Security comment --> plan.md constraints + tasks.md audit task
Engineer comment --> plan.md technical approach
QA comment -------> tasks.md test coverage

Después de la implementación, llegan estos comentarios:

Reviewer: The code allows non-admin users to call the endpoint.
PM: Can we also schedule this every month?
Engineer: The task said streaming, but the implementation buffers in memory.
QA: The CSV has no test for invoices with missing tax IDs.

Gestiónalos así:

non-admin access ----> code defect, fix before merge
scheduled exports ---> new follow-up spec
buffering mismatch --> reconcile plan vs implementation, then fix or document
missing tax ID test -> add test task and test

Lo importante no es la tabla en sí. Lo importante es negarse a tratar todos los comentarios como si fueran el mismo tipo de trabajo.

Alternativas a GitHub Spec Kit

Spec Kit es una buena opción cuando quieres un flujo de trabajo abierto, local al repositorio y flexible en cuanto a los agentes que puedes usar.

No siempre es la opción más adecuada.

Kiro

Kiro es un entorno de desarrollo guiado por especificaciones que orienta el trabajo a través de requisitos, diseño y tareas antes de la implementación. Puede ser más adecuado si tu equipo quiere que el flujo de especificaciones esté integrado directamente en la experiencia de un IDE, en lugar de conectar Spec Kit con distintos agentes de programación.

Elige Kiro cuando:

• quieras una experiencia de producto más integrada
• quieras especificaciones, diseño y tareas en un solo entorno guiado
• tu equipo se sienta cómodo adoptando un IDE de IA específico

Tessl

Tessl apuesta con más fuerza por las especificaciones como artefactos principales. Sus materiales públicos describen especificaciones con descripciones de componentes, capacidades, pruebas vinculadas y APIs.

Elige Tessl cuando:

• quieras explorar flujos donde la especificación es la fuente principal
• te sientas cómodo con una capa metodológica más rigurosa
• el experimento principal sea generar implementaciones a partir de especificaciones estructuradas

BDD y Gherkin

BDD tiene más trayectoria, está probado y es muy útil cuando el principal riesgo es que no exista un entendimiento compartido del comportamiento del usuario. Cucumber describe BDD como una colaboración alrededor de ejemplos concretos de cómo debería comportarse el sistema.

Elige BDD cuando:

• los ejemplos importen más que la arquitectura
• QA, producto e ingeniería necesiten un lenguaje compartido
• las pruebas de aceptación ejecutables sean el artefacto principal

Ejemplo:

Feature: Invoice CSV export

  Scenario: Finance admin exports invoices for an empty month
    Given I am a finance admin
    And there are no invoices for March 2026
    When I export March invoices as CSV
    Then the CSV contains only the header row
    And the export is audit logged

Desarrollo de API contract-first

Para trabajos centrados en APIs, OpenAPI, AsyncAPI, archivos proto de gRPC y pruebas de contratos pueden ser más precisos que una especificación amplia de funcionalidad. Specmatic plantea este enfoque como una forma de convertir las especificaciones de API en contratos ejecutables y verificaciones de compatibilidad.

Elige contract-first cuando:

• la compatibilidad de la API sea el riesgo principal
• varios equipos dependan de la interfaz
• CI deba hacer cumplir el contrato automáticamente

RFC y ADR ligeros

A veces Spec Kit es demasiado.

Para un cambio interno pequeño, un RFC ligero más un registro de decisión arquitectónica pueden ser suficientes.

Elige esta opción cuando:

• la implementación sea pequeña
• haya una decisión principal
• el riesgo sea perder el registro de las decisiones arquitectónicas, no la ambigüedad de la funcionalidad

Mi recomendación por defecto

Para un equipo real que recibe muchos comentarios antes y después de la implementación, usaría este modelo de trabajo:

Before implementation:
  comment -> classify -> update spec/plan/tasks -> checklist -> analyze

During implementation:
  discovery -> classify -> flow-back if still in scope -> tests

After implementation:
  defect -> fix code/tests
  missed requirement -> update spec/plan/tasks/tests
  changed requirement -> flow-forward follow-up spec
  new capability -> new spec or issue

En otras palabras:

Do not ask "how do we answer this comment?"
Ask "which source of truth should this comment change?"

Esa sola pregunta hace que Spec Kit se sienta menos como una carpeta de archivos markdown y más como un verdadero sistema de entrega.

Vacíos que todavía veo

Spec Kit es útil, pero el ciclo de feedback todavía necesita convenciones de equipo.

Los principales vacíos que veo son:

• No hay una regla universal para la persistencia de los artefactos. La documentación deja esto intencionalmente en manos de los equipos, lo que aporta flexibilidad, pero puede confundir a quienes recién lo adoptan.
• La trazabilidad de issues y PRs sigue dependiendo principalmente de las prácticas del equipo. La comunidad ha mostrado interés en una integración más estrecha con GitHub Issues, pero los equipos no deberían esperar una automatización oficial para vincular especificaciones, issues y PRs.
• La reconciliación posterior a la implementación requiere disciplina. Spec Kit puede estructurar el flujo de trabajo, pero no puede obligar a un equipo a actualizar el artefacto correcto después de un cambio tardío en los requisitos.
• Los conjuntos grandes de comentarios necesitan facilitación. Cuando muchos stakeholders comentan, alguien todavía tiene que clasificar, eliminar duplicados y decidir qué bloquea la implementación.

La sección que agregaría en una versión futura sería un ejemplo desarrollado con un hilo real de revisión de PR, que muestre cómo cada comentario pasa a spec.md, plan.md, tasks.md, el código, las pruebas o una funcionalidad de seguimiento.

Conclusión

Spec Kit no es valioso porque crea más documentos.

Es valioso porque le da al feedback un destino específico.

Antes de la implementación, usa el feedback para precisar la especificación, el plan y la lista de tareas.

Después de la implementación, usa el feedback para decidir si el código está mal, si la especificación está incompleta, si el requisito cambió o si ya comenzó la siguiente funcionalidad.

Esa distinción marca la diferencia entre «recibimos muchos comentarios» y «mejoramos el sistema».

Lista de fuentes

Validado con estas fuentes el June 10, 2026.

Fuentes principales de Spec Kit

• README de GitHub Spec Kit
• Documentación de GitHub Spec Kit
• Guía de inicio rápido de GitHub Spec Kit
• ¿Qué es el desarrollo guiado por especificaciones?
• Modelos de persistencia de especificaciones
• Blog de GitHub: Desarrollo guiado por especificaciones con IA

Fuentes de la comunidad y alternativas

• Martin Fowler: Entender el desarrollo guiado por especificaciones: Kiro, spec-kit y Tessl
• Discusión de GitHub Spec Kit: Evolución de las especificaciones
• Issue de GitHub Spec Kit: Integración más estrecha entre GitHub Issues y las ramas creadas por Spec Kit
• Documentación de Kiro: Especificaciones
• Tessl: Desarrollo guiado por especificaciones con Tessl
• Blog de Tessl: Tessl lanza un framework y un registro guiados por especificaciones
• Cucumber: Desarrollo guiado por comportamiento
• Specmatic: Desarrollo guiado por contratos