## Tipo de feedback suggestion ## Qué intentabas conseguir Sostener una investigación larga (evidence -> propose -> review -> cold-read -> consolidate) sobreviviendo a compactaciones de la sesión del agente. ## Qué ocurrió El recorrido exige reconstruir estado grande (claims, inventario semántico, target, fingerprints de overview, revisiones) entre llamadas separadas por minutos; en una sesión real de investigación con varias compactaciones, los payloads grandes y las respuestas eco dominan el coste y degradan la precisión. Además, el skill no documenta en sus referencias los contratos exactos de las operaciones (qué devuelve cada una, qué fingerprint hay que devolver, qué parámetros son obligatorios, precondiciones), de modo que se descubren por prueba y error. ## Qué esperabas Una operación que devuelva un estado compacto y rehidratable de la investigación (resumen, identificadores, fingerprints, revisiones) utilizable tras una compactación sin releer el artefacto completo; y referencias del skill con los contratos exactos de entrada, salida y precondiciones de cada operación. ## Contexto técnico seguro - Context Architecture version: 0.3.5.2+8bd0bc6bef - OS/runtime family: Windows / .NET 10.0.12 - Telemetry schema version: 1.0.0 - Surface: mcp - Operation: investigation_get ## Utilidad / impacto Menos compactaciones y menos llamadas de reconocimiento en investigaciones largas, y menor riesgo de operar con estado obsoleto. ## Información adicional voluntaria _Draft preparado localmente por Context Architecture. No incluye telemetry raw, paths, repositorios, prompts ni cuerpos de conocimiento automáticamente._ --- ## Plan coordinado #135 + #136 — contrato de contexto manejable > **Estado:** diseño acordado para planificar; **sin implementación iniciada**. > **Documento rector:** este #135. **Complementario:** [#136](https://gitlab.com/miguelsierra/context-architecture/-/work_items/136), que valida reducción del eco MCP, respuestas selectivas y referencia a fichero. > **Decisión del taller (2026-10-14):** persistencia progresiva guiada por el skill + lectura/verificación compacta del estado realmente persistido. Un sistema nuevo de checkpoints **no** entra en esta iteración: primero medir y aprender. > **Entrega:** una rama y una MR conjunta, dos issues abiertos hasta validar sus criterios; Linux, seguridad y paquete, pero **sin Windows ni release** hasta la publicación conjunta. ### 1. Objetivo y principios de diseño Context Architecture existe para convertir volúmenes grandes de información en **contextos manejables para agentes y personas**, preservando todo el conocimiento material sin exigir tenerlo entero en memoria de trabajo. - **Persistir, no mantener en la conversación:** evidencias materiales y resultados verificables se guardan incrementalmente en la InvestigationCase; el agente continúa con identificadores, dudas abiertas y próximo paso. No confundir «guardar» con «borrar tokens» de la conversación actual. - **Una sola autoridad:** la ficha compacta de estado se deriva siempre del documento existente. No añadir un segundo estado durable, cache semántica, sesión paralela ni snapshot inventado por el agente. - **Lectura progresiva, nunca pérdida:** acuse compacto por defecto en mutaciones; consulta explícita y selectiva de evidencias/inventario/propuesta; acceso completo disponible bajo petición. - **Knowledge para utilizar, Evidence para justificar:** overview autocontenido con reglas, scopes, excepciones y límites materiales; detalle especializado en secciones navegables; provenance/historia en la parte final o enlazada. La redistribución del detalle nunca convierte una limitación material en información oculta ni delega al lector una investigación de las fuentes. - **Diferenciar operaciones:** rehidratación = recuperar situación/punto de continuación; relectura = consultar datos persistidos específicos; cold-read = lector independiente evalúa *solo* el overview y los criterios de comprensión. Una compactación no equivale a un cold-read ni lo sustituye. - **Compatibilidad controlada:** no modificar por sorpresa el modelo de Core, persistencia canónica, formato CLI \`--json\` ni controles de revisión/seguridad. Delimitar y documentar la evolución de los *payloads MCP* predeterminados y la vista completa explícita. ### 2. Flujo deseado guiado por el skill 1. Consultar primero ContextKnowledge y ContextArea; abrir InvestigationCase solo para gaps reales. 2. Explorar un bloque temático. Registrar **en lote**, mediante \`investigation_submit_evidence_batch\` (#138), las *EvidenceClaims* que sí sean materiales (fuente, locator, revisión, incertidumbre, scope, temporalidad). No persistir cada búsqueda, fichero o hipótesis casual. 3. Tras el acuse de escritura, obtener/verificar una **ficha de estado persistido**: investigationId, revisión efectiva, modo/estado, counts y paginación/identificadores selectivos, target, estado de propuesta, contradicciones/unknowns materiales, estado de gates/fingerprints **solo si están calculados y son vigentes**. Confirmar explícitamente qué claims/IDs quedaron escritos; no asumir que lo restante de la conversación está persistido. 4. Conservar activo un **plan de continuación corto**, con preguntas abiertas y siguiente bloque; no repetir cuerpos de evidencias que ya pueden recuperarse. 5. Volver a leer solamente la evidencia, inventario o propuesta necesaria por ID, filtro o páginas. Si aparece una contradicción, registrar su estado sin borrar los hallazgos previos ni declararla resuelta automáticamente. 6. Antes de una compactación prevista, cambio de fase o interrupción: persistir lo material nuevo y verificar que la revisión esperada y los IDs clave son recuperables. Si la compactación ya ocurrió, rehidratar desde \`investigation_get\` compacto y solicitar el detalle indispensable. 7. Reconciliar sin pérdida. Separar gates deterministas de cobertura de una pasada **cold-read independiente** sobre overview y criterios; auditar usando el \`overviewFingerprint\` exacto y rechazar fingerprints stale. Consolidar solo tras superar los gates. **Cadencia:** checkpoints *semánticos* (bloque de evidencia, cambio relevante, fase, reanudación), **no** temporizadores ni commits Git por evidencia. El skill guía y el sistema confirma persistencia; no incorpora un scheduler automático de checkpoints. ### 3. Contratos MCP propuestos (a concretar y testear antes de implementarlos) | Superficie | Respuesta por defecto | Lectura adicional bajo petición | |---|---|---| | \`investigation_get\` | \`view=state\` pequeño, suficiente para continuar tras compactación | \`evidence\`, \`inventory\`, \`proposal\`, \`full\`; filtros/paginación para colecciones | | \`investigation_submit_evidence\` / \`_batch\` | acuse, revision, IDs/contadores afectados y diagnósticos; **no** eco de InvestigationCase | \`responseMode=full\` cuando se requiera compatibilidad/inspección | | \`investigation_propose\`, \`set_*\`, \`close\` | acuse de la modificación y revisión efectiva; no duplicar la propuesta | respuesta \`full\` explícita si procede | | \`investigation_review\` | validez de gates, coverage, diagnósticos, estado/fingerprint y metadatos de cambios | \`view=coldRead\` entrega overview+criterios **una sola vez**; \`view=preview\` entrega diff; \`view=full\` mantiene la salida histórica | | \`investigation_consolidate\` | aplicado/no aplicado, rutas afectadas/restauradas, conflictos y diagnósticos | full/changeset bajo petición explícita | Los nombres exactos de parámetros/DTO siguen **propuestos**, no desplegados. Mantener \`investigationId\` (#137), \`expectedRevision\` y conflicto reintentable (#138), batch all-or-nothing, protección de secretos (#133) y política de paths. Nada de ecos que oculten diagnósticos o gates fallidos. No permitir que un acuse positivo de revisión signifique \`CanConsolidate=true\` si no es cierto. En \`propose\`, evaluar la entrada alternativa por referencia a un **fichero local del workspace**, mutuamente excluyente con texto inline: path autorizado, rechazo de traversal/symlink fuera de raíz, tamaño acotado, validación de contenido/secretos y protección frente a cambios concurrentes. No hacer lectura externa ni permitir que un fichero temporal actúe como nueva autoridad de conocimiento. Si requiere una complejidad incompatible con el primer corte, delimitarla como slice posterior del mismo alcance antes de cerrar #136. **Footprint:** preferir evolucionar tools actuales frente a añadir muchas tools nuevas. Presupuesto MCP actual de 16.000 B de catálogo y 1.300 B de descriptions; comprobar en CI el tamaño de input schemas y seguir la filosofía ST-K de progressive disclosure. Modo \`full\` de *respuesta* **no** es un perfil que oculta herramientas del catálogo. ### 4. Observabilidad, compactaciones y decisión futura sobre checkpoints **Señales existentes, verificadas:** las operaciones CLI/MCP tienen métricas de uso/latencia/errores; K5 observa **solo localmente**, bajo integración voluntaria con host \`opencode\`, buckets de capacidad/utilización de contexto. **No** registra automáticamente cada compactación. Un bucket alto **no prueba** que el host haya compactado. **Hipótesis de dogfooding:** «se producen varias compactaciones o reanudaciones con **poco avance semántico** entre ellas». Puede indicar que la estrategia de persistencia guiada por skill no basta y que merece la pena estudiar un checkpoint de recuperación más explícito. *No* tomar revisiones de fichero, número de llamadas o bytes como proxies suficientes de avance útil: hay escrituras idempotentes, reintentos y fases de reflexión sin nuevas claims. **Qué podemos observar/analizar sin contenido funcional:** - base de uso: operaciones \`get/state\` vs \`get/full\`, respuestas/previews, mutaciones, batch y errores/conflictos, duración; - tamaños **agregados o en buckets** de payload MCP y ratios frente a la versión base, en CI/dogfooding local, para 10/50/100 claims; - progreso **solo como señales acotadas derivables**: cambios de fase/gate, claims distintos registrados, inventario/coverage válido y consolidaciones; no comparar cuerpos, prompts, rutas ni almacenar IDs de investigación como dimensiones; - evento de compactación/reanudación **solo si una API documentada del host lo anuncia fiablemente**, con origen/capacidad/consentimiento explícitos. Hasta entonces declarar \`compaction signal = unavailable\`, sin deducirlo de presión de contexto. **Ruta de aprendizaje:** 1. Medir localmente baselines y casos reales; registrar cualitativamente si el agente logró retomar la tarea y cuánto tuvo que releer. 2. Cuando aparezca un patrón de compactaciones repetidas con progreso insuficiente, el skill puede **sugerir preparar feedback** con \`feedback_prepare\` para revisión de la persona, con un episodio concreto y sin autosubmit ni flood de drafts. 3. Compartir telemetry de producto **solo bajo consentimiento existente y para categorías autorizadas**. K5 no es shared; ampliar shared para compactaciones, payload buckets o correlación de progresos requiere propuesta independiente con revisión de privacidad, policy/schema y **reconsentimiento si corresponde**. No activar exportadores MCP ni recolectar prompts, cuerpos de conocimiento, source paths, session IDs o tokens exactos. 4. Tras evidencia repetida y dogfooding, decidir un **issue posterior** para un sistema de checkpoints autónomo, *solo si* la estrategia ligera resulta insuficiente. No implementarlo preventivamente ni fijar umbrales universales sin baseline. Este aprendizaje alimenta la filosofía de CA y puede informar #74/#75 (telemetry learning loop), sin mezclar usage metrics con autoridad semántica ni inventar resultados. ### 5. Plan de implementación en una rama/MR y gates - **Slice A — Contrato y baseline.** Inventario de operaciones, outputs reales, bytes UTF-8 y crecimiento con 10/50/100 claims; versionado/compatibilidad, límites por vistas y validación de esquema/footprint. Primero tests que fallen con el comportamiento actual. - **Slice B — Persistir y rehidratar.** \`get/state\` derivado del documento; verificación de revisión/IDs, colecciones accesibles selectivamente y reanudación tras reinicio del proceso. Skill instruye a escribir por lotes al cerrar una unidad material y comprobar el acuse. - **Slice C — Sin eco y lectura selectiva.** Mutaciones con acuse compacto; lectura por filtro/página; full opt-in. Respuesta acotada frente a número de evidencias y ningún crecimiento cuadrático acumulado por eco. - **Slice D — Review/cold-read/consolidation.** Vistas de gates, overview+criterios aislados, preview bajo petición, receipts de consolidación y compatibilidad del \`overviewFingerprint\`. Entrada opcional desde fichero con salvaguardas de seguridad. - **Slice E — Conocimiento y skills.** Guía de *persistencia progresiva*, recuperación, distinción relectura/cold-read, niveles de lectura humana/IA; **no reestructurar automáticamente** todos los ContextKnowledge existentes. Documentar para cada operación inputs, outputs, precondiciones, errores/recuperación y ejemplos reales de sesión compactada. - **Slice F — Evidencia y política de observabilidad.** Benchmarks/regresiones de payload, K5 local donde sea observable, dogfooding de compactaciones/reanudaciones, decisión documentada de «checkpoint avanzado por ahora no», propuesta de feedback revisable, límites de privacidad. **Aceptación conjunta mínima:** prueba real MCP y CLI de 10/50/100 claims; payload state/acks acotados y significativamente menores que los anteriores; listas grandes paginadas; no pérdida ni alteración de EvidenceClaims, inventarios o propuestas; revisión/reapertura en procesos distintos; compatibilidad \`full\`; \`expectedRevision\`, idempotencia, rechazo de secretos y rutas inseguras; test cold-read independiente y stale fingerprint; gates lossless inalterados; CI Linux, SAST, Secret Detection, \`verify_package\`, SBOM/instalación, control de footprint. ### 6. Cierre y exclusiones - Cerrar **#135 y #136 juntos** solo cuando se demuestren los criterios específicos de ambos y el dogfooding no revele regresiones. No utilizar el cierre de un issue como prueba automática del otro. - **Fuera de alcance ahora:** motor de checkpoints automáticos, nueva persistencia de sesión, cronómetros de guardado, commits por claim, deducción de compactaciones desde tokens altos, shared telemetry de contenido o consentimiento implícito, cambio automático del significado de notas canónicas. - **Publicación:** continuar política de esta tanda; verificar Windows y publicar únicamente durante la futura release conjunta.