backfill-enumerate-drain

name	backfill-enumerate-drain
description	How to backfill a newly-added repo or team — the enumerate-then-drain loop, the single-event contract, and resume-safe todo discipline. Load this when handling a *.added seed event with the planner on.
version	1.0.0
tags	["backfill","planner","todo","ingestion"]

Backfill: enumerate, then drain

You are handling a single *.added seed event (a repository or a team was just connected). The graph has no history for it yet. One seed fans out into many artifacts (PRs, issues, projects, documents). Your todo/plan tools are ON. Use this procedure for any such backfill; the playbook tells you WHICH enumerators and WHAT to extract per artifact.

The loop

1. Enumerate (one call per list tool). Call each list/enumerator tool the playbook names exactly once. They are bounded server-side to a trailing window and a hard item cap, and come back newest-first. Do not page or scrape beyond what one call returns — the window/cap is deliberate; the tail arrives via live webhooks and future backfill.
2. Write one todo per returned ref, across all enumerated kinds. If the playbook says some kinds frame the others (e.g. projects/documents frame issues), drain those first.
3. Drain newest-first. For each todo: hydrate the ref with the detail tool named by the playbook (for example github_get_pull_request or github_get_issue), apply the extraction the relevant per-kind playbook prescribes via apply_graph_mutations, then mark the todo done and move on.

Resume discipline (critical)

The todo list rides in your message history, which is checkpointed after every tool call. A resumed run therefore continues an existing list — if todos already exist, never re-enumerate and never restart the walk from scratch. Re-running an enumerator on resume duplicates work and burns budget.

Single-event contract

This batch contains exactly one event — the seed. Per-artifact identity lives in each artifact's stable entity_key, not in event ids. So:

• Pass the seed's event_id to every apply_graph_mutations call.
• Finish with a single mark_event_processed(seed_event_id, summary) then finish_batch.

Stable keys make a backfilled artifact and a later live webhook for the same thing converge on one node instead of duplicating. See the graph-mutation-plan skill for the key patterns.

Budget discipline

Breadth of a coherent recent seed beats exhaustive depth. If you approach the tool budget, ingest what you already have cleanly, then mark_event_processed the seed and finish_batch — the remainder re-batches later. Never fabricate a PR/issue/project/document/comment you did not actually fetch; add a warning instead.