feat(communication): configurable clarity layer for user-facing replies, plans, and docs

[nachosag]

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

Cuando el agente explica un problema, una decisión, un plan o un resultado, su respuesta está calibrada para otro desarrollador que ya comparte su modelo mental y su vocabulario interno. Entiendo cada palabra por separado, pero no construyo una comprensión clara de lo que está diciendo: tengo que traducir mentalmente cada respuesta antes de poder usarla.

No es un problema de tono, ni de personalidad, ni de "inglés vs. español", y no pido que el agente sea menos técnico ni que elimine profundidad. Lo que falta es una capa que ordene la explicación para la persona que supervisa.

Qué es y qué no es este problema

Dimensión	¿Está regulada hoy?	¿Es el problema reportado?
Personalidad / tono (rioplatense vs. neutral)	Sí — prompt de persona	No
Estilo de comunicación (registro, voseo, calidez)	Sí — prompt de persona	No
Claridad pedagógica (qué pasó → por qué → impacto → opciones)	No	Sí
Jerga técnica sin explicación previa	No	Sí
Estructura y densidad de la información	Solo "síntesis corta"	Sí
Distinción estado interno del workflow vs. información para decidir	No	Sí

Probé las dos Personas disponibles (Gentleman y Neutral): el problema de comprensión persiste con ambas, porque ninguna de las dos regula los cuatro ejes marcados. No tengo paquetes de terceros que transformen el output del agente (Caveman, I Have ADHD, Ponytail, u otros no están instalados), así que el comportamiento no se explica por una interacción con otra extensión de personalización.

Evidencia: una sesión exportada (2026-09-26)

Setup: gentle-pi 3.7.0 (subió de 2.7.0 durante la sesión), Pi 0.87.1, Linux, sin paquetes de terceros que alteren el output. 49 respuestas del agente, sin code blocks en el conteo:

Métrica	Valor
Respuestas que narran vocabulario interno del review (lineage, lens, forecast, acknowledgement, authority, slot, closure, controller-only)	15 / 49
lens / lineage / acknowledgement	15 / 6 / 3
shim / lockfile / host / store / override	15 / 14 / 13 / 12 / 12
Chequeos de comprensión ("¿se entiende?", "¿te queda claro?")	0
Respuestas que contienen siquiera una pregunta al usuario	2

Ejemplos representativos (citas textuales, paths abreviados):

1. Internals antes que la situación. Pregunto "que es esto?" por un warning al arrancar. La respuesta arranca con el path del archivo y el código fuente de la extensión; el significado para el usuario recién aparece en la cuarta sección, "Consecuencia real":

   La lógica está en: ~/.pi/agent/npm/node_modules/.pnpm/pi-web-access@0.31.0.../tool-activation.ts
   Si el gate falla, printea el warning y cae al modo eager.

2. Jerga sin explicación previa. Un mismo párrafo encadena peer dependency, host, lockfile, peer y gate sin aclarar qué es cada uno ni qué consecuencia tiene para mí:

   … declaran el host como peer dependency con rango '*': pnpm auto-instaló ese peer una vez, cuando el lockfile se creó, y lo resolvió a 0.86.0. Ese es el valor congelado que lee el gate.

3. Demasiada información por oración. Varias relaciones causales, calificadores y conceptos en dos oraciones que tengo que descomponer a mano:

   Los "referenciados" son symlinks dentro de otros huérfanos (viejos gentle-engram@0.1.14 y una variante stale de 0.1.15 resuelta contra 0.86.0), no desde el árbol vivo. No los toco: borrarlos exige calcular el cierre transitivo y si me equivoco te rompo el pi entero.

4. Contexto implícito. El agente referencia su propio razonamiento anterior como si ya compartiéramos las abstracciones:

   mi regex de hermanos no baja un nivel en los paquetes con scope (@aws-sdk/*, @ast-grep/*, @earendil-works/*)
   No voy a GC a mano un árbol del que dependen tus tools.

5. Estado interno del agente comunicado como si fuera el resultado. Durante la revisión automática, la narración pública es literalmente el estado del controller:

   Lineage creado (review-…), estado reviewing, tier medio, lens review-reliability. No vino envelope de consentimiento pendiente — el siguiente paso es status.
   Forecast del slot (no corrió nada, mutation_performed: false) … Un solo model run, sobre el lens review-reliability, contra los dos archivos del candidate. Lo autorizo.
   El acknowledgement es controller-only: rechaza input. Reenvío solo el lineage.
   Authority quemada. No emito más STATUS.

   Y el cierre que se me presenta como resumen del trabajo es un bloque de estado interno:

   lineage:   review-…
   tier:      medium          lens: review-reliability
   estado:    approved → authority: burned
   evidence:  gentle-ai.review-acknowledged/v1
   

6. Inglés completo dentro de frases en español. No son nombres de API ni comandos, son cláusulas enteras de la explicación:

   el receipt lo marca explícitamente como trabajo separado: no reabre el review ni ofrece corrección
   El closure da la continuación exacta de acknowledgement; la confirmo contra STATUS antes de ejecutarla.

Contra-ejemplo dentro de la misma sesión: el agente a veces lo hace bien. Una respuesta posterior usa el orden que necesito — "## Lo que pasó" → "## Verificación" (tabla) → "## Dos cosas que encontré y no toqué" → "## Rollback", y otra presenta "## Opciones" en tabla con riesgos y "Yo iría con A". La capacidad existe; el problema es que no es el default.

Por qué afecta la supervisión humana del agente

• No puedo aprobar un plan que no puedo parafrasear en mis propias palabras. Si la intención del cambio no queda clara, la aprobación es un acto de fe, no una revisión.
• La información que necesito para decidir (qué pasó, por qué, qué impacto tiene, qué opciones hay, qué se recomienda) sí está en la respuesta, pero dispersa entre detalle de mecanismo, así que el esfuerzo cognitivo va a armar el relato en vez de evaluar la decisión.
• Me falta la separación entre estado interno del workflow (útil para depurar el harness) e información útil para la persona que supervisa (la que me deja auditar).
• El mismo registro gobierna los planes y la documentación que escribe el agente. Si la doc sale en este formato, el revisor no puede mantenerla: la documentación tiene que ser comprensible para la persona que la va a cuidar. (Esta sesión no escribió documentación; el punto es estructural, no una cita.)

Jerga necesaria vs. innecesaria

Necesaria (mantener, con glosa de una línea al primer uso)	Innecesaria para decidir (resumir; dejar el detalle opcional)
peer dependency, lockfile, corepack, shim, store, override, runtime — nombres reales del dominio pnpm/Node	lineage, lens, forecast, acknowledgement, authority burned, controller-only, slot materializable, candidate, closure, binding — estado interno del review

No se pide eliminar la segunda columna: se pide que la traducción al humano venga primero ("la revisión automática aprobó los 2 archivos; abajo está el detalle del protocolo") y que el detalle siga disponible.

Orígenes probables (con evidencia, sin atribuir sin comprobar)

1. Contenido del prompt de persona (alta confianza). GENTLEMAN_PERSONA_PROMPT y NEUTRAL_PERSONA_PROMPT (extensions/gentle-ai.ts:1232-1249, gentle-pi 3.7.0) regulan tono, idioma y regionalismo; ambos comparten "Be direct, technical, and concise" y "senior architect and teacher". Ninguno de los dos dice nada sobre orden de la explicación, densidad por oración, glosa de jerga ni audiencia. Explica por qué cambiar de Persona no cambia la comprensión. Además, en el canal de Pi no existe ni el Response Length Contract que sí tiene el output style de Claude.
2. Regla de síntesis del harness (alta confianza). assets/orchestrator.md:15: "Keep synthesis short by default: decision, outcome, next action." Optimiza respuestas cortas, no comprensibles; ningún lado del prompt pide orden pedagógico.
3. Contratos inyectados escritos para la máquina (confianza media-alta). El prompt de identidad + orchestrator + contrato de review se anexan al system prompt (extensions/gentle-ai.ts:9259) en vocabulario de proveedor, sin instrucción de re-codificarlos para el humano. Existen precedentes acotados que muestran que el principio ya se conoce y se aplica en forma puntual: se prohíbe exponer códigos internos en labels de envelopes de consentimiento (assets/orchestrator-delegation.md:24) y el propio código documenta "Names the situation before the mechanism" para un error dirigido al operador (extensions/gentle-ai.ts:5200). Cubre las 15 respuestas con vocabulario de review.
4. Jerga de dominio (alta confianza, ajena a Gentle). lockfile, shim, store, corepack, gate, eager, drift vienen del registro técnico de pnpm/Node y del modelo, no del harness. Es un eje separado: se arregla glosando, no cambiando el workflow.
5. Capacidad de claridad existe pero es opt-in (alta confianza). gentle-pi ya envía skills que codifican buena redacción: cognitive-doc-design (docs orientadas a revisión), comment-writer (comentarios de colaboración: "be useful fast", "explain why", fórmula observación → por qué → acción) e issue-creation. Todas se activan por trigger, no son el default y no cubren las explicaciones corrientes ni la narración de progreso. La sesión analizada no cargó ninguna: 0 lecturas de SKILL.md en 126 llamadas a herramientas.

Descartado con evidencia: elección de Persona (probada ambas), paquetes de terceros que transformen output (ninguno instalado) y la hipótesis "el modelo es demasiado técnico" como causa única (la misma sesión explica bien otras partes).

Proposed outcome

Una forma configurable de priorizar la claridad, el contexto y el lenguaje natural para la persona que supervisa, aplicable a las tres superficies que escribe el agente: respuestas conversacionales, planes/tasks y documentación generada.

Comportamientos observables que debería producir (no son una implementación, son el contrato de salida):

1. Orden por defecto: qué pasó → por qué pasó → qué impacto tiene → qué opciones existen → qué se recomienda y por qué → detalle técnico opcional.
2. Cada término nuevo, glosado o definido a la primera aparición; la jerga de dominio se conserva, no se elimina.
3. Estado interno del workflow separado de la información necesaria para decidir; el protocolo va al detalle, el resultado va primero.
4. Una relación causal principal por oración; sin apilar calificadores.
5. Referencias explícitas a lo que ya se compartió ("el lockfile interno de pnpm", no "ese tree" / "la variante stale").
6. Preguntas de verificación de comprensión cuando la explicación es larga (hoy: 0 en 49 respuestas).
7. Profundidad técnica intacta: disponible en la sección de detalle o bajo pedido, nunca recortada por defecto.

Observación adicional: hoy la claridad depende de que el agente cargue una skill por trigger, o de suerte. Si comment-writer y cognitive-doc-design ya codifican estas reglas, el salto natural es que sus principios (no el archivo completo) vivan en la capa always-on — prompt de persona o un contrato de comunicación compartido — para que apliquen a respuestas, planes y docs sin que nadie tenga que pedirlos.

No propongo un mecanismo concreto: el diseño queda en manos de los maintainers. Dejo anotados los canales que ya existen y podrían alojarlo (el prompt de persona de Pi, los output styles, la skill cognitive-doc-design) solo como referencia de que no haría falta inventar una superficie nueva.

Alternatives considered

• Cambiar de Persona: probado con Gentleman y Neutral; el problema persiste en ambos.
• Invocar cognitive-doc-design / comment-writer a mano en cada request: son opt-in por trigger, hay que pedirlos en cada turno, y no cubren la narración de progreso de una tarea en curso.
• Pedir "explícalo más simple" mensaje por mensaje: funciona puntualmente, no escala y no persiste entre sesiones.
• Reducir el contenido técnico: descartado directamente — bajaría la capacidad de auditoría, que es justamente lo que quiero mejorar.

Additional context

• Versiones observadas: gentle-pi 2.7.0 → 3.7.0 (misma sesión), Pi 0.87.1, Ubuntu 24. La sesión exportada está disponible si a los maintainers les sirve como evidencia.
• Relacionadas (otro repo, otro eje): Gentleman-Programming/gentle-ai#333 (gobernanza de longitud de respuesta — verbose ≠ incomprensible) y Gentleman-Programming/gentle-ai#789 (paridad Gentleman/Neutral). Los output styles viven en gentle-ai; el prompt de persona de Pi vive en este repo, por eso el reporte va acá.
• Non-goals: no pedimos tono más suave, menos inglés, menos técnica, ni una personalidad nueva. Pedimos legibilidad y revisabilidad humana como propiedad configurable, sin sacrificar profundidad.