backfill-checkpointing

name	backfill-checkpointing
description	Source-backed batch triage and checkpointing for grouped intake/backfill jobs.

Backfill checkpointing

Use this skill when processing a source-backed batch that arrives as grouped records and may include a required checkpoint snippet or commit line.

What this skill covers

• Compaction of grouped records by channel / thread before note writing
• Dedupe of repeated facts inside a group
• Q1–Q4 batch summaries for each group
• Routing to entity notes when the target is clear
• Creating one sourced Inbox note when routing is uncertain or cross-entity
• Running the exact checkpoint snippet provided by the batch after writeback
• Verifying that the checkpoint advanced before reporting success

Workflow

1. Read the batch instructions first and honor any explicit exclusions or commit-line rules.
2. Compact each channel / thread group as a unit.
3. Remove duplicate facts within the group before writing anything.
4. Answer the four batch questions for the group:
   • What needs to be done?
   • How can I help now?
   • What facts changed?
   • What patterns/signals changed?
5. Route durable facts to the smallest correct home:
   • clear person / org / deal / project → entity note with provenance
   • unclear or cross-entity → one sourced Inbox backfill note for the batch
6. Include source line ranges or representative vadimgest://... URIs in the summary bullets.
7. After triage/writeback, run the exact checkpoint snippet supplied by the batch.
8. Verify the checkpoint effect with a readback of the target state, not just the command exit code.

Pitfalls

• Do not create one note per raw row when rows belong to the same conversation.
• Do not invent a commit command if the batch gives an exact snippet.
• Do not advance a checkpoint for any source line you could not fully process.
• Do not omit provenance; inbox summaries need source ranges or representative URIs.
• Do not treat analysis-only or notification-only rows as durable facts unless they add something real.

Reference files

• references/checkpoint-snippet.md — reusable pattern for exact checkpoint snippets and verification.