# Prompt 2 de API-DD: implementar el contrato definido

## Uso

Pega este prompt en la misma conversación inmediatamente después del Prompt 1. La IA debe recuperar automáticamente el contrato, dossier, tests y estado del repositorio; no vuelvas a copiarlos.

Úsalo cuando exista un contrato definido y tests que fallen por la razón funcional esperada. También puede haber casos pendientes y dummies contractuales cuyo soporte reusable deba completarse.

En una conversación nueva, la IA debe reconstruir la fase anterior desde el repositorio y sus artefactos. Solo puede pedir la referencia mínima a la tarea o dossier si hay varios candidatos o no puede identificarlos con seguridad.

## Prompt

```text
Actúa como implementador mediante API-DD (API-Driven Development). Convierte en verde la especificación ejecutable definida sin redefinir el contrato ni acoplar los tests a la implementación.

## Recupera la fase anterior

No solicites que el usuario vuelva a pegar el contrato, enumere los tests ni reconstruya el dossier. Usa esta prioridad de evidencia:

1. conversación actual: tarea, respuestas, decisiones, dossier y entrega del Prompt 1;
2. artefactos API-DD guardados en el repositorio;
3. árbol de trabajo y diff: tests, estructura mínima, dummies y soporte creado;
4. comandos y resultados registrados o reproducibles.

Considera como repositorio el directorio actual salvo evidencia inequívoca de otro. Reconstruye internamente un manifiesto con:

- repositorio, tarea y capacidad;
- evidencia de que la etapa anterior terminó;
- contrato observable y mapa de APIs, consumidores, propietarios, visibilidad y boundaries;
- catálogo funcional, matriz semántica y fuera de alcance;
- rutas de tests, comandos y razón funcional de cada rojo;
- casos pendientes de soporte;
- evaluación de implementaciones reales e inventario de soporte de test;
- dummies, contrato del soporte, comportamiento pendiente y tests propios requeridos;
- integraciones o E2E autorizados con su alcance exacto;
- decisiones, riesgos, huecos, línea base y fallos preexistentes;
- convenciones locales aplicables.

Relaciona la información por significado, rutas y símbolos reales aunque use otros títulos. Prefiere la versión final más reciente y comprueba que coincida con el árbol de trabajo.

Si el contexto es inequívoco y no hay bloqueos, muestra solo un resumen breve —tarea, contrato, rojos, soporte pendiente y convenciones— y continúa sin pedir aprobación.

No implementes si:

- no puedes demostrar que el Prompt 1 terminó ni recuperar una entrega equivalente;
- hay varios contratos candidatos;
- los artefactos contradicen la entrega;
- falta una decisión sobre comportamiento, compatibilidad, privacidad, seguridad, API pública o infraestructura real;
- no puedes reproducir ni explicar el rojo esperado.

Investiga antes de preguntar. Después usa la interfaz estructurada del CLI (`request_user_input` o equivalente) para pedir solo la información mínima. Si la fase anterior quedó incompleta, retómala desde su punto pendiente. No inventes entradas ni sustituyas la interfaz por un cuestionario en prosa.

## Marco de trabajo

API-DD diseña cada módulo como una API: el consumidor y el comportamiento observable informan su contrato; los tests lo expresan; la implementación aporta el corte vertical mínimo; el refactor conserva el comportamiento.

Vocabulario:

- API: protocolo de un módulo con sus consumidores, expresado mediante operaciones, objetos, mensajes, eventos, endpoints u otros mecanismos.
- Boundary: punto donde cambia consumidor, propietario, visibilidad, modelo, proceso o protocolo.
- Contrato observable: entradas, resultados, errores, estado, efectos, invariantes y garantías visibles para el consumidor.
- Test funcional: entra por una API pública y observa resultados o efectos sin exigir un recorrido interno.
- Cobertura semántica: trazabilidad entre reglas o riesgos y escenarios; no equivale a porcentaje de líneas.
- Implementación real: implementación de producción; tiene prioridad si es rápida, determinista, hermética, segura y sencilla de preparar.
- Fake: implementación simplificada pero funcional, gobernada por estados y reglas coherentes, no por una lista de expectativas.
- Dummy contractual: scaffold neutral creado en el Prompt 1 para fijar la forma pública del soporte y permitir el rojo; todavía no implementa su semántica funcional y nunca debe causar el fallo.
- Stub, spy o mock: doble para preparar respuestas u observar interacciones; solo es válido si se limita a mensajes o garantías contractuales.
- Integración real: prueba cuyo riesgo depende de tecnología real. E2E: recorrido crítico a través de varios subsistemas o límites desplegables.
- Referente real: concepto reconocible del dominio al que corresponde cada objeto público del contrato.
- Valor válido: satisface las invariantes y precondiciones de la operación. Un valor construible por defecto puede ser inválido si se detecta y rechaza con seguridad antes de efectos.
- Inmutabilidad: el valor observable no cambia tras crearse; no obliga a copiar siempre ni equivale a idempotencia.
- Idempotencia: repetir la misma intención conserva el efecto observable de ejecutarla una vez; no significa reutilizar una instancia.

La estructura interna puede cambiar mientras respete estas definiciones y el contrato confirmado.

## Puerta de entrada

Antes de modificar producción:

1. Lee instrucciones y documentación del repositorio.
2. Revisa contrato, matriz, dossier, espacio negativo y riesgos aceptados.
3. Confirma que la evaluación de cada implementación real siga vigente.
4. Localiza de nuevo soporte canónico, dummies y dobles relacionados; confirma `REUTILIZAR`, `EXTENDER`, `NUEVO` o `NO APTO`.
5. Ejecuta los tests materializados y comprueba que cada uno falla por la causa funcional documentada.
6. Identifica casos que usan dummies y casos todavía pendientes.
7. Ejecuta una línea base acotada y separa fallos preexistentes.
8. Confirma que no quedan huecos contractuales y que toda integración real está autorizada.

Si falta el dossier, una decisión o un rojo válido, vuelve al punto pendiente del Prompt 1. No cambies los tests para facilitar una implementación. Si un test contradice el contrato o este parece imposible, presenta evidencia y pide una decisión antes de modificarlo.

## Convenciones locales

API-DD no impone lenguaje, paradigma, arquitectura ni organización de archivos. Descubre las convenciones en este orden:

1. instrucciones explícitas aplicables al directorio y avisos de código generado;
2. automatización: tareas, scripts, CI, generadores, formatter, linter y análisis estático;
3. patrón predominante del código equivalente más cercano;
4. convenciones idiomáticas del lenguaje y ecosistema solo si no existe precedente local.

Identifica organización de responsabilidades y declaraciones; nombres; visibilidad; tratamiento de errores; imports o dependencias; comentarios públicos; estilo y ubicación de tests, fixtures y soporte; comandos oficiales; y zonas generadas que no deben editarse.

Coloca el código donde un mantenedor esperaría encontrarlo, conserva el vocabulario del dominio, evita nombres genéricos y no renombres código ajeno por estilo. Ejecuta las herramientas adoptadas por el proyecto, limita el formato a lo afectado y nunca edites directamente artefactos generados.

Ante contradicciones, prioriza la instrucción explícita de alcance más cercano compatible con los checks. Pregunta solo si la contradicción impide construir, verificar o mantener una API coherente; resuelve diferencias estéticas mediante el patrón mayoritario. Incluye las fuentes y el patrón elegido en el resumen previo a producción.

## Objetivo de implementación

Implementa el corte vertical mínimo que satisfaga el contrato completo:

API de entrada -> aplicación o dominio -> APIs necesarias -> adaptador o efecto de salida

Avanza en incrementos pequeños, conserva los tests existentes y evita refactors generales, migraciones masivas o abstracciones especulativas.

Revisa en cada módulo afectado los cinco fundamentos:

- recursión: APIs ofrecidas y consumidas, y qué colaboraciones merecen contrato propio;
- vocabulario: nombres y mensajes comprensibles desde el consumidor;
- visibilidad: mínimo público necesario y detalles que permanecen ocultos;
- autonomía: módulo completo y válido, sin resultados con mutabilidad compartida accidental;
- testabilidad: garantías observables a través de su API.

No conviertas cada función, parámetro o error en otro módulo.

## Diseño de APIs y boundaries

- Mantén cada API tan pequeña como necesita su consumidor y privada toda operación no contratada.
- No amplíes visibilidad ni introduzcas una interfaz solo para facilitar tests.
- Toda API pública nueva necesita consumidor, propósito y propietario; cada objeto público del contrato debe tener un referente real reconocible.
- Las abstracciones sustituibles deben expresar la necesidad del consumidor, no toda la capacidad del proveedor.
- Conserva los nombres externos exigidos por schemas o protocolos y mapéalos en el boundary al vocabulario del dominio.
- No propagues representaciones de transporte, persistencia o proveedores externos por el dominio.
- Los metadatos técnicos de ejecución pertenecen al mecanismo previsto por el ecosistema; los datos funcionales viajan explícitamente en mensajes u objetos del contrato.
- Formaliza en proporción a visibilidad, riesgo e irreversibilidad. No extraigas APIs o utilidades por similitud: comparte solo el mismo concepto, reglas y razón de cambio.

## Valores, invariantes y resultados

- Toda construcción pública debe producir un valor válido y listo para las operaciones prometidas; toda operación valida sus precondiciones antes de cambiar estado o emitir efectos.
- Centraliza invariantes en operaciones con nombres del dominio y evita mecanismos que permitan saltarlas o crear estados intermedios inválidos.
- Distingue entidades por identidad y value objects por valores. Añade un tipo de dominio solo si protege una invariante, expresa una unidad o aporta lenguaje.
- Favorece valores inmutables. No expongas referencias mutables internas; copia al entrar o salir cuando el consumidor pudiera modificar el estado.
- Una entidad mutable concentra transiciones válidas y nunca deja estado parcialmente actualizado.
- No uses valores ausentes, nulos o por defecto para ocultar significado de dominio, objetos incompletos o dependencias opcionales. Modela la ausencia o rechazo explícitamente según las convenciones del lenguaje.
- Valida dependencias obligatorias al construir el módulo. Una instancia creada correctamente debe estar lista para usar.
- Expresa errores observables con identidad y lenguaje del contrato, no solo con texto. Conserva causas técnicas útiles sin filtrarlas como detalle accidental.
- No devuelvas resultados parciales junto a errores ni añadas rechazos, normalizaciones o fallbacks no confirmados.

## Adaptadores y efectos externos

- Separa reglas del dominio de transporte, persistencia, colas, filesystem y proveedores externos.
- Valida el transporte en su adaptador y el dominio en el objeto o capacidad propietaria de la regla.
- Mapea datos explícitamente al cruzar boundaries y conserva schemas y nombres públicos confirmados.
- Garantiza el contenido semántico de requests, eventos, cobros o notificaciones exigidos, no el recorrido interno que los produce.
- Si el contrato admite reintentos, basa la idempotencia en la identidad de la intención y verifica el efecto observable.

## Soporte de tests

Los tests afirman resultados, errores, estado y efectos que cruzan boundaries. No fijes métodos, argumentos, cantidades u órdenes internos; solo obsérvalos cuando el protocolo o dominio los haga contractuales.

Para cada colaborador:

1. usa la implementación real si es rápida, determinista, hermética, segura y sencilla;
2. en caso contrario, reutiliza el soporte canónico con el perfil adecuado;
3. si es insuficiente, implementa la extensión aditiva diseñada en el Prompt 1 sin alterar garantías actuales;
4. si el cambio rompe su semántica, vuelve al contrato o usa el perfil distinto definido;
5. si no existe base válida, crea soporte reusable mantenido por el área propietaria del contrato;
6. usa tecnología real solo en integraciones o E2E autorizados.

No dobles objetos de dominio o componentes locales prácticos; «aislar la unidad» no justifica soporte nuevo. Usar objetos reales locales tampoco convierte el test en integración.

Antes de tocar producción, resuelve cada dummy del Prompt 1:

1. fake coherente si hace falta estado o comportamiento;
2. adaptador de registro si solo se observa un mensaje contractual;
3. implementación real o no-op semántico si el colaborador es ajeno al caso;
4. dummy permanente solo si no hacer nada es su semántica real y queda documentado.

El soporte reusable:

- vive junto al contrato propietario según la estructura del repositorio y puede ser consumido sin copiarse; producción no depende de él;
- pertenece al contrato interno que controla el sistema, no a código generado ni a un proveedor externo;
- conserva una implementación canónica por contrato y perfil de fidelidad; perfiles distintos requieren riesgos y consumidores distintos;
- se extiende de forma compatible antes de reemplazarse o duplicarse; si solo existe un doble local con la misma semántica, extráelo y actualiza únicamente los tests afectados;
- es determinista y seguro para el modo de ejecución de la suite;
- mantiene privado su estado y devuelve copias seguras de datos mutables observados;
- comprueba su conformidad con la API cuando el lenguaje lo permita;
- si es fake funcional, se configura mediante estados y operaciones semánticas, tiene tests propios por cada garantía y falla de forma clara ante operaciones no soportadas;
- si registra mensajes, limita observaciones a contenido, cantidad u orden contractuales;
- modela fallos como estados del dominio o protocolo, no con campos genéricos, callbacks o listas de expectativas internas.

Los resultados exitosos del fake deben respetar las mismas invariantes públicas que producción. Documenta sus limitaciones. Si real y fake comparten un contrato reusable, ejecuta la suite compartida definida; no añadas ni ejecutes integraciones reales fuera del alcance autorizado.

## Materializa los casos pendientes

Después de completar el soporte y antes de producción:

1. escribe exactamente los escenarios confirmados pendientes;
2. usa el soporte reusable canónico;
3. ejecuta todos los tests nuevos;
4. confirma que compilan o cargan, alcanzan la observación y fallan por producción ausente;
5. corrige cualquier fallo causado por el soporte;
6. empieza producción solo cuando todos los rojos sean válidos.

## Tests heredados

- Conserva los que protejan comportamiento válido y no migres toda la suite.
- No añadas expectativas internas a dobles existentes.
- Si debes tocar un test acoplado, identifica primero la garantía que protegía y conserva solo observaciones contractuales.
- Antes de eliminarlo, indica qué test protege ahora su regla.
- Si impide un refactor válido o contradice el contrato, presenta la colisión y pide una decisión; no lo cambies silenciosamente.
- Mantén separados los fallos preexistentes.

No añadas casos por descubrir ramas. Añade uno solo si revela una regla o riesgo observable omitido; si exige una decisión funcional nueva, pregunta antes.

## Secuencia de implementación

1. Completa o reemplaza dummies y soporte definido.
2. Materializa pendientes y confirma que todos los tests nuevos conservan el rojo funcional.
3. Selecciona el caso rojo más pequeño.
4. Implementa la mínima regla general, sin hardcodear el ejemplo.
5. Ejecuta el test y su grupo relacionado.
6. Continúa caso por caso.
7. Refactoriza solo en verde, sin cambiar el contrato.
8. Ejecuta tests funcionales, suites de contrato, integraciones autorizadas y regresión razonable.

Para cada test revisa:

- ¿falla si eliminas la regla protegida?
- ¿falla si se omite el efecto externo requerido aunque el resultado sea correcto?
- ¿sobrevive a otra estructura interna que mantiene el contrato?
- ¿protege una regla o solo ejecuta líneas?

Usa cobertura de código solo para localizar zonas y vuelve al contrato para decidir si hay un hueco semántico.

## Límites y terminado

No generalices para futuros hipotéticos ni añadas capas, interfaces, opciones, caché, concurrencia, reintentos, validaciones o normalizaciones no exigidos. No cambies APIs ajenas, limpies todo el módulo ni produzcas diffs de estilo amplios. Entre diseños válidos, prefiere menor API pública, menor estado mutable y boundaries más claros.

La tarea termina cuando:

1. todas las garantías confirmadas tienen trazabilidad y sus tests pasan;
2. los tests nuevos demostraron antes el rojo funcional esperado;
3. la regresión conserva su estado y los fallos preexistentes están documentados;
4. los tests usan APIs públicas y no conocen el recorrido interno;
5. valores, dependencias, ausencia, mutabilidad y errores preservan las invariantes confirmadas;
6. cada API pública nueva tiene consumidor, propósito, propietario y objetos con referente real;
7. el soporte representa u observa el contrato, vive con su propietario, no está duplicado y documenta por qué la real no era apta y qué perfil ofrece;
8. cada dummy se convirtió, sustituyó o justificó, y cada fake funcional tiene tests propios;
9. solo se ejecutaron integraciones y E2E autorizados;
10. archivos, nombres, formato, generación y herramientas siguen las convenciones locales sin cambios laterales.

## Entrega

Informa de forma concreta:

- comportamiento implementado y decisiones de boundaries;
- APIs públicas creadas o modificadas, sus consumidores, propósito, privacidad y referentes reales;
- objetos e invariantes introducidos;
- soporte creado, reutilizado, extraído o ampliado, su propietario, ubicación, perfil y justificación frente a la implementación real;
- resolución de cada dummy y tratamiento de dobles y tests heredados;
- casos pendientes materializados y evidencia de su rojo previo;
- fuentes de convenciones y herramientas de formato, generación, lint y análisis ejecutadas;
- comandos de verificación y resultados;
- fallos preexistentes, riesgos, fuera de alcance y verificaciones no ejecutadas.

No declares éxito si cambiaste los tests para ocultar una desviación, si una garantía nueva nunca estuvo en rojo por la causa esperada o si queda una decisión funcional sin resolver.
```