Receta: Corrección de Bug con SDD

Esta receta muestra cómo usar SpecForge para documentar, acotar y resolver un bug de una forma que crea una spec duradera — para que la misma clase de bug nunca vuelva a producción.

¿Por Qué Documentar Bugs como Specs?

La mayoría de los bugs recurren porque el comportamiento correcto nunca fue especificado formalmente. Corregir un bug sin una spec significa:

• La corrección no tiene criterios de aceptación (¿cómo sabes que está arreglado?)
• El test de regresión no tiene trazabilidad
• El mismo patrón puede reaparecer en código relacionado

SDD trata los bugs como specs faltantes o incorrectas. Corregir el bug significa escribir la spec que debería haber existido, y luego implementar para que coincida con ella.

---

Escenario

Los usuarios reportan que hacer dos pedidos simultáneamente resulta a veces en cargos duplicados. Este es un bug de concurrencia en el flujo de creación de pedidos.

---

Paso 1 — Clarificar el Bug

Prompt:

Use specforge to clarify requirements for a bug fix:
duplicate charges when placing simultaneous orders in project proj_abc123

O en español:

Usa specforge para clarificar los requisitos de una corrección de bug:
cargos duplicados al hacer pedidos simultáneos en el proyecto proj_abc123

SpecForge preguntará:

• ¿Dónde ocurre la duplicación — capa API, procesador de pagos o BD?
• ¿Es reproducible en condiciones específicas (carga, retraso de red)?
• ¿Cuál es el comportamiento esperado — exactamente un cargo por pedido, siempre?
• ¿Existen tests que deberían haber detectado esto?

---

Paso 2 — Crear la Spec del Bug Fix

Prompt:

Create a spec for fixing duplicate charge bug in order placement for project proj_abc123.
Root cause: race condition in OrderService.placeOrder — no idempotency key on Stripe call.
Expected: exactly one charge per order regardless of concurrent requests.

Qué contendrá la spec:

## Criterios de Aceptación

1. Hacer el mismo pedido dos veces concurrentemente resulta en exactamente un cargo de Stripe
2. La segunda solicitud concurrente recibe una respuesta 409 Conflict con el ID del pedido
3. La idempotency key se deriva del orderId y se almacena en la tabla de pedidos
4. Los pedidos existentes no pueden modificarse después de que se inicia el pago
5. El test de integración cubre la creación simultánea de pedidos con 10 solicitudes simultáneas
6. El test unitario cubre los casos borde de generación de idempotency key (UUID v4, resistencia a colisiones)

---

Paso 3 — Hacer Challenge del Diseño de la Corrección

Prompt:

Challenge spec SPEC-BUG-001 for project proj_abc123

SpecForge indagará en:

• ¿Qué pasa si la generación de la idempotency key misma tiene una race condition?
• ¿Qué pasa si la primera solicitud falla a mitad de vuelo — tiene éxito la segunda?
• ¿Cuál es la política de expiración de las idempotency keys?
• ¿Maneja la corrección el caso en que el pago tiene éxito pero el write a la BD falla?

---

Paso 4 — Verificación de Seguridad

Prompt:

Run a security check on spec SPEC-BUG-001 for project proj_abc123

Los bugs de pagos concurrentes a menudo tienen implicaciones de seguridad — asegúrate de que la corrección no introduzca una vulnerabilidad TOCTOU.

---

Paso 5 — Ingeniería Inversa del Código Existente

Documenta lo que hace actualmente el código (roto):

Prompt:

Reverse engineer the code at /Users/me/my-app/src/orders/OrderService.ts for project proj_abc123

Esto crea una spec del comportamiento actual — útil para entender exactamente dónde divergieron la spec y la implementación.

---

Paso 6 — Generar Tests Primero (enfoque TDD)

Prompt:

Generate tests for spec SPEC-BUG-001 in project proj_abc123

Escribe los tests de regresión antes de tocar la implementación. Esto garantiza:

• El bug es reproducible con un test (rojo)
• La corrección hace pasar el test (verde)
• El test queda en el suite para siempre (protección de regresión)

---

Paso 7 — Generar Plan de Ejecución

Prompt:

Generate an execution plan for spec SPEC-BUG-001 in project proj_abc123

Para una corrección de bug, el plan típicamente se ve así:

## Fase 1: Reproducir
- [ ] Escribir test de integración fallando que dispara el cargo duplicado (RED)
- [ ] Confirmar que el test falla contra la implementación actual

## Fase 2: Corregir
- [ ] Agregar columna idempotency_key a la tabla de pedidos (migración)
- [ ] Generar idempotency key en OrderService antes de la llamada a Stripe
- [ ] Almacenar la key atómicamente con la creación del pedido (transacción)
- [ ] Manejar 409 del endpoint de idempotencia de Stripe

## Fase 3: Verificar
- [ ] Ejecutar test de integración (GREEN)
- [ ] Ejecutar suite completa de tests
- [ ] Test manual con solicitudes concurrentes en modo test de Stripe

---

Paso 8 — Implementar y Validar

Después de implementar la corrección:

Prompt:

Validate spec SPEC-BUG-001 against the code at /Users/me/my-app/src for project proj_abc123

Asegúrate de que los 6 criterios de aceptación estén cubiertos por la implementación y los tests.

---

Paso 9 — Detectar Drift desde la Spec Original

Si existe un SPEC para el flujo de creación de pedidos, verifica si la corrección introdujo drift:

Prompt:

Detect drift in spec SPEC-002 (order placement) for project proj_abc123

La corrección puede necesitar reflejarse en la spec original como un nuevo criterio: "El sistema debe usar idempotency keys para todas las llamadas a la API de Stripe."

---

Paso 10 — Capturar el Aprendizaje

Prompt:

Capture learning: payment provider API calls must always include idempotency keys derived from the business entity ID, never from request-generated UUIDs

Este patrón ahora está almacenado e influirá en specs futuras que involucren llamadas a APIs de pago.

---

Resultado de Esta Receta

Al final:

• Una spec de bug fix (SPEC-BUG-001) con criterios de aceptación completos
• Tests de regresión con trazabilidad a cada criterio
• La spec original actualizada para reflejar el comportamiento correcto
• Un aprendizaje capturado que previene que el patrón recurra
• Un rastro de auditoría: cuándo se encontró el bug, cuál fue la corrección, por qué fue la corrección correcta