@saulwade/swl-ses 1.5.2 → 1.6.1

package/habilidades/doubt-driven-review/SKILL.md

@@ -1,171 +1,177 @@
----
-name: doubt-driven-review
-description: >
-  Adversarial peer review de decisiones técnicas antes de comprometerlas.
-  Cuestiona supuestos, fuerza la articulación de alternativas descartadas y
-  detecta confianza injustificada. Cargar antes de decidir arquitecturas
-  irreversibles, elegir un framework crítico, definir un contrato de API
-  público o aprobar un PR de alto impacto. NO cubre adversarial review de
-  memoria (eso lo hace red-team-swl) ni de seguridad de código (eso lo hace
-  revisor-seguridad-swl) — este skill se especializa en decisiones técnicas
-  con costo de cambio alto.
----
-
-# Doubt-Driven Review
-
-## Cuándo cargar
-
-- Antes de aprobar un ADR que toma una decisión irreversible.
-- Antes de comprometer un contrato público de API o un schema de BD que afecta integraciones externas.
-- Antes de elegir un framework, librería o patrón con costo de migración alto.
-- Antes de fusionar un PR cuyo blast radius incluye módulos críticos.
-- Cuando el equipo o el agente exhibe **alta confianza con baja evidencia** sobre una decisión técnica.
-
-## Cuándo NO cargar
-
-- Para revisar código por calidad — eso es `revisor-codigo-swl` con `Skill("checklist-calidad")`.
-- Para revisar seguridad — eso es `revisor-seguridad-swl` con `Skill("checklist-seguridad")`.
-- Para validar memoria contra prompt injection o privacidad — eso es `red-team-swl`.
-- Para discutir alcances con el usuario — eso es `Skill("brainstorming")` o `swl:discutir-fase`.
-- Para fixes triviales o decisiones reversibles en menos de 10 minutos.
-
-## Principio
-
-> Una decisión cuya alternativa no se ha articulado, no es una decisión:
-> es una preferencia. Toda decisión técnica con costo de cambio alto debe
-> sobrevivir a un round adversarial antes de comprometerse.
-
-El skill ejecuta un protocolo en 5 pasos. Cada paso produce evidencia en
-texto. La salida del skill NO aprueba ni rechaza — produce un reporte que
-el agente o usuario humano usa para decidir.
-
-## Protocolo
-
-### Paso 1 — Articular la decisión y su irreversibilidad
-
-Pedir explícitamente:
-
-- **Qué se decide**: 1-3 oraciones, sin jerga ambigua.
-- **Qué se descarta**: la decisión opuesta concreta.
-- **Costo de revertir**: estimación en turnos / archivos / horas si en 3 meses se concluye que fue incorrecta.
-
-Si el costo de revertir es < 4 horas y < 5 archivos: la decisión NO es candidata
-a doubt-driven review. Cerrar el skill y proceder.
-
-### Paso 2 — Forzar 3 alternativas descartadas
-
-El agente o usuario debe articular las 3 alternativas más fuertes que NO se eligieron, con:
-
-- Por qué cada una es plausible (≥ 1 razón concreta).
-- Qué tradeoff la hace inferior a la elegida (sin frase genérica como "menos flexible").
-
-Si la persona/agente no puede articular 3 alternativas: **señal de decisión bajo-evidencia**.
-Reportar: "Decisión propuesta sin alternativas articuladas. Riesgo de selección por inercia."
-
-### Paso 3 — Buscar contraevidencia activamente
-
-Para la decisión propuesta:
-
-- Listar 3 escenarios donde la decisión **fallaría** o produciría costos no anticipados.
-- Listar 1 caso histórico (dentro o fuera del proyecto) donde una decisión similar resultó incorrecta.
-- Identificar 1 supuesto de la decisión que NO está validado con evidencia (corre el riesgo de ser falso).
-
-Si los 3 escenarios de falla son improbables Y el supuesto está validado: la decisión gana robustez.
-Si ≥ 1 escenario tiene probabilidad ≥ 30%: documentar el riesgo en el reporte.
-
-### Paso 4 — Detectar confianza injustificada
-
-Patrones a marcar como red flags:
-
-- "Es la mejor práctica" sin citar fuente o caso.
-- "Siempre se hace así" sin verificar el contexto del proyecto actual.
-- "Es lo que recomienda <autoridad>" sin verificar que la recomendación aplica al stack/escala/dominio.
-- "No hay otra opción razonable" cuando el paso 2 ya forzó 3 alternativas.
-- Cita de un blog post o tweet como evidencia única.
-- Argumentos de tipo "todo el mundo lo usa" sin métrica concreta.
-
-Por cada red flag detectado: 1 línea en el reporte con cita textual del argumento.
-
-### Paso 5 — Trigger de reversión
-
-Toda decisión que pase doubt-driven review debe incluir:
-
-- **Trigger de reversión**: condición observable que, de cumplirse, obliga a reabrir la decisión.
-  Ejemplos válidos: "p95 de latencia > 800ms en producción durante 7 días",
-  "≥3 reportes de bugs relacionados con la limitación X en 30 días", "vendor X
-  publica deprecation notice", "costo mensual de infra excede $Y".
-- **Fecha de reevaluación automática**: 6-12 meses desde la fecha de decisión.
-
-Si la decisión NO puede tener trigger observable: es una decisión **basada en preferencia**,
-no en hipótesis falsable. Documentarla como tal en el reporte.
-
-## Formato del reporte
-
-```markdown
-## Doubt-Driven Review — [decisión] — [fecha]
-
-### Decisión articulada
-- Qué se decide: [...]
-- Qué se descarta: [...]
-- Costo de revertir: [estimación]
-
-### Alternativas articuladas
-1. [alt-1]: plausible porque [...]; descartada porque [tradeoff concreto]
-2. [alt-2]: ...
-3. [alt-3]: ...
-
-### Contraevidencia
-- Escenario de falla 1 [prob: alta/media/baja]: [...]
-- Escenario de falla 2 [prob: ...]: [...]
-- Escenario de falla 3 [prob: ...]: [...]
-- Caso histórico relevante: [...]
-- Supuesto sin validar: [...]
-
-### Red flags detectados
-- [línea N: cita textual del argumento débil]
-- [...]
-- (o "Ninguno")
-
-### Trigger de reversión
-- Condición: [observable falsable]
-- Fecha de reevaluación: [YYYY-MM-DD]
-
-### Veredicto
-- ROBUSTA — pasó los 5 pasos sin red flags y con trigger claro
-- ACEPTABLE — pasó con 1-2 red flags documentados y trigger claro
-- BAJO-EVIDENCIA — falla en pasos 2, 4 o 5; reabrir antes de comprometer
-```
-
-## Anti-patrones del skill
-
-- **Auto-revisión**: el agente que tomó la decisión ejecuta el skill sobre sí mismo.
-  Pierde el efecto adversarial. Cargar el skill desde un agente distinto al
-  decisor (ej: `arquitecto-swl` decidió → `revisor-codigo-swl` ejecuta el skill
-  con foco en la decisión).
-- **Trigger inverificable**: "cuando el sistema deje de escalar" no es trigger.
-  Debe ser una métrica observable con valor numérico o evento concreto.
-- **Alternativas de paja**: las 3 alternativas no pueden ser opciones triviales
-  inferiores a propósito. Si las 3 son obviamente peores, el skill perdió su valor
-  — pedir 3 alternativas reales o aceptar que la decisión es bajo-evidencia.
-- **Convertirlo en proceso burocrático**: aplicar doubt-driven a decisiones
-  reversibles es overhead. El paso 1 filtra esto explícitamente.
-
-## Relación con otras capacidades del sistema
-
-- `red-team-swl`: cubre adversarial review de **memoria del sistema** (perfil-usuario,
-  instintos, APRENDIZAJES). Doubt-driven cubre **decisiones técnicas**. NO duplicación.
-- `arquitecto-swl`: produce ADRs. Doubt-driven se carga ANTES de aceptar el ADR.
-- `revisor-codigo-swl`: revisa calidad de código ya escrito. Doubt-driven revisa
-  decisiones ANTES de escribir código.
-- `Skill("verificar-trabajo")`: verificación goal-backward del resultado.
-  Doubt-driven es goal-backward del **diseño**, no del resultado.
-
-## Origen
-
-Patrón observado en `temp/agent-skills-main/skills/doubt-driven-development`
-(2026-05-09). Adaptado al sistema swl-ses: en español, con trigger de
-reversión obligatorio (alineado con `reglas/arquitectura.md` § ADRs en estado
-Propuesto), y con relación explícita a `red-team-swl` para evitar duplicar
-funciones que ya existen en el sistema.
-
-Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
+---
+name: doubt-driven-review
+description: >
+  Adversarial peer review de decisiones técnicas antes de comprometerlas.
+  Cuestiona supuestos, fuerza la articulación de alternativas descartadas y
+  detecta confianza injustificada. Cargar antes de decidir arquitecturas
+  irreversibles, elegir un framework crítico, definir un contrato de API
+  público o aprobar un PR de alto impacto. NO cubre adversarial review de
+  memoria (eso lo hace red-team-swl) ni de seguridad de código (eso lo hace
+  revisor-seguridad-swl) — este skill se especializa en decisiones técnicas
+  con costo de cambio alto.
+version: "1.0.0"
+exclusiones:
+  - "No cargar para revisión de memoria SWL (APRENDIZAJES.md, instintos/) — esa es responsabilidad de red-team-swl."
+  - "No cargar para auditoría de seguridad de código (OWASP, CVEs, inyección) — usar revisor-seguridad-swl."
+  - "No cargar para decisiones reversibles de bajo costo (formato de output, nombre de variable, refactor menor) — el overhead del review no compensa."
+  - "No cargar para code review estándar de PR — eso es revisor-codigo-swl; este skill aplica a decisiones de diseño, no a calidad de código."
+---
+
+# Doubt-Driven Review
+
+## Cuándo cargar
+
+- Antes de aprobar un ADR que toma una decisión irreversible.
+- Antes de comprometer un contrato público de API o un schema de BD que afecta integraciones externas.
+- Antes de elegir un framework, librería o patrón con costo de migración alto.
+- Antes de fusionar un PR cuyo blast radius incluye módulos críticos.
+- Cuando el equipo o el agente exhibe **alta confianza con baja evidencia** sobre una decisión técnica.
+
+## Cuándo NO cargar
+
+- Para revisar código por calidad — eso es `revisor-codigo-swl` con `Skill("checklist-calidad")`.
+- Para revisar seguridad — eso es `revisor-seguridad-swl` con `Skill("checklist-seguridad")`.
+- Para validar memoria contra prompt injection o privacidad — eso es `red-team-swl`.
+- Para discutir alcances con el usuario — eso es `Skill("brainstorming")` o `swl:discutir-fase`.
+- Para fixes triviales o decisiones reversibles en menos de 10 minutos.
+
+## Principio
+
+> Una decisión cuya alternativa no se ha articulado, no es una decisión:
+> es una preferencia. Toda decisión técnica con costo de cambio alto debe
+> sobrevivir a un round adversarial antes de comprometerse.
+
+El skill ejecuta un protocolo en 5 pasos. Cada paso produce evidencia en
+texto. La salida del skill NO aprueba ni rechaza — produce un reporte que
+el agente o usuario humano usa para decidir.
+
+## Protocolo
+
+### Paso 1 — Articular la decisión y su irreversibilidad
+
+Pedir explícitamente:
+
+- **Qué se decide**: 1-3 oraciones, sin jerga ambigua.
+- **Qué se descarta**: la decisión opuesta concreta.
+- **Costo de revertir**: estimación en turnos / archivos / horas si en 3 meses se concluye que fue incorrecta.
+
+Si el costo de revertir es < 4 horas y < 5 archivos: la decisión NO es candidata
+a doubt-driven review. Cerrar el skill y proceder.
+
+### Paso 2 — Forzar 3 alternativas descartadas
+
+El agente o usuario debe articular las 3 alternativas más fuertes que NO se eligieron, con:
+
+- Por qué cada una es plausible (≥ 1 razón concreta).
+- Qué tradeoff la hace inferior a la elegida (sin frase genérica como "menos flexible").
+
+Si la persona/agente no puede articular 3 alternativas: **señal de decisión bajo-evidencia**.
+Reportar: "Decisión propuesta sin alternativas articuladas. Riesgo de selección por inercia."
+
+### Paso 3 — Buscar contraevidencia activamente
+
+Para la decisión propuesta:
+
+- Listar 3 escenarios donde la decisión **fallaría** o produciría costos no anticipados.
+- Listar 1 caso histórico (dentro o fuera del proyecto) donde una decisión similar resultó incorrecta.
+- Identificar 1 supuesto de la decisión que NO está validado con evidencia (corre el riesgo de ser falso).
+
+Si los 3 escenarios de falla son improbables Y el supuesto está validado: la decisión gana robustez.
+Si ≥ 1 escenario tiene probabilidad ≥ 30%: documentar el riesgo en el reporte.
+
+### Paso 4 — Detectar confianza injustificada
+
+Patrones a marcar como red flags:
+
+- "Es la mejor práctica" sin citar fuente o caso.
+- "Siempre se hace así" sin verificar el contexto del proyecto actual.
+- "Es lo que recomienda <autoridad>" sin verificar que la recomendación aplica al stack/escala/dominio.
+- "No hay otra opción razonable" cuando el paso 2 ya forzó 3 alternativas.
+- Cita de un blog post o tweet como evidencia única.
+- Argumentos de tipo "todo el mundo lo usa" sin métrica concreta.
+
+Por cada red flag detectado: 1 línea en el reporte con cita textual del argumento.
+
+### Paso 5 — Trigger de reversión
+
+Toda decisión que pase doubt-driven review debe incluir:
+
+- **Trigger de reversión**: condición observable que, de cumplirse, obliga a reabrir la decisión.
+  Ejemplos válidos: "p95 de latencia > 800ms en producción durante 7 días",
+  "≥3 reportes de bugs relacionados con la limitación X en 30 días", "vendor X
+  publica deprecation notice", "costo mensual de infra excede $Y".
+- **Fecha de reevaluación automática**: 6-12 meses desde la fecha de decisión.
+
+Si la decisión NO puede tener trigger observable: es una decisión **basada en preferencia**,
+no en hipótesis falsable. Documentarla como tal en el reporte.
+
+## Formato del reporte
+
+```markdown
+## Doubt-Driven Review — [decisión] — [fecha]
+
+### Decisión articulada
+- Qué se decide: [...]
+- Qué se descarta: [...]
+- Costo de revertir: [estimación]
+
+### Alternativas articuladas
+1. [alt-1]: plausible porque [...]; descartada porque [tradeoff concreto]
+2. [alt-2]: ...
+3. [alt-3]: ...
+
+### Contraevidencia
+- Escenario de falla 1 [prob: alta/media/baja]: [...]
+- Escenario de falla 2 [prob: ...]: [...]
+- Escenario de falla 3 [prob: ...]: [...]
+- Caso histórico relevante: [...]
+- Supuesto sin validar: [...]
+
+### Red flags detectados
+- [línea N: cita textual del argumento débil]
+- [...]
+- (o "Ninguno")
+
+### Trigger de reversión
+- Condición: [observable falsable]
+- Fecha de reevaluación: [YYYY-MM-DD]
+
+### Veredicto
+- ROBUSTA — pasó los 5 pasos sin red flags y con trigger claro
+- ACEPTABLE — pasó con 1-2 red flags documentados y trigger claro
+- BAJO-EVIDENCIA — falla en pasos 2, 4 o 5; reabrir antes de comprometer
+```
+
+## Anti-patrones del skill
+
+- **Auto-revisión**: el agente que tomó la decisión ejecuta el skill sobre sí mismo.
+  Pierde el efecto adversarial. Cargar el skill desde un agente distinto al
+  decisor (ej: `arquitecto-swl` decidió → `revisor-codigo-swl` ejecuta el skill
+  con foco en la decisión).
+- **Trigger inverificable**: "cuando el sistema deje de escalar" no es trigger.
+  Debe ser una métrica observable con valor numérico o evento concreto.
+- **Alternativas de paja**: las 3 alternativas no pueden ser opciones triviales
+  inferiores a propósito. Si las 3 son obviamente peores, el skill perdió su valor
+  — pedir 3 alternativas reales o aceptar que la decisión es bajo-evidencia.
+- **Convertirlo en proceso burocrático**: aplicar doubt-driven a decisiones
+  reversibles es overhead. El paso 1 filtra esto explícitamente.
+
+## Relación con otras capacidades del sistema
+
+- `red-team-swl`: cubre adversarial review de **memoria del sistema** (perfil-usuario,
+  instintos, APRENDIZAJES). Doubt-driven cubre **decisiones técnicas**. NO duplicación.
+- `arquitecto-swl`: produce ADRs. Doubt-driven se carga ANTES de aceptar el ADR.
+- `revisor-codigo-swl`: revisa calidad de código ya escrito. Doubt-driven revisa
+  decisiones ANTES de escribir código.
+- `Skill("verificar-trabajo")`: verificación goal-backward del resultado.
+  Doubt-driven es goal-backward del **diseño**, no del resultado.
+
+## Origen
+
+Patrón observado en `temp/agent-skills-main/skills/doubt-driven-development`
+(2026-05-09). Adaptado al sistema swl-ses: en español, con trigger de
+reversión obligatorio (alineado con `reglas/arquitectura.md` § ADRs en estado
+Propuesto), y con relación explícita a `red-team-swl` para evitar duplicar
+funciones que ya existen en el sistema.
+
+Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).

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

@@ -1,123 +1,129 @@
----
-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) -->
+---
+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.
+version: "1.0.0"
+exclusiones:
+  - "No cargar para revisión de estilo de código o naming — usar revisor-codigo-swl."
+  - "No cargar para auditoría de seguridad (OWASP, secretos, inyección) — usar revisor-seguridad-swl."
+  - "No cargar para módulos triviales de <200 LOC con CRUD directo — el costo de carga supera el valor."
+  - "No cargar para análisis de performance o bottlenecks — usar performance-baseline."
+---
+
+# 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) -->