eva4j 1.0.16 → 1.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. package/AGENTS.md +220 -5
  2. package/DOMAIN_YAML_GUIDE.md +188 -3
  3. package/FUTURE_FEATURES.md +33 -52
  4. package/QUICK_REFERENCE.md +8 -4
  5. package/bin/eva4j.js +70 -2
  6. package/config/defaults.json +1 -0
  7. package/docs/CAMUNDA_DMN_GUIDE.md +1380 -0
  8. package/docs/KAFKA_PRODUCTION_CONFIG.md +441 -0
  9. package/docs/RABBITMQ_PRODUCTION_CONFIG.md +227 -0
  10. package/docs/commands/ADD_RABBITMQ_CLIENT.md +192 -0
  11. package/docs/commands/EVALUATE_SYSTEM.md +290 -10
  12. package/docs/commands/GENERATE_RABBITMQ_EVENT.md +341 -0
  13. package/docs/commands/GENERATE_RABBITMQ_LISTENER.md +595 -0
  14. package/docs/commands/GENERATE_TEMPORAL_FLOW.md +52 -12
  15. package/docs/commands/INDEX.md +27 -3
  16. package/docs/prototype/TEMPORAL_COMMUNICATION_PATTERNS.md +731 -0
  17. package/docs/prototype/TEMPORAL_DESIGN_METHODOLOGY.md +740 -0
  18. package/docs/prototype/system/RISKS.md +277 -0
  19. package/docs/prototype/system/customers.yaml +133 -0
  20. package/docs/prototype/system/inventory.yaml +109 -0
  21. package/docs/prototype/system/notifications.yaml +131 -0
  22. package/docs/prototype/system/orders.yaml +241 -0
  23. package/docs/prototype/system/payments.yaml +256 -0
  24. package/docs/prototype/system/products.yaml +168 -0
  25. package/docs/prototype/system/system.yaml +269 -0
  26. package/examples/domain-endpoints-multi-aggregate.yaml +140 -0
  27. package/examples/domain-events.yaml +26 -0
  28. package/examples/domain-read-models.yaml +113 -0
  29. package/examples/system/customer.yaml +89 -0
  30. package/examples/system/orders.yaml +119 -0
  31. package/examples/system/product.yaml +27 -0
  32. package/examples/system/system.yaml +80 -0
  33. package/package.json +1 -1
  34. package/read-model-spec.md +664 -0
  35. package/src/agents/design-gap-analyst-temporal.agent.md +452 -0
  36. package/src/agents/design-gap-analyst.agent.md +383 -0
  37. package/src/agents/design-reviewer-temporal.agent.md +412 -0
  38. package/src/agents/design-reviewer.agent.md +34 -5
  39. package/src/agents/implement-use-cases.prompt.md +179 -0
  40. package/src/agents/ux-gap-analyst.agent.md +412 -0
  41. package/src/commands/add-rabbitmq-client.js +261 -0
  42. package/src/commands/add-temporal-client.js +22 -2
  43. package/src/commands/build.js +267 -11
  44. package/src/commands/evaluate-system.js +700 -13
  45. package/src/commands/generate-entities.js +560 -24
  46. package/src/commands/generate-http-exchange.js +3 -0
  47. package/src/commands/generate-kafka-event.js +3 -0
  48. package/src/commands/generate-kafka-listener.js +3 -0
  49. package/src/commands/generate-rabbitmq-event.js +665 -0
  50. package/src/commands/generate-rabbitmq-listener.js +205 -0
  51. package/src/commands/generate-record.js +2 -2
  52. package/src/commands/generate-resource.js +4 -1
  53. package/src/commands/generate-temporal-activity.js +970 -33
  54. package/src/commands/generate-temporal-flow.js +98 -38
  55. package/src/commands/generate-temporal-system.js +708 -0
  56. package/src/commands/generate-usecase.js +4 -1
  57. package/src/skills/build-system-yaml/SKILL.md +343 -2
  58. package/src/skills/build-system-yaml/references/domain-yaml-spec.md +253 -26
  59. package/src/skills/build-system-yaml/references/module-spec.md +90 -9
  60. package/src/skills/build-system-yaml/references/system-yaml-spec.md +36 -0
  61. package/src/skills/build-temporal-system/SKILL.md +752 -0
  62. package/src/skills/build-temporal-system/references/temporal-communication-patterns.md +167 -0
  63. package/src/skills/build-temporal-system/references/temporal-domain-yaml-spec.md +449 -0
  64. package/src/skills/build-temporal-system/references/temporal-module-spec.md +353 -0
  65. package/src/skills/build-temporal-system/references/temporal-system-yaml-spec.md +326 -0
  66. package/src/skills/implement-use-case/SKILL.md +350 -0
  67. package/src/skills/implement-use-case/references/use-case-patterns.md +980 -0
  68. package/src/skills/requirements-elicitation/SKILL.md +228 -0
  69. package/src/skills/requirements-elicitation/references/interview-framework.md +260 -0
  70. package/src/skills/requirements-elicitation/references/output-templates.md +368 -0
  71. package/src/utils/bounded-context-diagram.js +844 -0
  72. package/src/utils/config-manager.js +4 -2
  73. package/src/utils/domain-validator.js +495 -17
  74. package/src/utils/naming.js +20 -0
  75. package/src/utils/system-validator.js +169 -11
  76. package/src/utils/system-yaml-parser.js +318 -0
  77. package/src/utils/temporal-validator.js +497 -0
  78. package/src/utils/validator.js +3 -1
  79. package/src/utils/yaml-to-entity.js +281 -9
  80. package/templates/aggregate/AggregateRepository.java.ejs +4 -0
  81. package/templates/aggregate/AggregateRepositoryImpl.java.ejs +8 -0
  82. package/templates/aggregate/AggregateRoot.java.ejs +38 -4
  83. package/templates/aggregate/DomainEventHandler.java.ejs +116 -22
  84. package/templates/aggregate/JpaAggregateRoot.java.ejs +4 -4
  85. package/templates/aggregate/JpaEntity.java.ejs +2 -2
  86. package/templates/base/docker/rabbitmq-services.yaml.ejs +12 -0
  87. package/templates/base/resources/parameters/develop/kafka.yaml.ejs +5 -0
  88. package/templates/base/resources/parameters/develop/rabbitmq.yaml.ejs +15 -0
  89. package/templates/base/resources/parameters/develop/temporal.yaml.ejs +0 -3
  90. package/templates/base/resources/parameters/local/kafka.yaml.ejs +5 -0
  91. package/templates/base/resources/parameters/local/rabbitmq.yaml.ejs +15 -0
  92. package/templates/base/resources/parameters/local/temporal.yaml.ejs +0 -3
  93. package/templates/base/resources/parameters/production/kafka.yaml.ejs +39 -8
  94. package/templates/base/resources/parameters/production/rabbitmq.yaml.ejs +32 -0
  95. package/templates/base/resources/parameters/production/temporal.yaml.ejs +0 -3
  96. package/templates/base/resources/parameters/test/kafka.yaml.ejs +12 -6
  97. package/templates/base/resources/parameters/test/rabbitmq.yaml.ejs +15 -0
  98. package/templates/base/resources/parameters/test/temporal.yaml.ejs +0 -3
  99. package/templates/base/root/AGENTS.md.ejs +1 -1
  100. package/templates/crud/DeleteCommandHandler.java.ejs +19 -1
  101. package/templates/crud/EndpointsController.java.ejs +1 -1
  102. package/templates/crud/ScaffoldCommand.java.ejs +5 -2
  103. package/templates/crud/ScaffoldCommandHandler.java.ejs +3 -1
  104. package/templates/crud/ScaffoldQuery.java.ejs +5 -2
  105. package/templates/crud/ScaffoldQueryHandler.java.ejs +3 -1
  106. package/templates/crud/SubEntityRemoveCommand.java.ejs +1 -1
  107. package/templates/crud/UpdateCommandHandler.java.ejs +53 -2
  108. package/templates/evaluate/report.html.ejs +1447 -90
  109. package/templates/kafka-event/KafkaConfigBean.java.ejs +1 -1
  110. package/templates/kafka-event/KafkaMessageBroker.java.ejs +3 -3
  111. package/templates/ports/PortAclMapper.java.ejs +35 -0
  112. package/templates/ports/PortFeignAdapter.java.ejs +7 -22
  113. package/templates/ports/PortFeignClient.java.ejs +4 -0
  114. package/templates/ports/PortResponseDto.java.ejs +1 -1
  115. package/templates/rabbitmq-event/RabbitConfigBean.java.ejs +33 -0
  116. package/templates/rabbitmq-event/RabbitConfigExchange.java.ejs +12 -0
  117. package/templates/rabbitmq-event/RabbitMessageBroker.java.ejs +35 -0
  118. package/templates/rabbitmq-event/RabbitMessageBrokerMethod.java.ejs +9 -0
  119. package/templates/rabbitmq-listener/RabbitConfigConsumerBean.java.ejs +33 -0
  120. package/templates/rabbitmq-listener/RabbitConfigConsumerExchange.java.ejs +12 -0
  121. package/templates/rabbitmq-listener/RabbitListenerClass.java.ejs +82 -0
  122. package/templates/rabbitmq-listener/RabbitListenerSimple.java.ejs +56 -0
  123. package/templates/read-model/ReadModelDomain.java.ejs +46 -0
  124. package/templates/read-model/ReadModelJpa.java.ejs +58 -0
  125. package/templates/read-model/ReadModelJpaRepository.java.ejs +13 -0
  126. package/templates/read-model/ReadModelKafkaListener.java.ejs +64 -0
  127. package/templates/read-model/ReadModelRabbitListener.java.ejs +71 -0
  128. package/templates/read-model/ReadModelRepository.java.ejs +42 -0
  129. package/templates/read-model/ReadModelRepositoryImpl.java.ejs +85 -0
  130. package/templates/read-model/ReadModelSyncHandler.java.ejs +54 -0
  131. package/templates/shared/configurations/kafkaConfig/KafkaConfig.java.ejs +18 -4
  132. package/templates/shared/configurations/rabbitmqConfig/RabbitMQConfig.java.ejs +100 -0
  133. package/templates/shared/configurations/temporalConfig/TemporalConfig.java.ejs +2 -64
  134. package/templates/shared/configurations/temporalConfig/TemporalWorkerFactoryLifecycle.java.ejs +41 -0
  135. package/templates/temporal-activity/ActivityImpl.java.ejs +68 -2
  136. package/templates/temporal-activity/ActivityInput.java.ejs +14 -0
  137. package/templates/temporal-activity/ActivityInterface.java.ejs +7 -1
  138. package/templates/temporal-activity/ActivityOutput.java.ejs +14 -0
  139. package/templates/temporal-activity/NestedType.java.ejs +12 -0
  140. package/templates/temporal-activity/SharedActivityInput.java.ejs +14 -0
  141. package/templates/temporal-activity/SharedActivityInterface.java.ejs +15 -0
  142. package/templates/temporal-activity/SharedActivityOutput.java.ejs +14 -0
  143. package/templates/temporal-activity/SharedNestedType.java.ejs +12 -0
  144. package/templates/temporal-flow/ModuleHeavyActivity.java.ejs +6 -0
  145. package/templates/temporal-flow/ModuleLightActivity.java.ejs +6 -0
  146. package/templates/temporal-flow/ModuleTemporalWorkerConfig.java.ejs +58 -0
  147. package/templates/temporal-flow/WorkFlowImpl.java.ejs +172 -12
  148. package/templates/temporal-flow/WorkFlowInput.java.ejs +11 -0
  149. package/templates/temporal-flow/WorkFlowInterface.java.ejs +5 -4
  150. package/templates/temporal-flow/WorkFlowService.java.ejs +42 -12
  151. package/COMMAND_EVALUATION.md +0 -911
@@ -0,0 +1,228 @@
1
+ ---
2
+ name: requirements-elicitation
3
+ description: "Transformar una idea vaga de producto en requisitos funcionales robustos y estructurados para diseño de sistemas. USE FOR: cuando el usuario tiene una idea de negocio, startup, feature o producto y necesita convertirla en especificación funcional clara antes de diseñar la arquitectura; cuando se dice 'quiero construir un sistema para...', 'tengo una idea de una app que...', 'necesito un sistema que gestione...', 'cómo empiezo a diseñar...'. PRODUCES: USER_FLOWS.md, VALIDATION_FLOWS.md y FUNCTIONAL_REQUIREMENTS.md listos para usar como entrada de build-system-yaml o build-temporal-system. Este skill SIEMPRE debe ejecutarse antes de build-system-yaml cuando el input es una descripción informal o una idea de negocio sin estructurar."
4
+ ---
5
+
6
+ # Requirements Elicitation Skill
7
+
8
+ Eres un **Consultor Senior de Producto** combinado con un **Analista de Negocio DDD experto**. Tu misión es convertir una idea vaga en requisitos funcionales estructurados y robustos que alimenten directamente a los skills de diseño de sistemas.
9
+
10
+ No eres técnico en esta fase — eres un experto que hace las preguntas correctas para descubrir lo que el negocio realmente necesita, cómo funcionan sus procesos, y cuáles son sus reglas críticas.
11
+
12
+ ---
13
+
14
+ ## Principios Fundamentales
15
+
16
+ **Escucha activa, no suposiciones.** Cuando algo es ambiguo, pregunta. Dos negocios del mismo sector pueden tener reglas radicalmente diferentes. Nunca inventes reglas de negocio.
17
+
18
+ **Descubrimiento progresivo.** No lances 20 preguntas de una vez. Cada ronda de 3–5 preguntas debe desbloquear entendimiento suficiente para la siguiente. El usuario debe sentir que avanza, no que llena un formulario.
19
+
20
+ **Enfoque en flujos, no en datos.** Los campos y estructuras de datos emergen solos cuando entiendes bien los flujos. Prioriza entender qué hace el sistema *en el tiempo* — qué desencadena qué, qué estados existen, qué puede salir mal.
21
+
22
+ **Cuestionamiento constructivo.** Si algo no tiene sentido de negocio, dilo amablemente y propón alternativas. El usuario puede saber mucho de su negocio pero poco de cómo modelar sistemas. Tu rol es el de socio, no transcriptor.
23
+
24
+ ---
25
+
26
+ ## Fases de Ejecución
27
+
28
+ ```
29
+ FASE 1 — ANÁLISIS INICIAL (silencioso, < 30 segundos)
30
+ Leer lo que el usuario ya dijo → identificar dominio → preparar preguntas
31
+
32
+ FASE 2 — ENTREVISTA DE NEGOCIO (interactivo, múltiples rondas)
33
+ Actores → Flujos principales → Reglas → Casos de borde → Integraciones
34
+
35
+ FASE 3 — SÍNTESIS Y VALIDACIÓN (interactivo, 1 ronda)
36
+ Presentar resumen estructurado → validar con el usuario
37
+
38
+ FASE 4 — GENERACIÓN DE ARTEFACTOS (automático)
39
+ Crear archivos en system/ → Indicar siguiente skill a usar
40
+ ```
41
+
42
+ ---
43
+
44
+ ## Fase 1 — Análisis Inicial (Silencioso)
45
+
46
+ Antes de hacer ninguna pregunta, analiza internamente lo que el usuario ya describió:
47
+
48
+ 1. **Dominio identificado** — ¿E-commerce? ¿Salud? ¿Logística? ¿Fintech? ¿B2B SaaS?
49
+ 2. **Actores mencionados** — ¿Quiénes interactúan con el sistema? (explícitos o implícitos)
50
+ 3. **Procesos clave detectados** — ¿Qué verbos de negocio aparecen? (comprar, reservar, aprobar, gestionar...)
51
+ 4. **Incógnitas críticas** — ¿Qué necesitas saber antes de poder modelar algo?
52
+ 5. **Complejidad aparente** — ¿Sistema pequeño? ¿Multi-tenant? ¿Flujos largos con estados?
53
+
54
+ Esta fase no produce output visible. Termina en la lista de preguntas de la Fase 2.
55
+
56
+ ---
57
+
58
+ ## Fase 2 — Entrevista de Negocio
59
+
60
+ Ejecuta rondas de preguntas hasta tener cobertura suficiente en estas 5 dimensiones:
61
+
62
+ ```
63
+ ✅ ACTORES — quiénes usan el sistema y con qué roles
64
+ ✅ FLUJOS CORE — el flujo principal de valor del negocio
65
+ ✅ ESTADOS Y CICLOS — cómo evolucionan las entidades clave en el tiempo
66
+ ✅ REGLAS — qué está permitido, prohibido, bajo qué condiciones
67
+ ✅ BORDES E INTEGS — qué pasa cuando algo falla, qué sistemas externos participan
68
+ ```
69
+
70
+ ### Guía de Entrevista por Rondas
71
+
72
+ Lee `references/interview-framework.md` para el detalle completo de preguntas por dimensión y ejemplos de preguntas efectivas.
73
+
74
+ **Ronda 1 — Contexto y valor**
75
+
76
+ Empieza aquí si la idea es muy vaga (menos de 2–3 oraciones de descripción):
77
+ - ¿Cuál es el problema principal que este sistema resuelve? ¿Para quién?
78
+ - ¿Quiénes son los usuarios finales y cuántos tipos de usuarios hay?
79
+ - ¿Cuál es el "momento de oro" — la acción más importante que el sistema permite hacer?
80
+
81
+ **Ronda 2 — Flujo principal**
82
+
83
+ Una vez conocido el qué y el quién:
84
+ - Cuéntame el flujo completo de principio a fin: ¿qué hace el usuario paso a paso?
85
+ - ¿Qué tiene que pasar *antes* de que ese flujo sea posible?
86
+ - ¿Qué pasa exactamente *después* de que el flujo termina? ¿Quién es notificado? ¿Qué se registra?
87
+
88
+ **Ronda 3 — Estados y ciclos de vida**
89
+
90
+ Una vez conocido el flujo principal:
91
+ - Para la entidad más importante del sistema (ej: "el pedido", "la reserva", "la solicitud") — ¿cuáles son todos los estados que puede tener?
92
+ - ¿Qué transiciones están permitidas? ¿Quién puede hacer cuál transición?
93
+ - ¿Se puede cancelar? ¿Se puede revertir? ¿Bajo qué condiciones?
94
+
95
+ **Ronda 4 — Reglas de negocio**
96
+
97
+ La ronda más importante: descubrir los invariantes:
98
+ - ¿Qué validaciones son críticas? (cosas que si fallan, el negocio tiene un problema real)
99
+ - ¿Hay límites o cuotas? (máximo de items, stock mínimo, saldo suficiente, cupos limitados)
100
+ - ¿Hay reglas de tiempo? (expiración, ventanas de tiempo, deadlines, recordatorios)
101
+ - ¿Quién tiene autoridad para hacer qué? ¿Hay aprobaciones necesarias?
102
+
103
+ **Ronda 5 — Casos de borde e integraciones**
104
+
105
+ - ¿Qué pasa si el pago falla? ¿Si el stock se agota? ¿Si el usuario no hace algo a tiempo?
106
+ - ¿Hay sistemas externos involucrados? (pasarelas de pago, correo, SMS, ERP, CRM...)
107
+ - ¿Hay reportes o dashboards necesarios? ¿Analytics?
108
+ - ¿Hay requerimientos de multitenancy o multi-empresa?
109
+
110
+ ### Reglas de la Entrevista
111
+
112
+ - **Máximo 5 preguntas por ronda.** Si tienes más, prioriza las que desbloquean más entendimiento.
113
+ - **Una ronda a la vez.** Espera respuesta antes de continuar.
114
+ - **Si el usuario es un experto técnico**, puedes ir más rápido y saltar rondas que ya cubrió.
115
+ - **Si el usuario no sabe responder algo**, sugiere opciones comunes del dominio y pide confirmación.
116
+ - **Anota cada respuesta mentalmente** en la dimensión correspondiente (✅ arriba).
117
+
118
+ ---
119
+
120
+ ## Fase 3 — Síntesis y Validación
121
+
122
+ Cuando tengas cobertura suficiente en las 5 dimensiones, presenta un resumen estructurado **antes** de generar los artefactos:
123
+
124
+ ```
125
+ ## Resumen funcional — [Nombre del Producto]
126
+
127
+ ### Actores
128
+ - [Actor 1]: [qué hace, sus permisos principales]
129
+ - [Actor 2]: [qué hace, sus permisos principales]
130
+
131
+ ### Módulos identificados
132
+ - [módulo-1]: [responsabilidad en una línea]
133
+ - [módulo-2]: [responsabilidad en una línea]
134
+
135
+ ### Flujo principal
136
+ [Descripción del happy path en 5–8 pasos numerados]
137
+
138
+ ### Estados de [EntidadPrincipal]
139
+ [Diagrama de estados en texto: ESTADO_A --acción--> ESTADO_B]
140
+
141
+ ### Reglas de negocio críticas
142
+ 1. [Regla]
143
+ 2. [Regla]
144
+ ...
145
+
146
+ ### Flujos alternativos importantes
147
+ - [ej: pago fallido → reintento / cancelación]
148
+ - [ej: stock insuficiente → notificación / lista de espera]
149
+
150
+ ### Integraciones externas
151
+ - [Sistema externo]: [propósito]
152
+ ```
153
+
154
+ Termina con: **"¿Este resumen captura bien lo que necesitas? ¿Hay algo que ajustar o que falte?"**
155
+
156
+ Solo continúa a la Fase 4 cuando el usuario confirme.
157
+
158
+ ---
159
+
160
+ ## Fase 4 — Generación de Artefactos
161
+
162
+ Una vez confirmado el resumen, genera los siguientes archivos. Lee `references/output-templates.md` para ver los templates exactos de cada archivo.
163
+
164
+ ### Archivos a generar
165
+
166
+ | Archivo | Propósito |
167
+ |---------|-----------|
168
+ | `system/FUNCTIONAL_REQUIREMENTS.md` | Casos de uso nombrados, precondiciones, postcondiciones |
169
+ | `system/PRODUCT_FLOWS.md` | Flujos de negocio por actor: happy path + flujos alternativos |
170
+ | `system/BUSINESS_RULES.md` | Reglas de negocio, invariantes, restricciones del dominio |
171
+
172
+ > **¿Por qué estos nombres?** `USER_FLOWS.md` y `VALIDATION_FLOWS.md` los genera `build-system-yaml` con contenido técnico (endpoints reales, topics Kafka, payloads). Los archivos de este skill son de negocio y tienen nombres distintos para no colisionar. `build-system-yaml` los leerá como contexto de entrada.
173
+
174
+ Genera los tres archivos completos. **Todo en inglés** — el contenido de los archivos siempre en inglés, la conversación puede ser en cualquier idioma.
175
+
176
+ ### Mensaje de Cierre
177
+
178
+ Después de generar los archivos, muestra este mensaje de cierre:
179
+
180
+ ```
181
+ ## ✅ Requisitos funcionales listos
182
+
183
+ Se han generado 3 archivos en system/:
184
+ - FUNCTIONAL_REQUIREMENTS.md — [N] use cases documentados
185
+ - PRODUCT_FLOWS.md — flujos de [Actor1], [Actor2], ...
186
+ - BUSINESS_RULES.md — [N] reglas de negocio capturadas
187
+
188
+ ### Próximo paso sugerido
189
+ Estos archivos son la entrada para el diseño de arquitectura.
190
+
191
+ **Opción A — Sistema basado en eventos (Kafka/RabbitMQ):**
192
+ Usa el skill `build-system-yaml` con este prompt:
193
+ > "Diseña la arquitectura para [nombre del producto] usando los requisitos en system/FUNCTIONAL_REQUIREMENTS.md, USER_FLOWS.md y VALIDATION_FLOWS.md"
194
+
195
+ **Opción B — Sistema con flujos duraderos (Temporal workflows):**
196
+ Usa el skill `build-temporal-system` con el mismo prompt si hay flujos
197
+ multi-paso con compensación, tiempos de espera, o sagas de negocio.
198
+ ```
199
+
200
+ ---
201
+
202
+ ## Señales de Cobertura Suficiente
203
+
204
+ Puedes pasar a la Fase 3 cuando:
205
+ - [ ] Conoces todos los actores y sus permisos principales
206
+ - [ ] Conoces el flujo principal de valor de principio a fin
207
+ - [ ] Conoces todos los estados de la(s) entidad(es) core y sus transiciones
208
+ - [ ] Conoces al menos 3–5 reglas de negocio concretas (no genéricas)
209
+ - [ ] Conoces qué pasa en al menos 2 casos de fallo importantes
210
+ - [ ] Sabes si hay integraciones externas y cuáles son
211
+
212
+ Si te falta alguna dimensión, lanza otra ronda antes de sintetizar.
213
+
214
+ ---
215
+
216
+ ## Anti-Patrones — Lo que NO Debes Hacer
217
+
218
+ ❌ **No inventar reglas de negocio.** Si el usuario no lo dice, no lo asumas.
219
+
220
+ ❌ **No hacer preguntas técnicas prematuras.** "¿Usarás Kafka o RabbitMQ?" no es una pregunta funcional.
221
+
222
+ ❌ **No generar artefactos sin confirmación del resumen.** El usuario debe validar antes de que generes los archivos.
223
+
224
+ ❌ **No usar jerga técnica con usuarios no técnicos.** Di "flujos automáticos en background" en vez de "async events".
225
+
226
+ ❌ **No modelar clases de datos en esta fase.** Los campos concretos los decide `build-system-yaml`.
227
+
228
+ ❌ **No omitir los flujos de fallo.** Los happy paths son fáciles; los flujos de error revelan las reglas reales.
@@ -0,0 +1,260 @@
1
+ # Interview Framework — Requirements Elicitation
2
+
3
+ Este documento contiene el banco de preguntas completo, organizadas por dimensión, con notas sobre cuándo usar cada una y ejemplos de respuestas que revelan entendimiento profundo vs. superficial.
4
+
5
+ ---
6
+
7
+ ## Dimensión 1 — Actores y Roles
8
+
9
+ El objetivo es descubrir *quién* interactúa con el sistema, con qué intenciones, y qué permisos o restricciones tienen.
10
+
11
+ ### Preguntas de descubrimiento
12
+
13
+ **Básicas (siempre hacer):**
14
+ - ¿Quiénes son los usuarios de este sistema? ¿Hay diferentes tipos?
15
+ - ¿Alguien administra el sistema "desde adentro" (backoffice) además de los usuarios finales?
16
+ - ¿Hay usuarios que solo consultan vs. usuarios que crean o modifican información?
17
+
18
+ **De profundidad (cuando hay múltiples roles):**
19
+ - ¿Qué puede hacer cada tipo de usuario que los demás NO pueden?
20
+ - ¿Hay jerarquías? ¿Un manager puede ver/hacer cosas que un empleado no?
21
+ - ¿Los permisos se configuran por empresa/tenant o son fijos?
22
+ - ¿Hay acciones que requieren la participación de más de un rol para completarse?
23
+
24
+ **De borde:**
25
+ - ¿Puede un usuario tener múltiples roles? ¿Al mismo tiempo?
26
+ - ¿Hay usuarios "invitados" o acceso sin autenticación para alguna parte?
27
+ - ¿Hay actores no-humanos involucrados? (sistemas externos, cron jobs, webhooks)
28
+
29
+ ### Señales de respuesta completa
30
+ ✅ Hay al menos 2 actores identificados con nombres concretos (no "usuario genérico")
31
+ ✅ Sabes qué hace CADA actor en el sistema
32
+ ✅ Sabes las diferencias de permisos entre actors
33
+
34
+ ### Señales de que necesitas profundizar
35
+ ⚠️ "Solo hay un tipo de usuario" — improbable en sistemas reales, pregunta por backoffice
36
+ ⚠️ "El admin puede hacer todo" — necesitas saber exactamente qué es "todo"
37
+
38
+ ---
39
+
40
+ ## Dimensión 2 — Flujo Principal de Valor
41
+
42
+ El objetivo es entender el *momento de mayor valor* del sistema: la secuencia de pasos que le da sentido al producto.
43
+
44
+ ### Preguntas de descubrimiento
45
+
46
+ **El flujo central:**
47
+ - ¿Cuál es la acción más importante que este sistema permite hacer? ¿Cuéntame cómo funciona paso a paso.
48
+ - Si una persona nueva llegara y quisiera usar la función principal del sistema, ¿qué haría?
49
+ - ¿Qué tiene que estar "listo" en el sistema antes de que ese flujo sea posible?
50
+
51
+ **Lo que viene antes y después:**
52
+ - ¿Cómo empieza el flujo? ¿Quién lo inicia?
53
+ - ¿Hay pasos que ocurren automáticamente (sin acción del usuario)?
54
+ - ¿Qué pasa inmediatamente después de que el flujo termina? ¿Qué se registra? ¿Quién se entera?
55
+ - ¿Hay algo que deba pasar "en background" después de la acción principal?
56
+
57
+ **Concurrencia y volumen:**
58
+ - ¿Múltiples usuarios pueden estar haciendo esto al mismo tiempo sobre el mismo recurso? (ej: dos personas comprando el último item en stock)
59
+ - ¿Cuántas veces aproximadamente se ejecuta este flujo por día? (afecta diseño de performance)
60
+
61
+ ### Técnica narrativa: "El día en la vida"
62
+
63
+ Si el usuario responde de forma muy abstracta, pide: *"Cuéntame un caso concreto real que hayas tenido. Empezando desde el principio, ¿qué pasó?"*
64
+
65
+ Los casos concretos revelan excepciones y reglas implícitas que la descripción abstracta oculta.
66
+
67
+ ### Señales de respuesta completa
68
+ ✅ Puedes narrar el flujo en 5–10 pasos concretos
69
+ ✅ Sabes el actor que inicia cada paso
70
+ ✅ Sabes qué datos se necesitan en cada punto
71
+ ✅ Sabes si hay pasos automáticos vs. manuales
72
+
73
+ ---
74
+
75
+ ## Dimensión 3 — Estados y Ciclos de Vida
76
+
77
+ El objetivo es descubrir el **modelo de estados** de las entidades clave. Esta dimensión es la más reveladora para DDD porque los estados definen el ciclo de vida del agregado.
78
+
79
+ ### Preguntas de descubrimiento
80
+
81
+ **Identificar la entidad core:**
82
+ - ¿Cuál es la "cosa" principal que el sistema gestiona? (el pedido, la reserva, la solicitud, el ticket...)
83
+ - ¿Cómo llamarías a esa cosa en tu negocio?
84
+
85
+ **Descubrir los estados:**
86
+ - ¿En qué estados puede estar ese [objeto]? ¿Tiene estados diferentes en distintos momentos?
87
+ - ¿Cuándo está "en progreso"? ¿Cuándo está "terminado"? ¿Cuándo está "rechazado"?
88
+ - ¿Puede un [objeto] que está "terminado" volver a estar activo? ¿Bajo qué condición?
89
+ - ¿Hay estados que son permanentes (no se puede salir de ellos)?
90
+
91
+ **Descubrir las transiciones:**
92
+ - Para ir de [Estado A] a [Estado B], ¿qué tiene que pasar? ¿Quién lo hace?
93
+ - ¿Hay transiciones que son automáticas (pasa sola después de un tiempo o un evento)?
94
+ - ¿Hay transiciones que requieren aprobación de alguien?
95
+
96
+ **Estados de fallo:**
97
+ - ¿Qué pasa si algo falla a mitad del proceso? ¿El [objeto] queda en algún estado intermedio?
98
+ - ¿Se puede cancelar? ¿Hay cancelaciones automáticas (ej: si no se paga en X tiempo)?
99
+
100
+ ### Plantilla de diagrama de estados (para construir durante la entrevista)
101
+
102
+ ```
103
+ [Estado1] --(acción: quién)--> [Estado2]
104
+ [Estado2] --(acción: quién)--> [Estado3]
105
+ [Estado2] --(acción: quién / condición)--> [EstadoCancelado]
106
+ ```
107
+
108
+ Construye esto mentalmente y valida con el usuario antes de sintetizar.
109
+
110
+ ### Señales de respuesta completa
111
+ ✅ Tiene al menos 3 estados identificados
112
+ ✅ Sabes quién desencadena cada transición
113
+ ✅ Sabes si hay estados terminales (irreversibles)
114
+ ✅ Sabes si hay tiempos involucrados (expiración, recordatorios)
115
+
116
+ ---
117
+
118
+ ## Dimensión 4 — Reglas de Negocio e Invariantes
119
+
120
+ Esta es la dimensión más valiosa y la más difícil de extraer. Las reglas de negocio reales raramente aparecen en la descripción inicial — hay que excavar.
121
+
122
+ ### Preguntas de descubrimiento
123
+
124
+ **Reglas de validación:**
125
+ - ¿Qué información es obligatoria para crear un [objeto]? ¿Hay campos que deben cumplir un formato?
126
+ - ¿Hay combinaciones de datos inválidas? (ej: no puede haber descuento del 100% en órdenes > $1000)
127
+
128
+ **Límites y cuotas:**
129
+ - ¿Hay límites de cantidad, stock, fondos, o cupos? ¿Qué pasa cuando se alcanza el límite?
130
+ - ¿Hay reglas de "máximo por usuario" o "máximo global"?
131
+
132
+ **Reglas de tiempo:**
133
+ - ¿Hay cosas que expiran? ¿Cuánto tiempo duran vigentes?
134
+ - ¿Hay recordatorios o notificaciones automáticas antes de que algo expire?
135
+ - ¿Hay horas hábiles o ventanas de tiempo para ciertas operaciones?
136
+
137
+ **Reglas de autorización:**
138
+ - ¿Hay acciones que solo ciertos roles pueden hacer bajo ciertas condiciones?
139
+ - ¿Hay aprobaciones? ¿Dobles niveles de aprobación?
140
+ - ¿Un usuario puede operar sobre recursos de otros usuarios? ¿Bajo qué condición?
141
+
142
+ **Reglas de integridad:**
143
+ - ¿Puede eliminarse un [objeto] si tiene [otros objetos] asociados?
144
+ - ¿Qué pasa con los [objetos relacionados] cuando eliminas o cancelas el [objeto principal]?
145
+
146
+ ### La pregunta más reveladora
147
+
148
+ Cuando el usuario ya cubrió las reglas obvias, pregunta:
149
+ *"¿Cuál ha sido el litigio o problema de negocio más común que este sistema debería haber evitado? ¿Qué regla habría prevenido ese problema?"*
150
+
151
+ Los problemas reales revelan las reglas implícitas que nadie piensa en mencionar.
152
+
153
+ ### Señales de respuesta completa
154
+ ✅ Tienes al menos 5 reglas concretas (no "los campos son obligatorios" — eso es genérico)
155
+ ✅ Tienes al menos 1 regla que no es obvia (invariante de negocio específico del dominio)
156
+ ✅ Sabes qué pasa cuando se viola cada regla (error al usuario, log, reintento...)
157
+
158
+ ---
159
+
160
+ ## Dimensión 5 — Casos de Borde e Integraciones
161
+
162
+ ### Preguntas sobre fallos
163
+
164
+ - ¿Qué pasa si [sistema externo crítico] no responde? (ej: pasarela de pago, SMS, inventario)
165
+ - ¿Qué pasa si el usuario no completa el flujo? ¿Queda algo incompleto en el sistema?
166
+ - ¿Qué pasa si dos usuarios intentan hacer lo mismo al mismo tiempo sobre el mismo recurso?
167
+ - ¿Hay operaciones que deben ser "o todo o nada"? (ej: reservar stock Y registrar el pedido — si una falla, la otra debe revertirse)
168
+
169
+ ### Preguntas sobre integraciones
170
+
171
+ - ¿Hay sistemas externos que este sistema llama? (APIs de pago, correo, SMS, mapas, CRM...)
172
+ - ¿Hay sistemas externos que llaman a este? (webhooks entrantes, integraciones)
173
+ - ¿Hay sistemas internos de la empresa que deben sincronizarse? (ERP, contabilidad, BI)
174
+ - ¿Hay proveedores externos con SLAs específicos o limitaciones de rate?
175
+
176
+ ### Preguntas sobre observabilidad
177
+
178
+ - ¿Hay dashboards o reportes que el negocio necesita?
179
+ - ¿Necesitas auditoría de quién hizo qué y cuándo?
180
+ - ¿Hay notificaciones que deben enviarse? ¿A quién, cuándo, por qué canal?
181
+
182
+ ### Señales de respuesta completa
183
+ ✅ Sabes al menos el flujo de fallo del caso más crítico
184
+ ✅ Sabes todas las integraciones externas y su propósito
185
+ ✅ Sabes si hay notificaciones y cuándo/a quién
186
+
187
+ ---
188
+
189
+ ## Técnicas de Entrevista Efectiva
190
+
191
+ ### Técnica: Cinco "¿Por qué?"
192
+
193
+ Cuando una respuesta parece simple, aplica "¿por qué?" hasta descubrir la regla real:
194
+
195
+ > "Los precios no pueden ser negativos."
196
+ > "¿Por qué? ¿Hay un caso donde un descuento podría llevar a precio negativo?"
197
+ > "Bueno, sí, los descuentos están limitados al 90%..."
198
+ > "¿Y quién puede asignar descuentos mayores al 50%?"
199
+
200
+ Cada "¿por qué?" revela una regla nueva.
201
+
202
+ ### Técnica: Casos extremos
203
+
204
+ "Qué pasa si..." seguido de un caso extremo o anormal:
205
+ - "¿Qué pasa si alguien intenta comprar 10,000 unidades de golpe?"
206
+ - "¿Qué pasa si el usuario canceló su cuenta pero tiene pedidos pendientes?"
207
+ - "¿Qué pasa si la misma dirección registra dos cuentas?"
208
+
209
+ ### Técnica: Analogía de negocio
210
+
211
+ Si el usuario no sabe cómo responder, usa analogías del mismo dominio:
212
+ - "En Amazon, cuando compras el último artículo disponible, el stock cae a 0 y el producto se marca como agotado. ¿Algo similar ocurre aquí?"
213
+
214
+ Esto da al usuario un punto de partida para comparar y ajustar.
215
+
216
+ ### Técnica: Pre-condición explícita
217
+
218
+ Para cada flujo, pregunta: "¿Qué tiene que ser verdad en el sistema ANTES de que esto sea posible?"
219
+ Esto revela dependencias, pre-estados, y configuración necesaria que el usuario asume obvia.
220
+
221
+ ---
222
+
223
+ ## Reconocer Dominios Comunes y Sus Preguntas Específicas
224
+
225
+ ### E-Commerce / Marketplace
226
+ - ¿Hay inventario real o es bajo demanda? ¿Por SKU o por variante?
227
+ - ¿Cómo funciona el pricing? ¿Precios fijos, variables, por nivel de cliente?
228
+ - ¿Hay carrito persistente? ¿Sesión anónima?
229
+ - ¿La empresa vende directamente o es un marketplace con múltiples vendedores?
230
+ - ¿Cómo es el flujo de fulfillment? ¿Quién gestiona el envío?
231
+
232
+ ### Salud / Clínica
233
+ - ¿Hay citas con disponibilidad limitada? ¿Cómo se gestiona el horario del profesional?
234
+ - ¿Hay historia clínica? ¿Quién puede acceder a ella?
235
+ - ¿Hay prescripciones o autorizaciones que deben seguir flujos regulatorios?
236
+ - ¿Hay integración con seguros médicos o sistemas de salud nacionales?
237
+
238
+ ### Logística / Transportes
239
+ - ¿El seguimiento es en tiempo real o por hitos?
240
+ - ¿Hay múltiples paradas o puntos de entrega?
241
+ - ¿Qué pasa si el destinatario no está? ¿Reintento automático o manual?
242
+ - ¿Hay zonas geográficas con reglas distintas?
243
+
244
+ ### Fintech / Pagos
245
+ - ¿La plataforma mueve dinero real o es solo trazabilidad?
246
+ - ¿Hay wallets o saldos internos? ¿Cómo se fondean?
247
+ - ¿Hay regulación local que aplique? (PCI-DSS, normativa bancaria local)
248
+ - ¿Hay reversiones o chargebacks?
249
+
250
+ ### B2B SaaS / Multi-tenant
251
+ - ¿Los clientes son empresas con múltiples usuarios?
252
+ - ¿Cada empresa tiene datos completamente aislados o hay datos compartidos?
253
+ - ¿Hay planes/tiers con funcionalidades distintas?
254
+ - ¿Hay un ciclo de onboarding de empresa antes de que los usuarios puedan operar?
255
+
256
+ ### RR.HH. / Gestión Interna
257
+ - ¿Hay jerarquía organizacional que afecte permisos o flujos de aprobación?
258
+ - ¿Los flujos pasan por múltiples niveles de aprobación?
259
+ - ¿Hay integración con nómina u otros sistemas de HR?
260
+ - ¿Hay períodos de cierre (mensual, anual) que restrinjan operaciones?