Socratic Coding

Qué es

Un framework de trabajo para desarrollo con IA donde el humano mantiene ownership real del sistema — no solo del repositorio.

El nombre refleja el mecanismo central: el diálogo socrático entre humano e IA, donde las preguntas son tan importantes como el código generado. Sin comprensión no hay ownership. Sin ownership, el humano es un huésped en su propio proyecto.

Origen

Emergió orgánicamente durante el desarrollo del proyecto plomo.uy Edge Audio Intelligence (abril 2026). No fue diseñada a priori — fue identificada y formalizada post-facto como patrón repetible, a partir de una sesión de desarrollo de ~10 labs sobre un gateway ARM64 con restricciones reales de hardware.

---

El problema que resuelve

El vibe coding (descripción en lenguaje natural → código generado por IA → aprobación humana) tiene un defecto estructural: el humano no entiende lo que aprueba. Esto produce:

• Revisiones superficiales (“se ve bien, dale”)
• Bugs arquitectónicos que el humano no puede detectar
• Deuda técnica invisible
• Dependencia creciente de la IA para mantener el propio código
• Sin aprendizaje acumulable entre proyectos

El problema no es la IA — es que el humano queda afuera del loop cognitivo.

---

El insight central

Sin comprensión no hay ownership del sistema.

El aprendizaje no es el objetivo — es el mecanismo. Un humano que entiende lo que está mirando puede revisar, cuestionar y decidir. Uno que no entiende solo puede aprobar. La diferencia entre los dos define si el proyecto es tuyo o de la IA.

La teoría antes de la implementación no es documentación: es el prerequisito para que haya dos pares de ojos mirando el código, no uno.

Esto convierte el binomio humano-IA en colaboración simétrica:

• La IA aporta velocidad de generación y amplitud de conocimiento técnico
• El humano aporta contexto de negocio, validación en entorno real, y criterio

---

El ciclo

Basado en el ciclo de aprendizaje experiencial (Kolb, 1984), adaptado a desarrollo con IA:

┌─────────────────────────────────────────────────────┐
│  1. CLASE (conceptualización)                       │
│     La IA explica la teoría necesaria para          │
│     entender lo que se va a construir.              │
│     El humano hace preguntas, reformula,            │
│     conecta con conocimiento previo.                │
│     ⚠ La Clase es punto de partida, no verdad.     │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│  2. PLAN (formulación)                              │
│     La IA propone arquitectura y approach.          │
│     El humano aprueba, redirige o cuestiona.        │
│     Las decisiones y trade-offs quedan escritos.    │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│  3. LAB (implementación guiada)                     │
│     La IA genera el código.                         │
│     El humano lo lee entendiendo el contexto        │
│     de la Clase — puede detectar errores reales.    │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│  4. VALIDACIÓN en entorno real (experimentación)    │
│     El humano corre el código en el sistema real.   │
│     Los fallos son esperados y bienvenidos.         │
│     La IA diagnostica, el humano confirma.          │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│  5. CONSOLIDACIÓN (reflexión)                       │
│     Los fallos y fixes quedan documentados.         │
│     Las lecciones aprendidas se agregan al plan.    │
│     El humano puede explicar qué se hizo y por qué. │
└─────────────────────┬───────────────────────────────┘
                      │
                      └── siguiente módulo ──►

Al cerrar el proyecto completo (no cada módulo), se agrega un paso final:

┌─────────────────────────────────────────────────────┐
│  6. CIERRE (release)                                │
│     El código se empaqueta y documenta para         │
│     ser usado por otros sin contexto previo.        │
│     Se genera el documento de cierre del proyecto:  │
│     qué se hizo, qué resultados, qué quedó afuera.  │
│     El backlog de salida queda como input explícito │
│     del próximo ciclo.                              │
└─────────────────────────────────────────────────────┘

El CIERRE produce tres entregables:

• Release package: el código organizado, con READMEs de instalación y uso, listo para que alguien lo levante sin haber participado en ningún lab.
• Contratos de interfaz: la especificación de lo que cada componente expone hacia otros equipos o sistemas.
• Documento de cierre: qué se construyó, resultados medidos, backlog de salida categorizado. Es el Gate 4 del proyecto completo.

---

Gates (puntos de control no negociables)

Gate 0 — La Clase es punto de partida, no verdad La IA puede estar equivocada en la teoría. La Clase orienta — no reemplaza la validación con fuentes externas, documentación oficial, o prueba empírica. Si la teoría y la realidad divergen, la realidad gana siempre.

Gate 1 — Plan antes de código La IA describe intención y trade-offs antes de escribir una línea. El humano aprueba o redirige. Si el humano no entiende el plan, volver a la Clase.

Gate 2 — Entorno real como criterio de verdad No se declara éxito hasta validar en el entorno objetivo con sus restricciones reales (hardware, red, dependencias). Los entornos sanitizados mienten.

Gate 3 — Fallo documentado Cuando algo no funciona, el diagnóstico es un entregable, no un commit revertido. “Intentamos X, falló por Y, elegimos Z” tiene más valor a largo plazo que el código que finalmente funcionó.

Gate 4 — El humano puede explicar Criterio de cierre de cada módulo: el humano puede explicar a otro humano qué se hizo y por qué, sin leer el código. Si no puede, la Clase fue insuficiente.

---

Fricción real: cuándo saltarse pasos

Socratic Coding agrega overhead. En un módulo simple, la Clase puede tomar 20 minutos que en vibe coding no existen. Eso es el costo — y vale la pena ser honesto al respecto.

Cuándo reducir el ciclo:

• El humano ya domina el dominio → se puede acortar o saltar la Clase
• El módulo es mecánico y sin decisiones arquitectónicas → Lab directo con Gate 4 igual
• Prototipo descartable → validación informal alcanza

Cuándo no reducir:

• Decisiones que afectan la arquitectura futura
• Dominios completamente nuevos para el humano
• Código que otros van a mantener

La pregunta no es “¿tengo tiempo para la Clase?” sino “¿puedo permitirme no entender esto?”

---

Evidencia del proyecto de origen

Tres casos concretos donde el ciclo detectó problemas que el vibe coding hubiera pasado por alto:

1. ONNX INT8 no funciona para MobileNet en ARM La Clase de Lab 2 estableció que ONNX Runtime era el runtime estándar. La validación en hardware real (Gate 2) reveló que ONNX Runtime no tiene kernels NEON para convoluciones depthwise separables — la arquitectura exacta de YAMNet. Resultado: 9 variantes probadas, todas fallidas. La decisión de adoptar TFLite FP32 quedó documentada con diagnóstico completo, no como “cambio de enfoque” sin explicación. Speedup resultante: 6.8× (19ms vs 133ms).

2. -rtsp_transport tcp rompe archivos locales La Clase de Lab 7 explicó RTSPStream y el flag -rtsp_transport tcp para estabilidad de red. Al validar con archivo local (Gate 2), FFmpeg retornaba exit code 1. El humano, entendiendo el propósito del flag desde la Clase, identificó que era RTSP-específico. Fix: condicional por esquema de URL. Sin la Clase, el bug hubiera sido opaco.

3. Detector compartido entre threads sin lock La Clase de Lab 9 explicó el modelo de threads del pipeline antes de implementar el CommandSubscriber. Cuando se diseñó el reload_config, el humano preguntó explícitamente por la concurrencia — pregunta que no hubiera surgido sin entender el modelo de threads. Resultado: RLock con snapshot fuera del lock, diseño correcto desde el inicio.

---

Beneficio operacional: continuidad entre sesiones y entre equipos

Los artefactos del ciclo (Plan, TODO, Clase, Lab, contratos de interfaz) no son solo documentación pedagógica. Son el mecanismo por el cual el proyecto sobrevive el cierre de una sesión de IA.

Una instancia nueva de la IA puede retomar exactamente donde quedó leyendo los docs. Un desarrollador diferente puede incorporarse sin necesitar al autor original. Esto transforma la documentación de obligación a infraestructura.

El beneficio se extiende más allá de la continuidad individual: los contratos de interfaz permiten que equipos que nunca participaron en las sesiones implementen su parte de forma asíncrona y autónoma. El equipo cloud puede implementar los endpoints de Bedrock usando integracion-con-cloud.md sin haber estado presente en ninguna Clase ni Lab. No necesitan reconstruir el contexto — el contexto ya está escrito.

Esto convierte Socratic Coding en un mecanismo de colaboración distribuida, no solo de aprendizaje individual. El conocimiento que se construye en el diálogo humano-IA queda externalizado en documentos que otros equipos pueden consumir directamente.

---

Separación de artefactos

Artefacto	Captura	Ejemplo
Clase	El por qué — teoría, trade-offs, decisiones	Clase9.md
Lab	El cómo — pasos, comandos, validaciones	Lab9.md
Código	El qué — implementación	lab9_rtsp.py
Plan	El hacia dónde — arquitectura evolutiva	plan-plomo-edge-audio.md
TODO	El estado — completado vs. pendiente	TODO.md
Backlog de salida	Lo que quedó afuera — deuda, ideas, próximos sprints	sección en TODO.md
Contrato de interfaz	El borde — qué expone cada componente hacia otros	integracion.md

Los siete son distintos. Colapsar alguno degrada el sistema.

Contrato de interfaz — artefacto obligatorio en proyectos multi-componente

En proyectos con más de un componente (edge, gateway, cloud, frontend), cada frontera de integración necesita su propio contrato. No es una Clase — no explica teoría. No es un Lab — no tiene pasos. No es un Plan — no traza dirección. Es la especificación de lo que un componente expone hacia otro: topics MQTT, payloads JSON, endpoints REST, contratos de QoS, comportamiento ante fallos.

El contrato de interfaz es el documento que permite que dos equipos trabajen en paralelo sin coordinación constante. Si está bien escrito, el equipo que implementa el otro lado no necesita preguntar nada.

Backlog de salida — artefacto obligatorio al cerrar un módulo

Al cerrar cada módulo o sprint, el ciclo debe producir explícitamente una lista de lo que quedó fuera de scope, no se resolvió, o requiere una metodología diferente. No es una lista de fracasos — es el input del próximo ciclo.

Tres categorías:

• Deuda técnica: decisiones conscientes de tomar un camino más rápido sabiendo que hay uno mejor. Ej: TFLite INT8 bloqueado, thresholds sin calibrar.

• Ideas descartadas por scope: funcionalidades válidas que no entraban en este sprint. Ej: noise level monitor (dBFS), calibración con audios etiquetados.

• Pendientes de otra metodología: problemas que Socratic Coding no puede resolver solo — requieren investigación formal, pruebas con usuarios, decisiones de negocio, o un equipo más grande. Documentar explícitamente por qué quedan fuera.

El backlog de salida es lo que convierte un proyecto terminado en un proyecto continuable.

---

Para qué proyectos aplica

Aplica bien:

• Proyectos exploratorios donde el path no está claro de antemano
• MVPs en dominios nuevos para el desarrollador
• Proyectos con restricciones técnicas no triviales (hardware limitado, integraciones complejas)
• Proyectos que otros van a mantener o continuar

No aplica bien (o es overkill):

• Features de negocio rutinarias en dominios conocidos
• Proyectos con spec completamente definida antes de empezar
• Prototipos descartables sin continuidad

---

Lo que NO es

• No es una metodología nueva completa — funciona sobre cualquier base (Agile, etc.)
• No es un proceso de documentación — la documentación es subproducto, no objetivo
• No es vibe coding estructurado — el objetivo es ownership, no velocidad
• No reemplaza el criterio del desarrollador — lo amplifica
• No garantiza que la IA no se equivoque — garantiza que el humano pueda detectarlo

---

Diferencia con vibe coding

	Vibe coding	Socratic Coding
Rol humano	Aprobador pasivo	Co-arquitecto activo
Revisión de código	Superficial	Informada por la Clase
Fallos	Obstáculos	Entregables
Documentación	Afterthought o ninguna	Infraestructura del proyecto
Resultado	Código que funciona	Sistema que el humano entiende
Deuda técnica	Alta (invisible)	Baja (registrada)