feat: Add native Learning Mode for contextual learning during AI-assisted development #3207

Before submitting

• I searched open and closed issues and did not find a request for this feature.
• I reviewed this request and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem or opportunity

Problem or opportunity

El desarrollo de software asistido por agentes de IA ha mejorado considerablemente la productividad. Actualmente es posible implementar funcionalidades complejas en una fracción del tiempo que habría requerido hacerlo manualmente.

Sin embargo, esta evolución también ha generado un problema:

La velocidad a la que los agentes producen código supera ampliamente la capacidad del desarrollador para comprender lo que están construyendo.

Tradicionalmente, el proceso de desarrollo implicaba investigar tecnologías, comprender conceptos, evaluar alternativas, resolver errores y tomar decisiones técnicas. Gran parte del aprendizaje ocurría naturalmente durante esas actividades.

Con los agentes de IA, muchas de estas responsabilidades se delegan. El desarrollador solicita una funcionalidad y el agente puede implementar múltiples archivos, introducir nuevas dependencias, aplicar patrones arquitectónicos, ejecutar pruebas y corregir errores de manera autónoma.

Aunque esto permite construir software más rápidamente, también puede generar una desconexión entre la capacidad de producir software y la capacidad de comprenderlo, mantenerlo y tomar decisiones informadas sobre él.

Los agentes suelen comunicar qué implementaron y si las pruebas resultaron satisfactorias, pero generalmente no explican de manera proactiva:

• Por qué eligieron determinada solución, tecnología o patrón de diseño.
• Qué conceptos técnicos intervienen en la implementación.
• Qué alternativas existían y cuáles son sus ventajas y desventajas.
• Cómo se relacionan los cambios con la arquitectura general del proyecto.
• Qué conocimientos necesita adquirir el desarrollador para comprender lo implementado.

Es posible solicitar estas explicaciones manualmente, pero hacerlo constantemente interrumpe el flujo de trabajo y reduce las ganancias de productividad.

El dilema actual

flowchart TD
    A["El desarrollador solicita una funcionalidad"]
    B["El agente implementa y verifica"]
    C{"¿Qué hace el desarrollador?"}
    D["Avanza rápidamente"]
    E["Se detiene a investigar y preguntar"]
    F["Mayor productividad, pero menor comprensión"]
    G["Mayor aprendizaje, pero menor velocidad"]

    A --> B --> C
    C --> D --> F
    C --> E --> G

Esto afecta especialmente a estudiantes y desarrolladores con experiencia limitada, aunque también puede resultar relevante para profesionales que trabajan con tecnologías, arquitecturas o proyectos desconocidos.

El objetivo sería reducir la necesidad de elegir constantemente entre productividad y aprendizaje.

Proposed outcome

Proposed outcome

Propongo incorporar a Gentle Shell una funcionalidad nativa, opcional y configurable denominada Learning Mode (Modo Aprendizaje o Modo Tutor).

Su objetivo sería transformar el desarrollo asistido por IA en una experiencia que permita no solamente construir software, sino también aprender progresivamente de las decisiones técnicas y las implementaciones realizadas por el agente.

La funcionalidad debería integrarse directamente con Gentle Shell, aprovechando su arquitectura y sus mecanismos de ejecución, configuración y presentación.

1. Activación y desactivación

Incorporar una opción dentro de /gentle:customize que permita activar o desactivar el modo de aprendizaje.

Por ejemplo:

Learning Mode
  Enabled:       [On / Off]
  Depth:         [Minimal / Balanced / Detailed]
  Explanations:  [Automatic / On demand]

Representación conceptual de las preferencias, no una captura de la interfaz actual.

La configuración debería ser persistente entre sesiones.

Cuando esté desactivado, Gentle Shell debería conservar su comportamiento habitual, sin intervenciones educativas adicionales.

2. Aprendizaje contextual automático

Cuando Learning Mode esté activado, Gentle Shell debería identificar oportunidades relevantes de aprendizaje durante el desarrollo.

Por ejemplo:

• Incorporación de nuevas tecnologías o dependencias.
• Aplicación de patrones de diseño.
• Decisiones arquitectónicas.
• Implementación de mecanismos de seguridad.
• Resolución de errores significativos.
• Introducción de conceptos técnicos relevantes.
• Decisiones que impliquen compromisos entre rendimiento, mantenibilidad, seguridad o complejidad.

No se trata de explicar cada línea de código ni cada operación del agente, sino de identificar las decisiones y los conceptos que realmente aportan valor educativo.

3. Explicaciones breves y no intrusivas

El modo de aprendizaje no debería transformar cada interacción en una clase ni interrumpir constantemente al agente.

La prioridad debe continuar siendo completar las tareas de desarrollo de manera eficiente.

Las explicaciones podrían aparecer al finalizar una implementación o un hito relevante.

Flujo de trabajo propuesto

flowchart TD
    A["El desarrollador solicita una tarea"]
    B["Gentle Shell implementa y verifica"]
    C["Learning Mode observa los resultados"]
    D{"¿Existe una oportunidad relevante de aprendizaje?"}
    E["Continúa el flujo habitual"]
    F["Genera una explicación breve y contextual"]
    G["El usuario comprende el cambio"]
    H["Puede profundizar si lo desea"]

    A --> B --> C --> D
    D -->|No| E
    D -->|Sí| F
    F --> G
    G --> E
    G -.->|Opcional| H

De esta manera, el agente continúa desarrollando normalmente y el aprendizaje se incorpora como una capacidad adicional del entorno.

Ejemplo de comportamiento

Sin Learning Mode:

Implementé autenticación mediante JWT y un middleware para proteger las rutas privadas. Las pruebas se completaron correctamente.

Con Learning Mode activado:

Implementación: Se agregó autenticación mediante JWT y un middleware para proteger las rutas privadas.

¿Por qué JWT? Permite verificar la identidad de un usuario mediante tokens firmados, sin requerir necesariamente una consulta a una sesión almacenada en el servidor para cada petición.

Concepto importante: Un middleware es una función que interviene durante el procesamiento de una petición. En este caso, comprueba si el usuario tiene autorización para acceder a una ruta.

Consideración: Los JWT requieren una gestión adecuada de expiración, almacenamiento y revocación.

El objetivo es proporcionar explicaciones pequeñas, relevantes y directamente relacionadas con el trabajo realizado.

4. Profundización bajo demanda

Además de las explicaciones automáticas, sería útil poder profundizar en decisiones anteriores sin perder el contexto de la implementación.

Por ejemplo, mediante un comando como /gentle:learn o una sección educativa dentro de Gentle Shell.

El desarrollador podría consultar:

• ¿Por qué se utilizó este patrón de diseño?
• ¿Qué problema resuelve esta dependencia?
• ¿Cómo funciona esta parte del código?
• ¿Qué alternativas podrían haberse utilizado?
• ¿Qué conceptos necesito entender para modificar esta implementación?

Estas consultas deberían utilizar el contexto real del proyecto, los archivos relevantes y las evidencias disponibles.

5. Niveles de aprendizaje configurables

Se podrían ofrecer diferentes niveles de profundidad:

El usuario podría ajustar la profundidad según sus conocimientos o preferencias.

6. Memoria educativa y aprendizaje progresivo

Como evolución posterior, Learning Mode podría incorporar un mecanismo para recordar qué conceptos fueron explicados anteriormente.

Esto permitiría:

• Evitar explicaciones repetitivas.
• Adaptar progresivamente el nivel de profundidad.
• Identificar conceptos que requieren mayor comprensión.
• Consultar un historial educativo relacionado con el proyecto.
• Proponer repasos opcionales.

Sería importante distinguir entre conceptos explicados y conocimientos realmente comprendidos. Una explicación no debería considerarse evidencia suficiente de aprendizaje.

7. Integración con el flujo de trabajo existente

La funcionalidad debería respetar estos principios:

• Development-first: el agente sigue priorizando completar las tareas.
• Learning-by-building: el aprendizaje surge del trabajo real del proyecto.
• Non-intrusive: evitar interrupciones educativas innecesarias.
• Context-aware: utilizar los cambios y las decisiones técnicas relevantes.
• Evidence-based: fundamentar las explicaciones en información verificable, sin inventar las razones de una decisión.
• Optional: el usuario conserva el control sobre su activación.
• Efficient: minimizar el impacto en el consumo de tokens, el contexto y los tiempos de desarrollo.

Possible architecture

Una posibilidad sería desarrollar un subsistema educativo integrado en Gentle Shell que observe la actividad del agente, identifique oportunidades de aprendizaje y presente explicaciones contextualizadas.

Arquitectura conceptual

flowchart TD
    A["Gentle Shell"]
    B["Agente principal"]
    C["Observador de ejecución"]
    D["Motor de aprendizaje"]
    E["Interfaz educativa"]
    F["Preferencias de Learning Mode"]
    G["Memoria educativa futura"]

    A --> B
    B -->|"Cambios, herramientas y resultados"| C
    C -->|"Información relevante"| D
    D -->|"Explicaciones contextualizadas"| E
    F -.->|"Activación y configuración"| C
    F -.->|"Profundidad"| D
    D <-.->|"Conceptos y progreso"| G

Esta arquitectura es conceptual. No pretende imponer componentes o tecnologías específicas.

La idea central es separar la ejecución de las tareas de desarrollo del procesamiento educativo, de forma que el modo de aprendizaje no interfiera innecesariamente con el trabajo del agente principal.

Gentle Shell ya dispone de extensiones de Pi, mecanismos de observación de eventos y una interfaz de configuración mediante /gentle:customize, que podrían estudiarse como posibles puntos de integración.

La generación de explicaciones podría realizarse utilizando el propio modelo o un componente especializado, según lo que resulte más adecuado para la arquitectura existente.

También sería importante evitar que las explicaciones atribuyan al agente razonamientos que no estén documentados. Si no existe evidencia de por qué se tomó una decisión, el tutor debería explicar sus fundamentos técnicos y alternativas sin inventar una justificación histórica.

Alternatives considered

Alternatives considered

Instrucciones permanentes al agente

Una alternativa sería agregar instrucciones globales para que el agente explique sus decisiones después de cada implementación.

Aunque esto permitiría obtener parte del comportamiento deseado, dependería del cumplimiento de las instrucciones por parte del modelo y podría incrementar innecesariamente el contexto de trabajo.

Tampoco ofrecería por sí solo una infraestructura para observar eventos, administrar preferencias, conservar historial educativo o controlar la frecuencia de las explicaciones.

Tutor externo independiente

Otra alternativa sería desarrollar una herramienta educativa completamente independiente del entorno principal.

Sin embargo, el objetivo es que esta capacidad forme parte de la experiencia de Gentle Shell y aproveche directamente el contexto de sus sesiones, herramientas y cambios.

Esto no excluye que internamente pueda utilizarse un componente especializado, siempre que la funcionalidad se presente al usuario como una integración nativa.

Additional context

Additional context

Motivación

Esta propuesta surge de una experiencia personal como estudiante de Ingeniería en Sistemas y usuario de agentes de programación.

Gracias a la IA, actualmente puedo construir proyectos y funcionalidades que anteriormente habrían requerido conocimientos técnicos mucho más avanzados.

Sin embargo, muchas veces, al finalizar una tarea, descubro que el agente implementó correctamente algo que no comprendo del todo.

Para entenderlo tengo que detener el desarrollo, inspeccionar archivos y solicitar explicaciones adicionales. Repetir este proceso en cada implementación hace que los tiempos de trabajo aumenten considerablemente.

Como resultado, termino enfrentando una elección poco deseable: avanzar rápidamente en mis proyectos sin comprender completamente lo implementado, o invertir mucho tiempo en estudiar cada cambio.

Creo que una herramienta capaz de integrar el aprendizaje dentro del proceso de desarrollo podría reducir esta dificultad.

Alcance inicial sugerido

Para evitar una implementación excesivamente compleja, una primera versión podría limitarse a:

1. Activar y desactivar Learning Mode desde Gentle Shell.
2. Detectar oportunidades educativas al completar hitos relevantes.
3. Generar explicaciones breves basadas en evidencias del trabajo realizado.
4. Permitir profundizar manualmente cuando el usuario lo considere necesario.

La memoria educativa, la adaptación progresiva y otras funcionalidades avanzadas podrían desarrollarse posteriormente.

La propuesta está enfocada exclusivamente en Gentle Shell.

Objetivo final

Que los agentes de IA no solamente ayuden a los desarrolladores a construir software más rápidamente, sino que también les permitan comprender progresivamente lo que están construyendo, sin obligarlos a elegir constantemente entre productividad y aprendizaje.