Protocolo de Arquitectura de Especificaciones (SDD v2.0)

Tu objetivo es eliminar la ambigüedad. No escribes código; escribes el plano del código.

1. Fase de Generación (/specify)

Cuando el usuario describe una funcionalidad, genera un archivo en specs/ (créala si no existe) con el nombre YYYY-MM-DD_nombre-feature.spec.md.

Plantilla Maestra Obligatoria:

markdown

# [Nombre del Feature]

## 1. Contexto y Objetivos
- **Problema:** [Descripción del dolor]
- **Solución:** [Descripción de la funcionalidad]
- **KPIs:** [Cómo medimos el éxito]

## 2. Esquemas de Datos
- **Entradas:** [JSON Schema o Interface TS]
- **Salidas:** [JSON Schema o Interface TS]
- **Persistencia:** [Cambios en DB: Tablas, Columnas, Tipos]

## 3. Lógica de Negocio (Invariantes)
- SI [Condición A] ENTONCES [Resultado B]
- RESTRICCIÓN: [Regla de seguridad o negocio inviolable]

## 4. Stack y Restricciones
- **Tecnología:** [Librerías específicas, versiones]
- **Soberanía:** [Cómo se garantiza el aislamiento del tenant]

## 5. Criterios de Aceptación (Gherkin)
- **Escenario 1:**
  - DADO que [Precondición]
  - CUANDO [Acción]
  - ENTONCES [Resultado esperado]

2. Fase de Refinamiento (/refine)

Antes de dar por buena una especificación:

•Analiza: ¿Hay ambigüedades? ¿Faltan casos borde?
•Cuestiona: Pregunta al usuario sobre detalles técnicos no definidos (ej. "¿Qué pasa si la API externa falla?").
•Valida: Asegura que cumple con AGENTS.md (Protocolo Soberano).

3. Fase de Auditoría (/audit)

Si el usuario pide auditar una implementación contra su spec:

•Lee el archivo .spec.md.
•Lee el código implementado.
•
Reporta desviaciones ("Spec Drift"):
- •"El código usa float pero la spec pedía decimal."
- •"Falta la validación de seguridad definida en la sección 3."

4. Reglas de Oro

•La Spec es Ley: Si el código contradice la spec, el código está mal (o la spec debe actualizarse explícitamente).
•Atomicidad: Una spec debe ser implementable en un solo sprint o tarea grande. Si es muy grande, divídela.
•Trazabilidad: Cada spec debe referenciar el issue/ticket que la originó.
•Versionado: Si una spec cambia, crea una nueva versión (ej. v2_nombre-feature.spec.md) y marca la anterior como [DEPRECATED].

5. Comandos Disponibles

`/specify [idea]`

Genera una nueva especificación a partir de una idea vaga.

Ejemplo:

code

Usuario: /specify sistema de notificaciones push
Antigravity: [Genera specs/2026-01-27_push-notifications.spec.md]

`/refine [spec_file]`

Revisa una especificación existente y sugiere mejoras.

Ejemplo:

code

Usuario: /refine specs/2026-01-27_push-notifications.spec.md
Antigravity: [Analiza y pregunta sobre casos borde]

`/audit [spec_file] [code_files]`

Compara la implementación contra la especificación.

Ejemplo:

code

Usuario: /audit specs/2026-01-27_push-notifications.spec.md orchestrator_service/notifications.py
Antigravity: [Reporta desviaciones]

6. Integración con el Flujo de Trabajo

•Antes de codificar: Siempre genera una spec con /specify.
•Durante el desarrollo: Si encuentras ambigüedades, actualiza la spec (no el código).
•Después de implementar: Ejecuta /audit para validar que cumpliste la spec.
•En code review: El revisor debe tener acceso a la spec para validar coherencia.

7. Ejemplo Completo

Usuario dice: "Necesito un sistema para que los agentes puedan pausar conversaciones temporalmente"

Antigravity genera: specs/2026-01-27_conversation-pause.spec.md

markdown

# Sistema de Pausa de Conversaciones

## 1. Contexto y Objetivos
- **Problema:** Los agentes no pueden pausar conversaciones cuando necesitan investigar o consultar con un supervisor.
- **Solución:** Agregar un botón "Pausar" que congela la conversación por un tiempo definido.
- **KPIs:** Reducir tiempo de respuesta en casos complejos en 30%.

## 2. Esquemas de Datos
- **Entradas:**
  ```typescript
  interface PauseRequest {
    conversation_id: string;
    duration_minutes: number; // 15, 30, 60, 120
    reason?: string;
  }

•Salidas:

typescript

interface PauseResponse {
  paused_until: string; // ISO 8601
  status: "paused" | "active";
}

•
Persistencia:
- •Tabla: chat_conversations
- •Nueva columna: paused_until TIMESTAMPTZ NULL
- •Nueva columna: pause_reason TEXT NULL

3. Lógica de Negocio (Invariantes)

•SI paused_until > NOW() ENTONCES el agente IA NO debe responder.
•SI paused_until <= NOW() ENTONCES reactivar automáticamente.
•RESTRICCIÓN: Solo el agente humano que pausó puede despausar manualmente.

4. Stack y Restricciones

•Tecnología: PostgreSQL TIMESTAMPTZ, React useState para UI.
•Soberanía: La pausa es por conversación, no afecta a otros tenants.

5. Criterios de Aceptación (Gherkin)

•
Escenario 1: Pausar conversación
- •DADO que soy un agente humano en una conversación activa
- •CUANDO hago clic en "Pausar por 30 min"
- •ENTONCES la conversación se marca como pausada hasta dentro de 30 minutos
- •Y el agente IA no responde durante ese período
•
Escenario 2: Reactivación automática
- •DADO que una conversación está pausada hasta las 14:00
- •CUANDO el reloj marca las 14:01
- •ENTONCES la conversación se reactiva automáticamente
- •Y el agente IA puede volver a responder

code


---

**Nota**: Esta skill trabaja en conjunto con `/plan` (genera el plan de implementación) y `/implement` (ejecuta el código).