---
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) -->
