bigbrain-granola-ingest

Files (3)

• SKILL.md
• openai.yaml · agents/
• cases.md · tests/

SKILL.md (first lines)

# BigBrain Granola Ingest

Discover and route recent Granola meetings, delegate each claimed meeting to `$bigbrain-meeting-ingest`, then resume the Granola ledger, cursor, verification, and batch-reporting lifecycle.

## Contract Checklist

- Read and follow [the shared ingestion completeness checklist](../bigbrain-ingest/references/ingestion-completeness.md) before any Brain write, including when this skill is invoked directly. Complete that checklist before declaring ingestion complete.
- The active brain or routed destination is resolved before any write.
- Machine-wide routing uses each reachable brain's live description as the routing source of truth.
- Machine-wide routing ingests every processable meeting; when no specialized brain clearly wins, route to Personal Brain if it is reachable and writable.
- An optional user-level meeting-ingestion protocol is checked in Personal Brain before destination writes; a missing protocol is a non-blocking no-op.
- Live destination filing rules are read before paths, page types, entities, tasks, or raw sidecars are chosen.
- Existing Granola coverage is checked before creating or repairing pages.
- Every claimed standard-path meeting is delegated exactly once to `$bigbrain-meeting-ingest` in delegated mode for canonical meeting, transcript, entity, and task processing.
- Before delegation, a continuation checklist records the Granola-owned steps that remain after the delegated result returns.
- A delegated Meeting Ingest result is intermediate and cannot complete the Granola run, verify a route, advance a cursor, or emit the batch report.
- Partial or failed delegated results never verify the route or advance the cursor.
- Rely on the destination Brain MCP for automatic propagation and backup, and perform independent caller read-back before reporting success. Run manual sync or maintenance only if verification identifies a failed side effect that requires repair.
- Final output is count-first, grouped by destination-brain headings with meeting-title bullets and created-page sub-bullets, and privacy-safe.

## Scheduled machine-wide ledger control

Scheduled machine-wide runs use the repo-owned `bigbrain-granola-ledger` JSON
helper. Do not use removed `bigbrain granola cursor` or low-level
`bigbrain granola routes` write commands.

1. Run `bigbrain-granola-ledger preflight --source granola` before discovery.
   Stop when the ledger is not writable, its schema is incompatible, integrity
   is not `ok`, or foreign-key violations are present.
2. Run `bigbrain-granola-ledger inspect --source granola --item ID` before
   recording a route. A verified route is a duplicate and permits no new write.
3. Record one decision with `bigbrain-granola-ledger record`, then atomically
   claim an approved route with `bigbrain-granola-ledger claim`. A response with
   `claimed: false` permits no worker and no destination write.
4. Keep the lease token private. Use `renew` while work continues. After every
   destination write and same-Brain read-back succeeds, use `verify` with a
   non-sensitive verification reference. Use `fail` with a non-sensitive error
   code for a terminal failure. For an explicit user-requested retry of a
   failed route, use `retry --source granola --item ID` and then inspect and
   claim the route again. A retry starts a new isolated attempt and still
   requires the full delegation, read-back, verification, and cursor
   gates.
5. Use `advance` only after the matching route is verified. The helper enforces
   that gate and monotonic cursor ordering. Held, failed, partial, unavailable,
   or merely claimed routes never advance the cursor.

See `docs/granola-routing-ledger.md` in the BigBrain repository for the exact
invocations. Never pass meeting titles, participants, summaries, transcripts,
prompts, credentials, or other private content to the ledger helper.

## Workflow

1. Resolve candidate brains and routing context.
   - Read the shared ingestion completeness checklist linked above and use it throughout this workflow, even on direct invocation.
   - In selected-brain mode, resolve the target through selected BigBrain context, `--brain-home`, `BIGBRAIN_HOME`, or the saved default pointer.
   - In machine-wide routing mode, list registered machine-wide brains first, then read each reachable brain's live description and authenticated capability/about state.
   - Consider only brains that are reachable, authenticated, writable, and have a valid description.
   - Route machine-wide candidates by comparing allowed meeting metadata to brain descriptions only; do not use per-brain examples, purpose tags, source rules, profile approval state, or private filing hints as routing inputs.
   - Prefer the specialized brain when a clear description match exists.
   - If no specialized brain clearly wins and Personal Brain is reachable, authenticated, writable, and has a valid description, route to Personal Brain as the fallback destination.
   - Hold the item for review only when the likely destination is unavailable, Personal Brain fallback is unavailable, required folder exclusions cannot be enforced, or the meeting cannot be fetched safely enough to ingest.
   - Anti-patterns: reading filing rules before knowing candidate brains, routing from examples or keyword lists, treating unclear specialized routing as ambiguous when Personal Brain is available, fan-out to multiple brains, writing to an unavailable brain
2. Read the optional Personal Brain protocol and destination filing rules.
   - Before any destination write, check Personal Brain for `protocol/meeting-ingestion-protocol.md`.
   - If the protocol page exists, read it and apply any explicit meeting-specific route or output override before continuing.
   - If the protocol selects a specialized workflow, delegate to that workflow and stop the standard BigBrain meeting-write path for that meeting. Do not name or hardcode a personal sub-skill in this shared skill.
   - If the protocol page is absent, continue with standard Granola ingestion and apply no protocol-specific override. Do not search other brains and do not create the page automatically.
   - For meetings that remain on the standard BigBrain path, read the selected destination's top-level `FILING.md` and relevant collection filing rules before choosing paths or page types.
   - Treat live filing rules as authoritative for meeting pages, raw transcript sidecars, entity pages, deal/project updates, and tasks.
   - In machine-wide routing mode, delegate destination write behavior to the selected brain's live filing rules instead of duplicating those rules in this router skill.
   - Anti-patterns: writing before the optional protocol check, searching every brain for the protocol, hardcoding destination paths, duplicating filing rules, using stale memory instead of live rules, creating pages before reading rules
3. Confirm Granola access and exclusions.
   - Prefer direct Granola MCP tools such as `list_meeting_folders`, `list_meetings`, `get_meetings`, and `get_meeting_transcript`.
   - Use the active harness's MCP discovery process before concluding Granola tools are unavailable.
   - Check user instructions and destination filing rules for excluded Granola folders or separate ingestion workflows.
   - Use folder-aware Granola listing to enforce required exclusions; stop if required folder filters cannot be resolved.
   - Anti-patterns: ignoring required excluded folders, using broad queries when folder filtering is required, assuming Granola is unavailable without tool discovery, continuing when exclusions cannot be enforced
4. Identify candidate meetings.
   - Consider only recent meetings or meetings since the newest ingested Granola meeting with a small overlap window, unless the user asks for a backfill.
   - Query from two days before the newest ingested meeting, or the last 30 days when no prior import exists.
   - Drop exact-title `New note` and `New Note` records before fetching details, transcripts, or writing pages.
   - Fetch meeting details in batches of at most 10.
   - Fetch transcripts only for new meetings or explicit repair/update work.
   - Anti-patterns: backfilling without request, processing placeholder notes, fetching transcripts for known duplicates without repair need, over-fetching beyond tool limits
5. Check existing coverage and repair needs.
   - Search existing meeting pages and raw sidecars for Granola provenance before writing.
   - In machine-wide routing mode, also check the global routing ledger and destination provenance by Granola ID before attempting any write.
   - Treat matching Granola coverage as already ingested even if the title changed.
   - Skip duplicates unless a missing transcript, missing sidecar, stale participant/entity link, or clear task/status update needs repair.
   - Anti-patterns: duplicate meeting pages, relying on title-only dedupe, ignoring changed titles with same Granola ID, skipping a new processable meeting because it feels low-value, repairing pages without a concrete gap
6. Prepare the delegated meeting handoff and continuation checklist.
   - Complete the routing-ledger `record` and `claim` steps before allowing any destination write. Invoke Meeting Ingest only after the route is successfully claimed with `claimed: true`; a route with `claimed: false` permits no delegation.
   - Before delegation, record an ephemeral continuation checklist for this route: receive and validate the delegated result, perform Granola final read-back, verify or fail the route, advance only after verification, then continue the batch and emit the Granola report.
   - Prepare a natural-language delegated handoff containing caller identity `$bigbrain-granola-ingest`, the resolved destination, live filing context, Granola source identity and provenance, meeting metadata, fetched transcript and notes, source-specific authority boundaries, privacy constraints, and allowed mutations.
   - Require the worker to apply the shared ingestion completeness checklist to the full accepted meeting evidence, including secondary entities, and to verify its coverage before returning complete.
   - Explicitly instruct `$bigbrain-meeting-ingest` to use delegated mode and return control to `$bigbrain-granola-ingest` after one meeting. Do not pass the ledger lease token, cursor state, credentials, or private batch-control data.
   - Renew the private ledger lease while delegated work continues when necessary.
   - Anti-patterns: delegating before claim, relying on memory for remaining Granola steps, passing routing secrets to Meeting Ingest, asking Meeting Ingest to process a batch, omitting the return-control instruction
7. Delegate one meeting and regain control.
   - Invoke `$bigbrain-meeting-ingest` exactly once for the claimed route and wait for its delegated result.
   - The delegated result is not completion of the Granola item, the Granola run, or the batch.
   - Immediately resume Granola processing from the recorded continuation checklist after the delegated result returns. Do not stop, summarize to the user, or move to another route before resolving the current route's post-delegation lifecycle.
   - Require the delegated result to identify `complete`, `partial`, or `failed`, the canonical meeting outcome, required-artifact verification, related changes, blockers, and explicit return of control.
   - Partial or failed delegated results must not run ledger verification or cursor advancement.
   - If the delegated result is incomplete, unclear, partial, failed, or lacks required verification, record a non-sensitive terminal failure code with `bigbrain-granola-ledger fail`; leave the route unverified and the cursor unchanged.
   - Anti-patterns: treating delegated success as overall success, losing the caller continuation, emitting Meeting Ingest output to the user, invoking Action Review or duplicating meeting interpretation in Granola, verifying a partial result
8. Complete the Granola-owned post-delegation lifecycle.
   - For a delegated `complete` result, perform the final read-back of the referenced canonical meeting, provenance, required transcript sidecar or artifact, affected stable pages, and tasks through the same destination Brain.
   - Confirm the stored raw transcript is full-text using content, size, or equivalent metadata against the fetched transcript payload when available.
   - Re-scan the destination for duplicate Granola provenance and confirm changed pages match live filing rules.
   - Confirm the shared checklist is complete for this meeting before declaring it ingested or verifying its route; a delegated report alone is not proof.
   - Only after delegated completion, Granola final read-back, and required-artifact verification succeed may the caller run `bigbrain-granola-ledger verify` with a non-sensitive verification reference.
   - Run `bigbrain-granola-ledger advance` only after the same route is verified. If any post-delegation check fails, use `fail` with a non-sensitive code and leave the cursor unchanged.
   - Mark the route's continuation checklist complete only after verify and any eligible advance succeed.
   - Anti-patterns: trusting the delegated report without independent caller read-back, failing to resume after delegation, verifying before final read-back, advancing before verify, leaving a claimed route unresolved, treating a failed advance as successful completion
9. Continue the batch.
   - Repeat claim, continuation recording, one-meeting delegation, caller resumption, final verification, and cursor handling for every processable candidate.
   - Keep each route isolated so one partial or failed meeting does not erase verified results for other meetings.
   - Do not expose internal delegated results, lease state, continuation notes, identifiers, or private source content in the final report.

From life-efficient/bigbrain, MIT.

More from life-efficient/bigbrain