context doctor, lee lo que marca y prepara una limpieza que arregla la capa sin nunca borrar ni fusionar Knowledge por iniciativa propia.
La regla de principio a fin: un agente (o un member) inspecciona, propone y archiva. Los movimientos destructivos y de autoridad (integrar en Knowledge, consolidar, borrar) esperan a que un owner o admin los pida.
Resultado
Un workspace cuyo contexto vuelves a poder confiar: claims stale triados, duplicados reales marcados para consolidar, Topics sin archivar con un hogar, y todo lo incierto aparcado para un humano, sin destruir Knowledge en el camino.Cuándo usarlo
- El retrieve devuelve resultados stale o fuera de tema y quieres saber por qué.
- Estás por apoyarte fuerte en la capa de contexto y quieres revisar su salud primero.
- Higiene periódica: el vault creció y sospechas drift y duplicación.
Disponibilidad y prerrequisitos
Necesitas la CLI instalada y con login. Auditar y proponer son de nivel member; consolidar, borrar e integrar en Knowledge son actos de owner/admin.
Objetos involucrados
Antes de empezar
Corre la auditoría. Cuenta y nombra lo que necesita atención, así triás desde evidencia, no desde una corazonada.- stale: el código bajo el anchor del topic cambió; el porqué registrado quizá ya no se sostiene.
- orphaned: el repo al que el topic ancló ya no está.
- zombie: los globs del anchor coinciden con cero archivos, un anchor que apunta a la nada.
- draft / proposed: una Nota o un topic En revisión, todavía no Knowledge. No es un defecto, solo sin bendecir.
- duplicate: comparte un título o un set de anchors idéntico con otro topic. Quizá el mismo concepto, quizá no.
- unassigned: archivado en ninguna área, donde se pudren los vaults.
- mis-shaped: un field malformado (por ejemplo un
howque es un doc pegado en vez de una nota corta).
Context preflight
Nunca repares un Topic que no leíste. Antes de tocar un topic marcado, carga el claim, su actividad reciente y el código que ancla, así juzgas desde evidencia.Workflow paso a paso
1
Prioriza por impacto
Ordena el trabajo antes de hacerlo. Un topic
reviewed en stale sobre un hot path desorienta a los agentes ahora, así que gana sobre un draft sin tocar. Atiende primero el drift en Knowledge, luego los duplicados, luego las notas sin archivar y mis-shaped.2
Tría un Topic stale: anchor drift vs content drift
Compara el claim contra el código que gobierna, y decide qué tipo de drift es.Anchor drift: el glob ahora coincide con los archivos equivocados o con ninguno. El arreglo es re-anclar (ajustar el pattern), una edición de topic que, para un topic
reviewed, re-confirma un owner o admin. Content drift: el código cambió cómo funciona el área, así que el porqué registrado está mal. El arreglo es una Edición sugerida.3
Corrige un claim stale con una Edición sugerida
Para una corrección comprobable a Knowledge, abre una Edición sugerida. Lleva el trigger y el rationale en el summary y el cambio en el content, y un humano la integra.Si no estás seguro de que el claim esté mal, deja un Comment en el field en vez de un parche, y deja que un humano decida.
4
Consolida un duplicado real, solo si es el mismo concepto
Un título compartido es una pista, no una prueba. Lee ambos topics; consolida solo cuando de verdad cubren un concepto. La consolidación es destructiva (archiva la fuente), así que previsualízala y córrela solo cuando un owner o admin lo pida.Si los dos solo comparten un nombre pero cubren conceptos distintos, retitula uno en vez de fusionar.
5
Archiva un Topic sin asignar en el Área correcta
Un topic sin archivar pertenece a un dominio real, no a uno inventado sobre la marcha. Lista las áreas existentes, luego archívalo en la que encaja.
Estados esperados
Knowledge write-back
La limpieza misma produce aprendizaje que vale conservar, enrutado igual que cualquier otro:- Una corrección a un claim existente es una Edición sugerida, no una reescritura en el lugar.
- Una incertidumbre es un Comment en el field, para que la ambigüedad llegue a un humano en vez de adivinarse.
- Una regla de higiene recurrente que descubres (una convención de nombres, un pattern de anchor que el equipo sigue equivocando) puede volverse una Nota, y después Knowledge tras revisión. No escribas los hallazgos de la auditoría en sí en Knowledge; son estado transitorio, no un porqué durable.
Qué no hacer
- No corras una limpieza masiva automática. Tría y repara por topic; la auditoría es un mapa, no un botón de autofix.
- No fusiones duplicados por coincidencia de título. Lee ambos; consolida solo un concepto único genuino.
- No inventes un Área para archivar un huérfano. Usa un dominio existente; un área inventada es donde se pudre el próximo vault.
- No sobrescribas un topic de Knowledge para arreglarlo. Abre una Edición sugerida para que el cambio se revise y se atribuya.
- No borres ni consolides sin un pedido explícito. Esos son actos de owner/admin, y destructivos.
Troubleshooting
- Un topic está marcado stale pero el claim todavía se sostiene. Ese es un falso positivo esperado. Necesita re-confirmarse (owner/admin), no una reescritura; para cualquier otro, propón la confirmación como una Edición sugerida.
- Un topic es zombie (los anchors no coinciden con nada). El glob apunta a archivos que se movieron o se borraron. Re-ancla a donde vive el código ahora, o archiva el topic si el concepto desapareció.
- Los duplicados reaparecen después de consolidar. Puede que estés fusionando por título mientras los conceptos difieren. Vuelve a leer ambos y retitula en su lugar.
- No estás seguro de que la auditoría esté actualizada. Vuelve a correrla; refleja el último estado del workspace cada vez.
Límites y truth states
Referencia relacionada
- Detección de Drift - qué significan stale, zombie y orphaned.
- Gobernanza - Ediciones sugeridas, roles y quién puede integrar.
- CLI: Context Commands - doctor, merge, area y los verbos de gobernanza.
- Govern agent learning - las rutas de Nota, Edición sugerida y Knowledge.