Saltar al contenido principal
Un agente puede descubrir algo verdadero, y puede afirmar una interpretación equivocada con la misma convicción. Por eso escribir una afirmación y volverla el Knowledge del equipo son actos distintos. Esta guía toma una observación cruda y la enruta bien: una Nota se queda como pista, un cambio a Knowledge existente pasa por una Edición sugerida, y solo una persona integra algo en la fuente de verdad del equipo. Hay dos rutas, según si el aprendizaje es nuevo o contradice algo ya registrado. Ambas terminan con un humano decidiendo.

​
Resultado

Un aprendizaje que aterriza donde pertenece y se confía al nivel correcto: una Nota limpia que el agente lee como pista, una Edición sugerida que un owner o admin puede integrar, o, tras revisión, Knowledge revisado, con autoría y procedencia intactas.

​
Cuándo usarlo

  • Un agente (o tú) aprendió algo durable y estás decidiendo qué hacer con ello.
  • Un Topic se ve desactualizado y quieres cambiarlo sin sobrescribirlo.
  • Estás tentado de “solo actualizar el wiki”, que es justo cuando la gobernanza importa.

​
Disponibilidad y prerrequisitos

ÍtemEstado
Notas, propose, Ediciones sugeridas, CommentsAvailable
Integrar en Knowledge (approve, pr --merge)Available, solo con autoridad de owner/admin
Un agente ejecutando la integración cuando se lo piden explícitamenteAvailable (sellado como approved_via: agent)
Agentes de plataforma abriendo Ediciones sugeridas automáticamenteNot available (una versión futura)
Necesitas la CLI instalada y con login. Cualquiera puede escribir una Nota y abrir una Edición sugerida; integrar requiere el rol admin u owner. Un agente integra solo cuando un owner o admin se lo pide de forma explícita.

​
Objetos involucrados

ObjetoRol en este workflow
NotaUn borrador privado; el agente la lee como pista.
En revisiónUna Nota propuesta al equipo; sigue siendo pista, ahora en la cola.
Knowledge (reviewed)La fuente de verdad del equipo, las notas integradas.
Edición sugeridaUn parche de contenido que propone un cambio a Knowledge existente.
CommentFeedback a nivel de field en el gate de revisión; resuelve en una edición.

​
Antes de empezar

Tienes una observación en la mano. Primero hazte la pregunta del litmus: ¿un cambio de código futuro la contradiría de forma significativa? Si sí, es durable y vale la pena capturarla. Si solo repite el código o es un valor transitorio, déjala ir. 
driftless context search "refund window"    # ¿un Topic ya cubre esto?

​
Context preflight

Qué ruta tomas depende de lo que ya existe, así que lee primero:
  • Ningún Topic lo cubre y es durable: esta es la ruta de nueva observación. Captura una Nota limpia.
  • Un Topic lo cubre y se ve mal o en drift: esta es la ruta de cambio a Knowledge existente. Abre una Edición sugerida, no sobrescribas.
Lee el trust y el drift del Topic candidato antes de decidir. reviewed es Knowledge (verdad); draft o proposed es una Nota (una pista). Un badge de drift significa que el código bajo él se movió y el porqué registrado quizá ya no se sostiene. 
driftless context get billing-flow    # lee trust, drift y los fields que podrías cambiar

​
Workflow paso a paso

​
Nueva observación

1

Captúrala como una Nota (o un Topic completo)

Una Nota de una línea alcanza para una pista. Si es claramente durable, escríbela como un Topic anclado: un concepto, archivado en un área, anclado estrecho.
# Una pista rápida se queda como Nota privada
driftless note add --content "RS256 lets services verify tokens without a shared secret"

# O un Topic completo cuando es claramente durable: una idea, un área, un anchor estrecho
driftless context add token-verification \
  --title "Token verification" \
  --content @note.md \
  --area auth \
  --pattern "src/auth/**" \
  --rel depends_on:token-refresh
La Nota se queda como pista, privada y fuera de la búsqueda, hasta que decidas que vale los ojos del equipo.
2

Proponla a revisión, cuando se lo gane

Cuando la Nota es lo bastante durable para todo el equipo, ponla a revisión. Esto no la vuelve verdad; entra a la cola como pista a la espera de un humano.
driftless context propose token-verification    # Nota -> En revisión
Una persona revisa la evidencia, el alcance, la durabilidad y cualquier contradicción, y decide. La mayoría de las Notas se quedan como Notas, y eso es sano: una pista limpia es valiosa aunque nunca se integre.

​
Cambio a Knowledge existente

1

Revisa drift, evidencia y relaciones

Lee el Topic y el código que ancla antes de proponer nada. Confirma que el cambio es real, no una mala lectura.
driftless context get billing-flow
driftless context get --files "src/billing/**"
2

Abre una Edición sugerida, con un parche o una pregunta

No sobrescribas Knowledge. Abre una Edición sugerida que lleve un parche de contenido comprobable. Si tienes incertidumbre, deja un Comment en el field en vez de un parche, para que un humano resuelva la ambigüedad.
# Un parche comprobable: trigger + rationale en el summary, el cambio en el content
driftless context pr billing-flow --open \
  --summary "Refund window moved from 30 to 60 days; update the decision" \
  --content @patch.md

# O, ante incertidumbre, una pregunta puntual sin parche
driftless context comment add billing-flow \
  --body "This decision may contradict the new refund window; can someone confirm?" \
  --field decisions
El agente no aprueba su propia interpretación. Un humano revisa la Edición sugerida y la integra, o resuelve el Comment.
Lo mismo por MCP: driftless_context_propose, driftless_context_create_proposal (la Edición sugerida) y driftless_context_comment. driftless_context_approve también existe, pero es solo con autoridad de owner/admin y el cliente lo ejecuta solo cuando la persona que autoriza se lo pide de forma explícita. Ver Gobernanza.

​
Estados esperados

MomentoQué deberías ver
Tras note addUn borrador privado, visible solo para ti, fuera de la búsqueda.
Tras context proposeLa Nota queda En revisión, en la cola, sigue siendo pista.
Tras que un owner o admin integratrust: reviewed, con approved_by y approved_via seteados.
Tras context pr --openUna Edición sugerida a la espera de una integración de owner o admin.
El agente corre approve sin autoridadRechazado: un token de member o sin rostro no puede integrar.

​
Knowledge write-back

El enrutamiento es el write-back aquí. Integrar es el único acto reservado a una persona: 
driftless context approve token-verification    # solo owner/admin; ejecútalo solo cuando te lo piden
  • Una pista se queda como Nota. Llega al agente ponderada como sugerencia, y eso alcanza para la mayoría de los aprendizajes.
  • Un cambio a la verdad pasa por una Edición sugerida, nunca por una sobrescritura directa. El parche está limitado por whitelist a los campos de contenido, así que nunca puede falsificar una aprobación.
  • La verdad institucional es lo que un owner o admin integra. No integres por iniciativa propia, aunque tengas la autoridad; propón, e integra solo cuando te lo piden.
Conserva el porqué, no un changelog. Un Topic contiene la decisión, el invariante o el gotcha durable. Las fechas, “shipped” y las referencias a PRs viven en git, no en Knowledge.

​
Qué no hacer

  • No dejes que un agente declare la verdad. Generar una afirmación e integrarla son actos distintos; la integración es una decisión humana.
  • No sobrescribas un Topic de Knowledge. Abre una Edición sugerida para que el cambio se revise y se atribuya.
  • No fuerces un Topic donde una pista alcanza. Si un cambio de código futuro no lo contradiría, no es durable; deja una Nota o nada.
  • No apiles dos conceptos en una nota. Una idea por nota; archívala en un área; anclala estrecho. Un anchor suelto filtra la nota a trabajo del que no tiene nada que decir.
  • No escribas un changelog en un field. El porqué durable pertenece a Knowledge; el historial pertenece a git.

​
Troubleshooting

  • approve fue rechazado. Tu key carece de autoridad de owner/admin, o nadie te pidió integrar. Propón en su lugar y deja la integración a una persona.
driftless context list --suggested    # lo que aún no es Knowledge: notas y En revisión
  • Dos Notas cubren lo mismo. Consolida en vez de apilar una tercera. Ver Clean workspace context.
  • Una Edición sugerida es ambigua. Agrega un Comment acotado a un field para que el revisor pueda fijar la objeción exacta antes de integrar.
  • Un Topic en drift todavía se sostiene. Re-confirmarlo (volver a ponerlo reviewed) es un acto de owner/admin; para cualquier otro, propón la confirmación como una Edición sugerida.

​
Límites y truth states

CapacidadEstado
Notas, propose, Ediciones sugeridas, CommentsAvailable
Integrar en KnowledgeAvailable, solo con autoridad de owner/admin
Integración por agente cuando se lo piden explícitamenteAvailable (approved_via: agent)
Integración automática o auto-aprobaciónNot available (una persona siempre decide)
Agentes de plataforma redactando Ediciones sugeridasNot available (una versión futura)

​
Referencia relacionada