granola-pipeline

name	granola-pipeline
description	Process Granola meeting notes or transcripts into Notion raw intake, review them through the V1 `session_capitalizable` layer, extract action items, and create proactive follow-ups. Use when "subir transcripcion", "procesar granola", "reunion terminada", "compromisos reunion", or "propuesta de seguimiento".
metadata	{"openclaw":{"emoji":"🎙","requires":{"env":["NOTION_API_KEY","NOTION_GRANOLA_DB_ID"]}}}

Granola Pipeline Skill

Rick puede procesar notas o transcripciones de Granola y generar follow-ups proactivos usando las tasks granola.* del Worker.

Estado vigente

• El flujo V1 vigente es raw -> session_capitalizable -> capitalization.
• El repo conserva curated en algunos nombres de env vars, tasks y docs por compatibilidad.
• En esta skill, curated se lee solo como alias legacy de session_capitalizable, no como capa paralela activa.

Regla principal

Esta skill trabaja primero sobre la capa raw y luego sobre el paso controlado hacia session_capitalizable.

No asumas que:

• todo item raw debe promoverse
• toda reunion debe convertirse en proyecto o tarea
• Granola siempre trae transcript de audio
• el alias curated implica una capa distinta a session_capitalizable

La arquitectura vigente es:

1. Raw: DB NOTION_GRANOLA_DB_ID
2. session_capitalizable: binding V1 hacia Registro de Sesiones y Transcripciones, hoy resuelto desde NOTION_CURATED_SESSIONS_DB_ID
3. Capitalization targets: proyectos, tareas, entregables, bridge items y follow-ups solo cuando el payload y el contrato lo permiten

Requisitos

• NOTION_API_KEY: token de integracion Notion Rick.
• NOTION_GRANOLA_DB_ID: ID de la DB raw de Granola.
• NOTION_TASKS_DB_ID (opcional): superficie operativa de tareas del stack.
• NOTION_CURATED_SESSIONS_DB_ID (opcional): nombre legacy del binding actual hacia la capa V1 session_capitalizable.
• NOTION_HUMAN_TASKS_DB_ID (opcional): DB humana de tareas usada desde un registro session_capitalizable.
• NOTION_COMMERCIAL_PROJECTS_DB_ID (opcional): DB comercial usada desde un registro session_capitalizable.
• Watcher corriendo en la VM (scripts/vm/granola_watcher.py) o flujo manual hacia .md.

Tasks disponibles

1. Procesar intake raw

Task: granola.process_transcript

Pipeline raw completo:

1. crea pagina raw en Notion
2. extrae action items
3. opcionalmente crea tareas del stack cuando el handler lo soporta
4. notifica a Enlace

2. Crear follow-up

Task: granola.create_followup

3. Evaluar capitalizacion de raw ya ingresado

Task: granola.capitalize_raw

Usar esta task sabiendo que:

• en V1, raw -> canonical target viene bloqueado por defecto
• si no se habilita allow_legacy_raw_to_canonical=true, el handler deja comentario de revision y redirige hacia session_capitalizable
• el escape hatch legacy existe solo para casos repo-side explicitos y con destinos exactos

4. Promover a session_capitalizable (nombre de task legacy)

Task: granola.promote_curated_session

Usar esta task solo cuando:

• la pagina raw ya existe
• la superficie V1 fue compartida con Rick
• NOTION_CURATED_SESSIONS_DB_ID ya esta configurado
• quieres crear o actualizar un registro session_capitalizable con trazabilidad

Esta task:

• inspecciona el schema vivo de la superficie V1
• crea o actualiza por titulo exacto
• solo crea relaciones si recibe page_id explicitos
• no reemplaza la derivacion posterior hacia tareas o proyectos humanos

5. Crear tarea humana desde session_capitalizable (nombre de task legacy)

Task: granola.create_human_task_from_curated_session

Usar esta task solo cuando:

• el registro session_capitalizable ya existe
• NOTION_HUMAN_TASKS_DB_ID ya esta configurado
• quieres registrar una tarea humana explicita y trazable

Esta task:

• exige task_name explicito
• inspecciona el schema vivo de la DB humana de tareas
• crea o actualiza por titulo exacto
• hereda Proyecto desde el registro session_capitalizable cuando existe
• enlaza Sesion relacionada

6. Actualizar proyecto comercial desde session_capitalizable (nombre de task legacy)

Task: granola.update_commercial_project_from_curated_session

Usar esta task solo cuando:

• el registro session_capitalizable ya existe
• el proyecto comercial humano ya esta identificado
• NOTION_COMMERCIAL_PROJECTS_DB_ID ya esta configurado
• el cambio comercial cabe en campos explicitos del proyecto

Esta task:

• usa project_page_id explicito o la relacion Proyecto heredada desde session_capitalizable
• actualiza solo campos comerciales soportados por el schema vivo
• deja trazabilidad por comentario entre el registro session_capitalizable y el proyecto comercial
• no crea proyectos comerciales nuevos

7. Orquestar un slice operativo explicito

Task: granola.promote_operational_slice

Usar esta task cuando:

• ya tienes una pagina raw concreta
• ya sabes exactamente que registro session_capitalizable registrar
• quieres encadenar en la misma corrida una tarea humana y/o una actualizacion comercial

Esta task:

• siempre ejecuta granola.promote_curated_session
• puede ejecutar ademas granola.create_human_task_from_curated_session
• puede ejecutar ademas granola.update_commercial_project_from_curated_session
• exige payloads explicitos por tramo
• no agrega inferencias nuevas
• soporta dry_run=true para devolver los payloads exactos sin escribir en Notion

Para lotes explicitos repo-side, usar:

• scripts/run_granola_operational_batch.py
• template: scripts/templates/granola_operational_batch.plan.template.json

Procedimientos

Pipeline automatico

1. Granola deja la reunion en cache local
2. un exporter o copy/paste genera .md en GRANOLA_EXPORT_DIR
3. granola_watcher.py detecta el archivo y llama al Worker
4. Worker crea pagina raw, extrae action items y notifica a Enlace

Pipeline manual

1. David copia la nota o transcript desde Granola
2. Rick o una herramienta intermedia la guarda como .md
3. el Worker procesa ese material en la capa raw

Guardrails de capitalizacion

Estas reglas aplican a cualquier cierre de una pagina raw Granola hacia objetos canonicos (proyecto, tarea, bridge item, sesion curada). Son normativas y no negociables.

G1. Preservacion de trazabilidad de ingest

• Nunca reemplazar por completo el campo Trazabilidad de una pagina raw de Granola. La capitalizacion solo puede anexar claves nuevas.
• Claves de ingest/reconciliation que deben preservarse siempre si ya existen en la pagina raw:
  • granola_document_id
  • source_updated_at
  • source_url
  • ingest_path
  • content_hash
  • char_count
  • segment_count
  • truncation_detected
  • ingested_at
  • reconciled_at
  • shared_folder_path
  • sha1
• Claves que la capitalizacion si puede anexar:
  • source
  • capitalization_mode (por ejemplo bridge_item, project+task+deliverable, partial)
  • canonical_target_type
  • canonical_target_name
  • processed_at
• canonical_target_url NO pertenece a Trazabilidad bajo ninguna circunstancia — corrige una version previa de esta guia. El prompt V2.1.1 del agente Notion (notion-governance/prompts/agents/review-capitalizacion-v2.1.md) prohibe explicitamente escribir URLs, mentions o links en cualquier valor de Trazabilidad: Notion los convierte automaticamente en <mention-page> y rompe el formato clave=valor. La URL del canonico final vive exclusivamente en la propiedad URL artefacto de la pagina raw.
• Prohibido explicitamente emitir una trazabilidad nueva que contenga frases tipo Residuo legacy descartado cuando ese residuo incluye claves de ingest. Esa accion borra evidencia y rompe la reconciliacion de PR fix(granola): reconcile updated transcripts before capitalization (ingest-side, ver docs/78-granola-transcript-finality-reconciliation.md).
• Si se detecta que un campo de trazabilidad de ingest desaparecio entre una corrida y otra, la capitalizacion cuenta como parcial y la pagina raw debe quedar en estado revisable, no Procesada.
• Helper determinista de referencia (P0, sin Notion, sin LLM): worker/tasks/granola_capitalization.append_capitalization_traceability(). Preserva byte a byte las lineas de ingest existentes y reconcilia (no duplica) el bloque de capitalizacion en reintentos.

G1-bis. Verify-after-write es bloqueante (P0)

Ninguna capitalizacion raw -> Tarea puede declarar exito a partir de la respuesta del write. El unico criterio valido es una relectura real posterior de la pagina raw y de la tarea, comparando campo a campo: titulo, URL artefacto == URL real de la tarea, Destino canonico, Estado, Estado agente, Accion agente, Procesar con agente, propiedades V2 obligatorias, lineas de ingest de Trazabilidad intactas y en orden, y relaciones si fueron proporcionadas. Si la relectura no confirma todo, no se declara Capitalizado. Helper determinista de referencia (P0): worker/tasks/granola_capitalization.verify_task_capitalization(). Este helper traduce a codigo la regla "Prohibicion de declaracion falsa de exito" del prompt V2.1, tras el patron "log miente" observado en el piloto Notion (ver docs/plans/granola-capitalization-hybrid-plan-2026-07-16.md).

G2. Reuniones comerciales / oportunidades (project-first)

Si una reunion raw funda o cambia una oportunidad comercial, el destino primario no puede ser solo una tarea suelta. La salida canonica es la pagina del proyecto. El orden es:

1. resolver el cliente/partner (nombre, dominio de correo, contacto);
2. resolver o crear el proyecto / oportunidad comercial en la DB Asesorias & Proyectos, o en su defecto registrar un bridge item cuando no hay DB comercial disponible o no hay permiso de Rick;
3. si hay un output revisable (propuesta, estimacion, demo, briefing), crearlo como seccion o subpagina dentro del proyecto — no como entregable separado en otra DB;
4. opcionalmente crear la tarea operativa (seguimiento), vinculada al proyecto o al bridge item;
5. dejar comentarios/trazabilidad cruzada entre la pagina raw y los objetos creados.

No usar la DB humana "📦 Entregables" (eliminada por David, ID 462adf65) ni la "Bandeja de revision - Rick" (NOTION_DELIVERABLES_DB_ID) para propuestas o presupuestos comerciales Granola. La Bandeja de revision queda reservada para outputs internos de agentes (auditorias, benchmarks, smokes, reportes de revision, QA interno).

Si no es posible crear/verificar el proyecto u oportunidad porque falta acceso, sharing o informacion:

• la capitalizacion debe marcarse como parcial o revision requerida;
• Estado de la pagina raw no puede quedar en Procesada;
• Accion agente no puede quedar en Capitalizado;
• debe dejarse un comentario explicando que bloquea el cierre.

G3. Tareas sueltas

Crear solo una tarea puede ser correcto cuando la reunion es claramente operativa interna. No es correcto cuando la reunion tiene identidad comercial (cliente nombrado, propuesta mencionada, presupuesto, entregable).

Una tarea sin proyecto/oportunidad ni bridge asociado, para una reunion con identidad comercial, cuenta como capitalizacion parcial, no como capitalizada.

G4. Datos ambiguos del transcript

• No convertir transcripcion fonetica ambigua en dato firme.
• Ejemplo real: beam beam arroba congress no debe guardarse como beam@comgrap ni beam@congress sin confirmacion humana.
• El registro correcto en ese caso es texto fenomenologico, por ejemplo: correo mencionado foneticamente; confirmar direccion, posiblemente bim@comgrap o [e-mail].
• Cualquier dato de contacto inferido por fonetica debe quedar marcado como sin confirmar hasta que David o Enlace lo validen.

G5. Caso de regresion: Comgrap Dynamo

Caso real observado (raw Comgrap Dynamo) que no debe repetirse:

• Raw: Comgrap Dynamo
• Cliente / partner: COMGRAP
• Contexto: demo y propuesta para Dynamo / Revit aplicado a particion de muros prefabricados de hormigon y diseno generativo.

Resultado incorrecto observado:

• solo se creo una tarea suelta
• Estado = Procesada
• Accion agente = Capitalizado
• Destino canonico = Tarea
• URL artefacto apuntando a una tarea aislada
• la Trazabilidad fue reescrita y se descartaron campos legacy criticos (granola_document_id, ingest_path, source_updated_at)
• el Log del agente reconocia que habria que evaluar crear un proyecto en Asesorias & Proyectos pero cerro igual como capitalizado

Resultado correcto esperado (project-first):

• proyecto canonico: COMGRAP — Demo Dynamo / prefabricados de hormigon (pagina: 3485f443-fb5c-8198-9f54-fc5882302bf2)
• subpagina propuesta dentro del proyecto: Propuesta demo Dynamo/Revit para particion de muros prefabricados + diseno generativo (pagina: 2de7b1e7-45c3-49b3-aec2-ea29ffd262d8)
• tarea operativa (seguimiento), vinculada al proyecto: Enviar propuesta/estimacion demo Dynamo a Comgrap (pagina: df938460-fdee-4752-b9d4-293bede5e541)
• nada en "📦 Entregables" (DB eliminada) ni en "Bandeja de revision - Rick"
• la pagina raw solo puede quedar como capitalizada si el proyecto y la subpagina propuesta estan creados y trazados; si falta alguno, queda como capitalizacion parcial o revision requerida
• la Trazabilidad de ingest (granola_document_id, source_updated_at, ingest_path, content_hash, etc.) se preserva intacta y la capitalizacion solo anexa sus propias claves nuevas

Este caso funciona como test de regresion documental: cualquier cambio futuro en la skill o en los handlers de capitalizacion debe seguir cumpliendo los guardrails G1-G4 y G7 sobre esta reunion.

G6. Trazabilidad de regularizaciones manuales

Cuando una regularizacion se hace por fuera del Worker — por ejemplo con curl directo desde la VPS, un script ad-hoc, el panel Notion manual de David, o un agente como Copilot corrigiendo a mano una capitalizacion rota — Notion queda coherente pero el stack no recibe evento central en ops_log.jsonl.

Regla normativa:

Toda regularizacion manual Notion con API/curl/script directo debe emitir un notion.operation_trace con operation_id. No cerrar como trazado si solo hay comentarios Notion.

Herramientas (sin llamadas a Notion, no requieren NOTION_API_KEY):

• infra.ops_logger.OpsLogger.notion_operation(...) — API programatica para agentes Python internos.
• scripts/notion_trace_operation.py — CLI con --dry-run y --operation-id opcional.

Campos minimos del evento:

• operation_id (UUID4 auto si no se provee)
• actor, action, reason
• raw_page_id, target_page_ids (lista corta, max 25)
• source, source_kind
• notion_reads, notion_writes, status
• details (truncado a 500 chars; prohibido meter transcript crudo o prompts completos)

Caso de regresion documental — Comgrap Dynamo (regularizado manualmente con curl sin dejar evento central inicialmente):

• raw_page_id: 3485f443-fb5c-81e9-ae88-fe2fb7cd7b54
• tarea vinculada: df938460-fdee-4752-b9d4-293bede5e541
• proyecto: 3485f443-fb5c-8198-9f54-fc5882302bf2
• action: regularize_granola_capitalization
• reason: task_only_capitalization_corrected_to_project_task

Detalles completos en docs/78-granola-transcript-finality-reconciliation.md (seccion 10) y docs/50-granola-notion-pipeline.md (seccion 9.9).

G7. Project-first para transcripciones comerciales Granola

Para transcripciones Granola con proyecto u oportunidad comercial clara:

1. El proyecto es la salida canonica. La pagina del proyecto en Asesorias & Proyectos es la fuente de verdad.
2. Propuesta/presupuesto = seccion o subpagina del proyecto. No crear registros separados en otra DB.
3. Tarea = seguimiento operativo. Opcional, vinculada al proyecto.
4. Raw = evidencia/trazabilidad. No es destino final.
5. No usar "📦 Entregables" — la DB humana con ID 462adf65 fue eliminada por David y no forma parte del stack.
6. No usar "Bandeja de revision - Rick" para propuestas comerciales. NOTION_DELIVERABLES_DB_ID apunta a esa bandeja; su uso queda reservado para outputs internos de agentes: auditorias, benchmarks, smokes, reportes de revision, QA interno.

Residue check documental para capitalizaciones comerciales:

• raw Granola apunta a una salida canonica clara (proyecto)
• proyecto contiene contexto y trazabilidad
• propuesta/presupuesto vive como seccion o subpagina del proyecto
• tarea, si existe, esta relacionada al proyecto
• no hay entrega comercial en "Bandeja de revision - Rick"
• no hay referencias a la DB humana eliminada 462adf65
• no hay datos foneticos ambiguos promovidos como dato firme

Notas

• Los docs repo-side que todavia usan curated deben leerse como alias legacy de session_capitalizable.
• Si falta sharing de la superficie V1 o de los targets humanos, el bloqueo correcto es de acceso, no de arquitectura.
• No asumas que session_capitalizable o los targets humanos son visibles para Rick solo porque existan en Notion.
• Si el watcher no esta corriendo, Rick puede procesar archivos manualmente.

Referencias

• docs/50-granola-notion-pipeline.md
• docs/54-granola-capitalize-raw-slice.md
• docs/78-granola-transcript-finality-reconciliation.md (ingest-side)
• docs/56-granola-promote-curated-session.md
• docs/57-granola-human-task-from-curated-session.md
• docs/58-granola-commercial-project-from-curated-session.md
• docs/59-granola-promote-operational-slice.md
• worker/notion_client.py
• worker/tasks/granola.py
• scripts/vm/granola_watcher.py
• infra/ops_logger.py (notion_operation)
• scripts/notion_trace_operation.py

Los docs 56-59 conservan naming legacy con curated; en el contrato vigente debe leerse como alias de session_capitalizable.