@saulwade/swl-ses 1.4.0 → 1.4.2

package/habilidades/eval-framework/SKILL.md

@@ -1,212 +1,212 @@
----
-name: eval-framework
-description: >
-  Eval framework para validar y puntuar outputs estructurados de SWL
-  (aprendizajes, instintos, observaciones, resúmenes, contextos). Cargar
-  cuando un agente produzca un output estructurado y se quiera medir su
-  calidad antes de persistir, o cuando se audite la calidad histórica de
-  funciones críticas (extractor-de-aprendizajes, perfilador-usuario,
-  consolidador, planificador).
-version: "1.0.0"
-herramientasPermitidas: [Read, Bash]
-exclusiones:
-  - "No cargar para validación de input de usuario o request HTTP — eso es validación de boundary, usar Pydantic/Zod en el endpoint."
-  - "No cargar para auditoría de seguridad — usar `revisor-seguridad-swl` y `escaneo-secretos`."
-  - "No cargar para tests unitarios de código — usar `tdd-workflow` y Vitest."
-  - "No cargar cuando el output no tiene estructura definida (texto libre): el eval framework requiere schemas declarados o quality scorers específicos."
-evolvable: true  # default para skill estandar
----
-# Eval Framework — Validación + Calidad de Outputs SWL
-
-## Cuándo cargar
-
-- Tras producir un output estructurado (observación, aprendizaje, resumen,
-  resultado de búsqueda) cuando se quiera puntuar su calidad antes de
-  persistir.
-- Para auditar histórico de calidad de una función crítica (ver métricas
-  agregadas en `.planning/evolucion/eval-metrics.json`).
-- En tests/CI cuando el contrato del output tenga campos obligatorios y
-  quality thresholds.
-- En loops de auto-corrección donde un output inválido debe regenerarse
-  con un prompt más estricto.
-
----
-
-## Componentes del framework
-
-| Módulo | Propósito |
-|---|---|
-| `scripts/lib/eval-schemas.js` | Schemas JSON-lite para outputs (observación, resumen, search input, etc.). |
-| `scripts/lib/eval-validator.js` | Validador zero-deps de schemas (sin Zod). |
-| `scripts/lib/eval-quality.js` | Funciones de scoring: `scoreObservacion`, `scoreResumen`, `scoreAprendizaje`, `scoreInstinto`, `scoreRelevanciaContexto`. |
-| `scripts/lib/eval-self-correct.js` | Loop de retry con sufijo estricto cuando validador falla. |
-| `scripts/lib/eval-metrics-store.js` | Persistencia: JSONL append-only (`eval-results.jsonl`) + agregado JSON (`eval-metrics.json`). |
-| `scripts/run-eval.js` | CLI para evaluar un output desde archivo JSON. |
-
----
-
-## Uso típico desde agente o test
-
-### Validar output contra schema
-
-```js
-const { validar } = require('./scripts/lib/eval-validator');
-const { COMPRESS_OUTPUT_SCHEMA } = require('./scripts/lib/eval-schemas');
-
-const observacion = {
-  type: 'discovery',
-  title: 'Detalle relevante',
-  facts: ['fact 1', 'fact 2'],
-  narrative: 'Narrativa con suficiente detalle para evaluar',
-  concepts: ['c1'],
-  files: ['ruta/al/archivo.js'],
-  importance: 7,
-};
-
-const r = validar(observacion, COMPRESS_OUTPUT_SCHEMA);
-if (!r.valid) {
-  console.error('Output inválido:', r.errors);
-} else {
-  // Persistir
-}
-```
-
-### Puntuar calidad (independiente de validez)
-
-```js
-const { scoreObservacion, scoreAprendizaje, scoreInstinto } = require('./scripts/lib/eval-quality');
-
-const score = scoreObservacion(observacion);
-// score ∈ [0, 100]. 100 = todos los campos óptimos.
-```
-
-### Loop de auto-corrección
-
-```js
-const { compresseConReintento } = require('./scripts/lib/eval-self-correct');
-
-const productor = async (sysPrompt, userPrompt) => {
-  // Llamar al LLM o ejecutar Skill que produzca el output
-  return await llamarClaude(sysPrompt, userPrompt);
-};
-
-const validador = (output) => {
-  const parsed = JSON.parse(output);
-  return validar(parsed, COMPRESS_OUTPUT_SCHEMA);
-};
-
-const r = await compresseConReintento({
-  productor, validador,
-  sysPrompt: '...', userPrompt: '...',
-  maxRetries: 2,
-});
-
-if (r.valid) {
-  // r.output es válido (puede haber requerido r.intentos retries)
-}
-```
-
-### Persistir métricas para auditoría histórica
-
-```js
-const ms = require('./scripts/lib/eval-metrics-store');
-
-ms.registrar(process.cwd(), {
-  functionId: 'extractor-de-aprendizajes::scorer',
-  latencyMs: 42,
-  success: true,
-  qualityScore: 85,
-});
-
-// Lectura agregada
-const m = ms.obtener(process.cwd(), 'extractor-de-aprendizajes::scorer');
-// → { totalCalls, successCount, failureCount, avgLatencyMs, avgQualityScore, ... }
-```
-
-### CLI desde Bash (para CI o manual)
-
-```bash
-# Crear archivo de eval
-cat > /tmp/eval.json << 'EOF'
-{
-  "functionId": "memoria-busqueda::search",
-  "schemaName": "MEMORY_SEARCH_RESULT_SCHEMA",
-  "qualityScorer": null,
-  "expectedKeys": ["id", "tipo", "titulo", "fecha", "relevancia"],
-  "output": { ... }
-}
-EOF
-
-# Ejecutar
-node scripts/run-eval.js /tmp/eval.json
-# Exit 0 si valid, 1 si inválido. Persiste métricas automáticamente.
-
-# Reconstruir agregado desde JSONL si se corrompe
-node scripts/run-eval.js --rebuild-aggregate
-```
-
----
-
-## Schemas disponibles
-
-- `COMPRESS_OUTPUT_SCHEMA` — observación comprimida con type, title, facts,
-  narrative, concepts, files, importance.
-- `SUMMARY_OUTPUT_SCHEMA` — resumen de sesión con title, narrative,
-  keyDecisions, filesModified, concepts.
-- `SEARCH_INPUT_SCHEMA` — input de búsqueda { query, limit? }.
-- `REMEMBER_INPUT_SCHEMA` — input de "remember" { content, type?,
-  concepts?, files? }.
-- `EVAL_RESULT_SCHEMA` — resultado de evaluación { valid, errors?,
-  qualityScore, latencyMs, functionId, metadata? }.
-- `MEMORY_SEARCH_RESULT_SCHEMA` — resultado de `hooks/lib/memory-search`
-  con id, tipo, titulo, fecha, relevancia, combinedScore?, confidence?.
-
-Agregar más schemas en `scripts/lib/eval-schemas.js` siguiendo el formato
-JSON Schema-lite (subset documentado en `eval-validator.js`).
-
----
-
-## Quality scorers disponibles
-
-- `scoreObservacion(obs)` — observación con type/title/facts/narrative/concepts/importance.
-- `scoreResumen(summary)` — resumen con title/narrative/keyDecisions/filesModified/concepts.
-- `scoreAprendizaje(aprendizaje)` — aprendizaje SWL con titulo/contenido/tipo (específico de SWL).
-- `scoreInstinto(instinto)` — instinto con pattern/confidence/status/source_*/evidence_count (específico de SWL).
-- `scoreRelevanciaContexto(context, project)` — contexto inyectado en sesión.
-
-Cada scorer devuelve un número en [0, 100]. Los criterios están documentados
-en cada función en `scripts/lib/eval-quality.js`.
-
----
-
-## Diferencias con tests unitarios
-
-| Eval framework | Tests unitarios |
-|---|---|
-| Mide calidad subjetiva sobre estructura | Mide correctitud lógica |
-| Score graduado [0, 100] | Pass/fail binario |
-| Persiste histórico para auditoría | No persiste (corre en CI) |
-| Para outputs estructurados de agentes | Para funciones puras / API |
-| Permite retry con prompt estricto | No aplicable |
-
-Los dos son complementarios: tests unitarios para `scoring-instintos.js`,
-eval framework para "¿el aprendizaje que extrajo el hook es de calidad?".
-
----
-
-## Gotchas / Errores comunes no obvios
-
-- **Validez estructural ≠ calidad**: un aprendizaje con `titulo: "X"` y
-  `contenido: "trivial"` puede pasar `expectedKeys` pero tener
-  `qualityScore: 0`. El framework los distingue. En CI gates, considerar
-  ambos: `valid && qualityScore >= 60`.
-- **Métricas agregadas se reescriben atómicamente**: si dos procesos
-  llaman `registrar()` en paralelo sobre el mismo `functionId`, el último
-  gana (race condition en agregado). Para alta concurrencia usar
-  `reconstruirAgregado()` periódicamente desde el JSONL append-only.
-- **`run-eval.js` exit code**: 0 = valid, 1 = inválido o error de I/O,
-  2 = error de uso. No confundir con quality threshold — el CLI no
-  bloquea por quality bajo, solo por validez.
-- **`compresseConReintento` no reintenta indefinidamente**: respeta
-  `maxRetries`. Tras agotar reintentos devuelve el último output con
-  `valid: false`. El caller decide qué hacer.
+---
+name: eval-framework
+description: >
+  Eval framework para validar y puntuar outputs estructurados de SWL
+  (aprendizajes, instintos, observaciones, resúmenes, contextos). Cargar
+  cuando un agente produzca un output estructurado y se quiera medir su
+  calidad antes de persistir, o cuando se audite la calidad histórica de
+  funciones críticas (extractor-de-aprendizajes, perfilador-usuario,
+  consolidador, planificador).
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar para validación de input de usuario o request HTTP — eso es validación de boundary, usar Pydantic/Zod en el endpoint."
+  - "No cargar para auditoría de seguridad — usar `revisor-seguridad-swl` y `escaneo-secretos`."
+  - "No cargar para tests unitarios de código — usar `tdd-workflow` y Vitest."
+  - "No cargar cuando el output no tiene estructura definida (texto libre): el eval framework requiere schemas declarados o quality scorers específicos."
+evolvable: true  # default para skill estandar
+---
+# Eval Framework — Validación + Calidad de Outputs SWL
+
+## Cuándo cargar
+
+- Tras producir un output estructurado (observación, aprendizaje, resumen,
+  resultado de búsqueda) cuando se quiera puntuar su calidad antes de
+  persistir.
+- Para auditar histórico de calidad de una función crítica (ver métricas
+  agregadas en `.planning/evolucion/eval-metrics.json`).
+- En tests/CI cuando el contrato del output tenga campos obligatorios y
+  quality thresholds.
+- En loops de auto-corrección donde un output inválido debe regenerarse
+  con un prompt más estricto.
+
+---
+
+## Componentes del framework
+
+| Módulo | Propósito |
+|---|---|
+| `scripts/lib/eval-schemas.js` | Schemas JSON-lite para outputs (observación, resumen, search input, etc.). |
+| `scripts/lib/eval-validator.js` | Validador zero-deps de schemas (sin Zod). |
+| `scripts/lib/eval-quality.js` | Funciones de scoring: `scoreObservacion`, `scoreResumen`, `scoreAprendizaje`, `scoreInstinto`, `scoreRelevanciaContexto`. |
+| `scripts/lib/eval-self-correct.js` | Loop de retry con sufijo estricto cuando validador falla. |
+| `scripts/lib/eval-metrics-store.js` | Persistencia: JSONL append-only (`eval-results.jsonl`) + agregado JSON (`eval-metrics.json`). |
+| `scripts/run-eval.js` | CLI para evaluar un output desde archivo JSON. |
+
+---
+
+## Uso típico desde agente o test
+
+### Validar output contra schema
+
+```js
+const { validar } = require('./scripts/lib/eval-validator');
+const { COMPRESS_OUTPUT_SCHEMA } = require('./scripts/lib/eval-schemas');
+
+const observacion = {
+  type: 'discovery',
+  title: 'Detalle relevante',
+  facts: ['fact 1', 'fact 2'],
+  narrative: 'Narrativa con suficiente detalle para evaluar',
+  concepts: ['c1'],
+  files: ['ruta/al/archivo.js'],
+  importance: 7,
+};
+
+const r = validar(observacion, COMPRESS_OUTPUT_SCHEMA);
+if (!r.valid) {
+  console.error('Output inválido:', r.errors);
+} else {
+  // Persistir
+}
+```
+
+### Puntuar calidad (independiente de validez)
+
+```js
+const { scoreObservacion, scoreAprendizaje, scoreInstinto } = require('./scripts/lib/eval-quality');
+
+const score = scoreObservacion(observacion);
+// score ∈ [0, 100]. 100 = todos los campos óptimos.
+```
+
+### Loop de auto-corrección
+
+```js
+const { compresseConReintento } = require('./scripts/lib/eval-self-correct');
+
+const productor = async (sysPrompt, userPrompt) => {
+  // Llamar al LLM o ejecutar Skill que produzca el output
+  return await llamarClaude(sysPrompt, userPrompt);
+};
+
+const validador = (output) => {
+  const parsed = JSON.parse(output);
+  return validar(parsed, COMPRESS_OUTPUT_SCHEMA);
+};
+
+const r = await compresseConReintento({
+  productor, validador,
+  sysPrompt: '...', userPrompt: '...',
+  maxRetries: 2,
+});
+
+if (r.valid) {
+  // r.output es válido (puede haber requerido r.intentos retries)
+}
+```
+
+### Persistir métricas para auditoría histórica
+
+```js
+const ms = require('./scripts/lib/eval-metrics-store');
+
+ms.registrar(process.cwd(), {
+  functionId: 'extractor-de-aprendizajes::scorer',
+  latencyMs: 42,
+  success: true,
+  qualityScore: 85,
+});
+
+// Lectura agregada
+const m = ms.obtener(process.cwd(), 'extractor-de-aprendizajes::scorer');
+// → { totalCalls, successCount, failureCount, avgLatencyMs, avgQualityScore, ... }
+```
+
+### CLI desde Bash (para CI o manual)
+
+```bash
+# Crear archivo de eval
+cat > /tmp/eval.json << 'EOF'
+{
+  "functionId": "memoria-busqueda::search",
+  "schemaName": "MEMORY_SEARCH_RESULT_SCHEMA",
+  "qualityScorer": null,
+  "expectedKeys": ["id", "tipo", "titulo", "fecha", "relevancia"],
+  "output": { ... }
+}
+EOF
+
+# Ejecutar
+node scripts/run-eval.js /tmp/eval.json
+# Exit 0 si valid, 1 si inválido. Persiste métricas automáticamente.
+
+# Reconstruir agregado desde JSONL si se corrompe
+node scripts/run-eval.js --rebuild-aggregate
+```
+
+---
+
+## Schemas disponibles
+
+- `COMPRESS_OUTPUT_SCHEMA` — observación comprimida con type, title, facts,
+  narrative, concepts, files, importance.
+- `SUMMARY_OUTPUT_SCHEMA` — resumen de sesión con title, narrative,
+  keyDecisions, filesModified, concepts.
+- `SEARCH_INPUT_SCHEMA` — input de búsqueda { query, limit? }.
+- `REMEMBER_INPUT_SCHEMA` — input de "remember" { content, type?,
+  concepts?, files? }.
+- `EVAL_RESULT_SCHEMA` — resultado de evaluación { valid, errors?,
+  qualityScore, latencyMs, functionId, metadata? }.
+- `MEMORY_SEARCH_RESULT_SCHEMA` — resultado de `hooks/lib/memory-search`
+  con id, tipo, titulo, fecha, relevancia, combinedScore?, confidence?.
+
+Agregar más schemas en `scripts/lib/eval-schemas.js` siguiendo el formato
+JSON Schema-lite (subset documentado en `eval-validator.js`).
+
+---
+
+## Quality scorers disponibles
+
+- `scoreObservacion(obs)` — observación con type/title/facts/narrative/concepts/importance.
+- `scoreResumen(summary)` — resumen con title/narrative/keyDecisions/filesModified/concepts.
+- `scoreAprendizaje(aprendizaje)` — aprendizaje SWL con titulo/contenido/tipo (específico de SWL).
+- `scoreInstinto(instinto)` — instinto con pattern/confidence/status/source_*/evidence_count (específico de SWL).
+- `scoreRelevanciaContexto(context, project)` — contexto inyectado en sesión.
+
+Cada scorer devuelve un número en [0, 100]. Los criterios están documentados
+en cada función en `scripts/lib/eval-quality.js`.
+
+---
+
+## Diferencias con tests unitarios
+
+| Eval framework | Tests unitarios |
+|---|---|
+| Mide calidad subjetiva sobre estructura | Mide correctitud lógica |
+| Score graduado [0, 100] | Pass/fail binario |
+| Persiste histórico para auditoría | No persiste (corre en CI) |
+| Para outputs estructurados de agentes | Para funciones puras / API |
+| Permite retry con prompt estricto | No aplicable |
+
+Los dos son complementarios: tests unitarios para `scoring-instintos.js`,
+eval framework para "¿el aprendizaje que extrajo el hook es de calidad?".
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Validez estructural ≠ calidad**: un aprendizaje con `titulo: "X"` y
+  `contenido: "trivial"` puede pasar `expectedKeys` pero tener
+  `qualityScore: 0`. El framework los distingue. En CI gates, considerar
+  ambos: `valid && qualityScore >= 60`.
+- **Métricas agregadas se reescriben atómicamente**: si dos procesos
+  llaman `registrar()` en paralelo sobre el mismo `functionId`, el último
+  gana (race condition en agregado). Para alta concurrencia usar
+  `reconstruirAgregado()` periódicamente desde el JSONL append-only.
+- **`run-eval.js` exit code**: 0 = valid, 1 = inválido o error de I/O,
+  2 = error de uso. No confundir con quality threshold — el CLI no
+  bloquea por quality bajo, solo por validez.
+- **`compresseConReintento` no reintenta indefinidamente**: respeta
+  `maxRetries`. Tras agotar reintentos devuelve el último output con
+  `valid: false`. El caller decide qué hacer.

package/habilidades/feynman-auditor-swl/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: feynman-auditor-swl
+description: >
+  Auditor de bugs de lógica de negocio mediante la técnica Feynman: cuestiona
+  cada línea, cada orden de operaciones, cada presencia/ausencia de guard, y
+  cada asunción implícita. Language-agnostic (Python, TS, Go, Rust, Java, C#).
+  Cargar cuando se necesite revisión profunda de funciones individuales en
+  módulos críticos, especialmente tras un revisor-codigo-swl que pasó pero
+  donde sospechas que algo no está bien.
+---
+
+# Cuándo cargar
+
+- El módulo maneja dinero, inventario, permisos, o datos críticos irreversibles.
+- `revisor-codigo-swl` pasó pero hay sospecha de bug de lógica de negocio.
+- Nemesis está corriendo su Pasada 1.
+- Se necesita revisión profunda de una función específica antes de merge.
+
+# Cuándo NO cargar
+
+- Para escaneo de vulnerabilidades conocidas (CVE, inyecciones) — usar `revisor-seguridad-swl`.
+- Para revisión de estilo o cobertura de tests — usar `revisor-codigo-swl`.
+- Para funciones de utilería sin estado (formateo, parsing puro).
+- Como sustituto de tests de regresión.
+
+---
+
+# Feynman Auditor
+
+Encuentra bugs de lógica de negocio cuestionando cada línea como si tuvieras que explicarle el código a alguien que no asume nada.
+
+Las preguntas detalladas están en [recursos/preguntas-language-agnostic.md](recursos/preguntas-language-agnostic.md).
+
+---
+
+## Mentalidad de base
+
+Antes de leer el primer archivo, adoptar esta perspectiva:
+
+> "Este código tiene un bug. Mi trabajo es encontrarlo.
+> No estoy aquí para confirmar que el código es correcto.
+> Cada línea que no entiendo completamente es un sospechoso."
+
+Dos fuentes principales de bugs de lógica:
+
+1. **Bugs de guard ausente**: la condición correcta existe en función A pero falta en función B que hace lo mismo por un path diferente.
+2. **Bugs de orden de operaciones**: el cálculo es correcto, pero se ejecuta antes o después del momento en que los datos son válidos.
+
+---
+
+## Fase 0: Inventario de scope
+
+Antes de auditar, mapear:
+
+- ¿Qué módulos/archivos están en scope?
+- ¿Cuáles son las funciones de punto de entrada (endpoints, handlers, métodos públicos)?
+- ¿Qué datos persisten (BD, caché, archivos, estado en memoria)?
+- ¿Qué actores pueden llamar qué funciones?
+
+---
+
+## Fase 1: Auditoría de funciones individuales
+
+Para cada función no trivial, hacer las preguntas Q1–Q7 del archivo de recursos.
+
+Categorías de preguntas:
+- **Q1** — Propósito: ¿qué hace exactamente esta función y solo esta función?
+- **Q2** — Orden: ¿importa el orden de estas operaciones?
+- **Q3** — Consistencia cross-función: ¿qué tienen en común dos funciones que parecen similares?
+- **Q4** — Asunciones implícitas: ¿qué asume este código sin verificarlo?
+- **Q5** — Límites: ¿qué pasa en los extremos (cero, máximo, vacío, ya-existe)?
+- **Q6** — Returns y errores: ¿qué devuelve esta función cuando algo falla?
+- **Q7** — Interacciones externas: ¿qué puede pasar mal cuando se llama a otro sistema?
+
+Registrar como sospechoso cualquier función donde una pregunta no tenga respuesta clara en el código.
+
+---
+
+## Fase 2: Auditoría cross-función
+
+Buscar divergencias entre funciones que deberían comportarse igual:
+
+- ¿Función A y B hacen lo mismo pero una tiene un guard que la otra no tiene?
+- ¿La función de creación inicializa todos los campos que la función de lectura usa?
+- ¿El path de happy path y el path de error manejan el estado de la misma manera?
+
+---
+
+## Fase 3: Síntesis de hallazgos
+
+Convertir sospechosos en hallazgos concretos:
+
+Para cada sospechoso, construir:
+1. La pregunta Feynman que lo identificó
+2. La asunción que el código hace implícitamente
+3. El contraejemplo concreto que rompe esa asunción
+4. La consecuencia observable del bug
+
+---
+
+## Fase 4: Verificación
+
+Todo hallazgo CRÍTICO, ALTO y MEDIO debe verificarse antes del reporte final.
+
+**Patrón de falsos positivos frecuentes:**
+- El guard existe pero en un nivel superior (middleware, decorator, caller).
+- El orden parece incorrecto pero hay un comentario que explica el diseño intencional.
+- La función parece no validar, pero el tipo de dato ya garantiza el invariante.
+
+**Formato de salida**: `.audit/findings/feynman-passN.md`
+
+---
+
+## Adaptación por lenguaje
+
+| Concepto | Python | TypeScript | Go | Rust | Java | C# |
+|---------|--------|------------|-----|------|------|-----|
+| Actor | `request.user` | `req.user` / `userId` | `ctx.UserID` | `actor_id` | `principal` | `User.Identity` |
+| Guard | decorador / `if not user:` | middleware / `if (!user)` | `if ctx.UserID == ""` | `if actor_id.is_none()` | `@PreAuthorize` | `[Authorize]` |
+| Mutación interna | método privado `_fn` | método privado | función local | `pub(crate) fn` | método `private` | método `private` |
+| Transacción | `with db.begin():` | `await trx.begin()` | `tx, _ := db.Begin()` | `conn.execute("BEGIN")` | `@Transactional` | `using var tx =` |
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->

package/habilidades/feynman-auditor-swl/recursos/preguntas-language-agnostic.md

@@ -0,0 +1,108 @@
+# Preguntas Feynman — Language-Agnostic
+
+28 preguntas organizadas en 7 categorías. Aplicar a cada función no trivial del módulo bajo auditoría.
+
+---
+
+## Q1 — Propósito
+
+**Q1.1** ¿Qué hace exactamente esta función y solo esta función? Si no puedo describirla en una oración sin usar "y", ¿tiene demasiadas responsabilidades?
+
+**Q1.2** ¿Cuál es el invariante que esta función garantiza al terminar? ¿El código lo garantiza de verdad o solo en el camino feliz?
+
+**Q1.3** ¿Hay alguna condición en que esta función debería rechazar la operación pero no lo hace? ¿Qué pasa si se la llama dos veces seguidas con los mismos argumentos?
+
+**Q1.4** ¿Esta función asume que el estado del sistema está en alguna condición particular antes de ejecutarse? ¿Dónde se verifica esa condición?
+
+---
+
+## Q2 — Orden de operaciones
+
+**Q2.1** ¿Importa el orden en que estas líneas se ejecutan? Si cambio el orden de dos líneas adyacentes, ¿el resultado es el mismo?
+
+**Q2.2** ¿Esta función lee un valor y luego lo modifica? Si algo cambia el valor entre la lectura y la escritura, ¿qué pasa?
+
+**Q2.3** ¿El cálculo de recompensa, crédito, o resultado se hace ANTES o DESPUÉS de actualizar el estado base? ¿Debería ser al revés?
+
+**Q2.4** ¿Si esta función llama a un sistema externo (BD, API, caché), el estado local ya está actualizado en ese momento? ¿El sistema externo puede ver un estado inconsistente?
+
+---
+
+## Q3 — Consistencia cross-función
+
+**Q3.1** ¿Qué tienen en común esta función y otra que hace algo similar? ¿Una tiene un guard o una actualización que la otra no tiene?
+
+**Q3.2** ¿Existe una función de "camino normal" y una de "camino de emergencia/admin"? ¿Ambas actualizan exactamente el mismo conjunto de estado?
+
+**Q3.3** ¿Esta función inicializa todos los campos que otras funciones esperan encontrar inicializados? ¿Hay algún campo que se lee antes de ser escrito?
+
+**Q3.4** ¿El path que crea un recurso y el path que lo elimina dejan el sistema en un estado simétrico? ¿O el delete deja huérfanos?
+
+---
+
+## Q4 — Asunciones implícitas
+
+**Q4.1** ¿Qué asume este código sobre el tipo o el rango del argumento que recibe? ¿Hay alguna validación que debería existir pero no existe?
+
+**Q4.2** ¿El código asume que el actor que llama esta función tiene permiso para hacerlo? ¿Dónde se verifica ese permiso exactamente?
+
+**Q4.3** ¿El código asume que algún recurso externo (BD, archivo, servicio) está disponible y en un estado consistente? ¿Qué pasa si no lo está?
+
+**Q4.4** ¿El código asume que nunca se llamará con valor cero, lista vacía, o string vacío? ¿Se validó eso?
+
+---
+
+## Q5 — Límites y casos de borde
+
+**Q5.1** ¿Qué pasa si el valor es exactamente cero? ¿Y si es el máximo representable? ¿Y si es negativo?
+
+**Q5.2** ¿Qué pasa si la lista o colección está vacía? ¿Y si tiene exactamente un elemento? ¿Y si tiene millones?
+
+**Q5.3** ¿Qué pasa si el recurso ya existe cuando se intenta crear? ¿Y si no existe cuando se intenta modificar o eliminar?
+
+**Q5.4** ¿Qué pasa si dos actores ejecutan esta función al mismo tiempo? ¿Hay condición de carrera? ¿El resultado es determinista?
+
+---
+
+## Q6 — Returns y manejo de errores
+
+**Q6.1** ¿Qué devuelve esta función cuando el input es inválido? ¿Lanza excepción, devuelve null, devuelve un error tipado, o silencia el problema?
+
+**Q6.2** ¿Si una operación parcial falla a mitad de camino, el estado queda consistente? ¿Hay rollback? ¿O el sistema queda a medias?
+
+**Q6.3** ¿El caller de esta función verifica el valor de retorno? ¿Un error no verificado puede causar daño silencioso más adelante?
+
+**Q6.4** ¿El código captura excepciones de forma demasiado amplia (`except Exception`, `catch (e)` vacío)? ¿Qué errores legítimos podría estar silenciando?
+
+---
+
+## Q7 — Interacciones externas
+
+**Q7.1** ¿Esta función llama a un sistema externo (BD, API, caché, cola)? ¿La llamada puede fallar? ¿Qué pasa con el estado local si falla?
+
+**Q7.2** ¿Esta función persiste datos en más de un lugar (ej: BD + caché + índice)? ¿Qué pasa si la segunda escritura falla después de que la primera tuvo éxito?
+
+**Q7.3** ¿El acumulador o índice que esta función usa se actualiza ANTES de modificar el valor base, o DESPUÉS? ¿El orden importa para la correctitud del cálculo?
+
+**Q7.4** ¿Esta función envía una notificación, evento, o mensaje a otro sistema? ¿Lo hace antes o después de confirmar la operación? ¿El receptor puede actuar sobre un estado que aún no se confirmó?
+
+**Q7.5** ¿Esta función lee un valor de caché y lo trata como fresco? ¿Hay algún path donde la caché puede estar desactualizada respecto a la fuente de verdad?
+
+**Q7.6** ¿Esta función modifica datos de otro actor además de los del actor que la llama? ¿Tiene permiso para hacerlo en todos los casos?
+
+**Q7.7** ¿Existe un patrón de acumulador donde el total acumulado se calcula con base en el estado anterior? Si el estado base cambia (insert/update/delete de otro registro), ¿el acumulador refleja el cambio correctamente?
+
+**Q7.8** ¿Esta función delega a otra función que tiene sus propios efectos secundarios? ¿El caller sabe qué estado modifica el callee internamente?
+
+---
+
+## Cómo usar estas preguntas
+
+1. Leer la función completa una vez para entender el propósito.
+2. Para cada pregunta de las categorías Q1–Q7, marcar:
+   - ✓ Respondida claramente por el código
+   - ? Requiere rastrear el caller o el sistema externo para responder
+   - ✗ El código no la responde — sospechoso de bug
+3. Todo `✗` o `?` sin resolver es un **sospechoso** para Fase 3 de síntesis.
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->