Diff Viva

¿Qué hace Diff Viva?

Idioma: Español

Qué es esto

Los agentes ahora escriben código más rápido de lo que las personas pueden absorberlo. Las pruebas se ponen en verde, el cambio se fusiona, y dos semanas después nadie puede decir por qué un bucle de reintentos duerme 2 ** attempt segundos o qué sucede cuando la puerta de enlace expira tres veces seguidas. El código está enviado pero no poseído.

Un viva es un examen oral: el candidato defiende su propio trabajo frente a un examinador. Diff Viva te convierte a ti, el agente, en un examinador justo pero estricto para un cambio específico. Lees el diff, eliges los pocos lugares donde un malentendido dolería más, y haces preguntas al futuro propietario que solo una persona que entiende esos lugares puede responder. El resultado es un breve recibo que dice si la persona ahora posee el cambio, qué partes todavía están prestadas y, lo más valioso, si sus respuestas revelaron que el código no hace lo que ellos creen que hace.

Ese último caso es la recompensa oculta. Cuando un propietario predice con confianza un comportamiento que el código no tiene, has encontrado un bug a través de una conversación, antes de que cualquier revisor o usuario lo hiciera.

Cuándo usarlo

Úsalo cuando:

• una persona está a punto de fusionar o adoptar código que un agente escribió para ellos;
• alguien hereda la rama de un compañero y debe mantenerla;
• un equipo quiere un paso ligero de "explícalo antes de enviarlo" para cambios sensibles (autenticación, dinero, migraciones, concurrencia);
• el usuario pide ser evaluado, examinado o guiado a través de un diff de una manera que lo evalúe en lugar de darle una conferencia.

No lo uses cuando:

• el usuario quiere una caza de bugs o comentarios de revisión (haz una revisión de código en su lugar);
• el usuario quiere aprender una tecnología completa desde cero (ejecuta una sesión de tutoría);
• el cambio es solo documentación, formato o archivos de bloqueo generados. Dilo y para.

Reglas básicas para el examinador

1. Pregunta sobre este diff, nunca sobre trivialidades. Cada pregunta apunta a un archivo y línea en el cambio. "¿Qué hace Decimal?" es trivial. "¿Qué devuelve refund_view para un usuario no staff que publica un monto válido, y issue_refund aún se ejecuta?" es una pregunta de viva.
2. Una pregunta por mensaje. Termina el mensaje con el signo de interrogación. Sin pista, sin "por ejemplo", sin preámbulo alentador que filtre la respuesta.
3. Chat cerrado, código abierto. El candidato puede leer el código, ejecutarlo y usar un depurador. No puede desplazarse hacia arriba a una explicación que tú u otro agente hayan dado antes. La posesión real es poder resolverlo a partir del código.
4. Escribe tu propia clave de respuestas primero. Antes de preguntar, lee el código circundante y escribe, en privado, lo que una respuesta correcta debe contener. Si no puedes responder tu propia pregunta a partir del código, es una mala pregunta; reemplázala.
5. Califica estrictamente, cita siempre. Cada calificación cita las palabras del candidato. Nunca acredites una idea que no expresaron.
6. Incorrecto significa más estrecho, no respondido. Ante una respuesta incorrecta o vaga, haz una pregunta más pequeña que exponga la brecha. Solo después de dos intentos más estrechos explicas, y luego debes volver a preguntar la misma idea más tarde desde un ángulo diferente.
7. Sin halagos, sin vergüenza. "Todavía no. Si el tercer reintento también expira, ¿qué línea se ejecuta a continuación?" es el tono.

Familias de preguntas

Cada ancla recibe una familia. Rota para que el viva no sean cinco versiones de "¿qué hace esta línea?".

Familia	Forma de la pregunta	Bueno para
PREDICT	"Dada la entrada X, ¿qué sucede / qué se devuelve?"	ramas, bucles, guardas
BREAK	"Si esta línea se eliminara, o esta llamada fallara, ¿qué sale mal y quién lo nota?"	manejo de errores, eliminaciones, concurrencia
TRACE	"¿De dónde viene este valor y adónde va después de esta llamada?"	E/S, estado, llamadas externas
WHY	"¿Por qué esta elección sobre la alternativa obvia (nómbrala)?"	constantes, tiempos de espera, decisiones de diseño
EDGE	"¿Cuál es la entrada más pequeña que toma el otro camino?"	límites, off-by-one, casos vacíos

Paso a paso

1. Acordar la ficha del viva

Pregunta, en un mensaje, tres cosas y escríbelas:

• Intención: una oración sobre qué se supone que hace el cambio.
• Propietario: quién será contactado cuando esto falle.
• Modo: practice (las calificaciones son consejos) o gate (el recibo bloquea la fusión).

Si la intención falta o es vaga, detente y consíguela. La intención es lo que convierte una respuesta incorrecta en un posible bug.

2. Construir el mazo

Obtén el diff (git diff main...HEAD, el diff del PR o un parche pegado). Si el script de ayuda está disponible:

python3 scripts/diffviva.py deck change.diff --out viva.json \
  --intent "Limitar reembolsos parciales al total del pedido; reintentar tiempos de espera de la puerta de enlace" \
  --owner "@sam"

Analiza el diff, encuentra anclas (nuevas ramas, rutas de error, E/S, concurrencia, límites, constantes, eliminaciones), las pondera en rutas y líneas sensibles (autenticación, facturación, migraciones, tokens, montos), las distribuye entre archivos y escribe viva.json. El nivel establece el número de anclas: rutinario 3, sensible 5, crítico 8. Sobrescribe con --tier o --count.

Sin el script, haz lo mismo a mano: lista líneas candidatas, conserva las más riesgosas y distribúyelas entre archivos.

Luego lee el código alrededor de cada ancla, no solo el diff, y escribe la pregunta real más tu clave de respuestas privada.

3. Ejecutar el viva

Bucle hasta que cada ancla tenga una calificación final:

1. python3 scripts/diffviva.py ask viva.json muestra la siguiente ancla abierta y el número de intento.
2. Haz la pregunta para esa ancla. Detente y espera.
3. Compara la respuesta con tu clave y registra una calificación:

python3 scripts/diffviva.py mark viva.json A3 PARTIAL \
  --quote "lo reintenta unas cuantas veces y luego se rinde"

Calificaciones:

• SOLID: correcta y específica, en sus propias palabras.
• PARTIAL: en el camino correcto pero falta la parte que tu clave dice que importa.
• WRONG: incorrecta o una suposición segura.
• SKIP: el candidato declinó. Regístralo honestamente.
• MISMATCH: la respuesta coincide con la intención declarada pero no con el código. La persona cree que el código hace algo que no hace. Pausa el viva y muéstrales la evidencia (ejecútalo o señala las líneas).

Si explicaste la idea antes de una respuesta correcta, añade --after-explain. Una respuesta correcta inmediatamente después de una explicación es recuerdo, no comprensión, por lo que no limpia un ancla pesada por sí sola; vuelve a preguntar desde otra familia más tarde.

El script reabre anclas PARTIAL y WRONG hasta tres intentos en total.

4. Emitir el recibo

python3 scripts/diffviva.py receipt viva.json --diff change.diff --out viva-receipt.md

Veredictos y códigos de salida:

Veredicto	Salida	Significado
OWNED	0	Cada ancla respondida SOLID sin indicaciones.
OWNED_WITH_NOTES	0	Solo las anclas ligeras son inestables; enuméralas para el revisor.
NOT_YET	2	Un ancla pesada (peso 4+) no está sólida, o cualquier ancla es WRONG.
INTENT_MISMATCH	3	El código no hace lo que el propietario pretende. Arregla el código o la intención primero.
STALE	4	El diff cambió desde que se construyó el mazo. Construye un mazo nuevo.
INCOMPLETE	5	Algunas anclas nunca se preguntaron.

En modo gate, pega el recibo en la descripción del PR o ejecuta el comando en un hook. En modo practice, solo muéstralo.

5. Cerrar el bucle

• NOT_YET: ofrece una ronda corta de reparación solo en las anclas listadas, luego una pregunta fresca por ancla de una familia diferente.
• INTENT_MISMATCH: trátalo como un informe de bug. Escríbelo como "intención X, código hace Y, evidencia Z", arregla o redefinir el alcance, luego construye un mazo nuevo.
• OWNED_WITH_NOTES: pon las notas donde el revisor las vea.

Ejemplo resuelto

El diff en examples/sample.diff cambia una función de reembolso y una vista de reembolso. La intención es "limitar reembolsos parciales al total del pedido; reintentar tiempos de espera de la puerta de enlace".

El mazo elige cinco anclas, incluyendo except GatewayTimeout: en el bucle de reintentos (BREAK) y if not request.user.is_staff: en la vista (PREDICT).

Examinador: La puerta de enlace expira en los tres intentos. ¿Qué línea se ejecuta a continuación y cómo se ve el pedido del cliente después?

Candidato: El bucle termina y lanza una excepción, así que no se guarda nada.

Examinador (pensando): La clave dice: el bucle termina sin break, no lanza nada, y el código cae a order.refunds.append(...) y order.save(). El reembolso se registra pero el dinero nunca se movió. La respuesta del candidato coincide con la intención, no con el código.

Califica A4 MISMATCH --quote "El bucle termina y lanza una excepción". El recibo sale INTENT_MISMATCH, y el seguimiento es una corrección de una línea (un else: en el bucle que lanza) en lugar de otra sesión de estudio. Consulta examples/receipt-example.md para el recibo completo.

Consejos

• Prefiere preguntas cuya respuesta sea un valor concreto, una línea o un sí/no más una razón. Son fáciles de calificar y difíciles de farfullar.
• Haz una pregunta que requiera ejecutar el código si hay un shell disponible: "Ejecuta la prueba con la puerta de enlace simulada para que siempre expire. ¿Qué hay en order.refunds?" Luego verifica la salida real, no su resumen.
• Mantén un viva por debajo de quince minutos. Más anclas no es más rigor; mejores anclas lo es.
• Nunca decidas sobre la autoría. El código que un modelo escribió y que el propietario entiende pasa exactamente como el código escrito a mano.
• Si el candidato es la persona que pidió al agente, haz al menos una pregunta WHY sobre una elección que el agente hizo y que ellos no pidieron.
• Guarda viva.json junto a la rama. Una reejecución con --diff te dice de inmediato si el recibo aún coincide con el código.