/backfill

name: backfill
description: >-
  Reconstruct an OKF bundle by event-sourcing a repository's history (git log
  and Claude session transcripts). Use when creating an `.okf/` bundle for an
  existing repository that predates this skill, or when resuming an interrupted
  backfill session. Triggers on: "reconstruct the OKF bundle", "backfill the
  knowledge bundle", "event-source the history".
user-invocable: true
argument-hint: "[repo-dir] [--no-sessions] [--sessions-dir DIR]"
allowed-tools: Bash Read Write Edit

Reconstruct an OKF bundle from history

This skill replays a repository's decision-making history (git commits and Claude session transcripts) to rebuild its OKF knowledge bundle as if the [okf](/okf) skill's Stop hook had been active from the start.

The extraction layer is **deterministic** (same repo → byte-identical events); the replay layer is an LLM loop, **replayable and auditable but not byte-identical** (timestamps, summaries change per run). See the event schema (§1) and skip rules (§3).

1. Event schema

Git commits and session turns become events (JSONL, one per line, sorted by timestamp then source):

{"id":"git:<sha>","source":"git","ts":"<ISO8601 Z>","sha":"...","author":"...","subject":"...","body":"...","files":[{"path":"...","add":N,"del":N}]}
{"id":"session:<file>:<lineno>","source":"session","ts":"<ISO8601 Z>","user":"...","outcome":"...","title":"...","branch":"...","skip":"..."}

• **Git events** come from `git log --first-parent --numstat`.
• **Session events** pair each user message with the **last** assistant text

block of that turn (the wrap-up), extracted from `~/.claude/projects/<repo-slug>/*.jsonl` and worktree subdirs.

• **Timestamps** are normalized to UTC ISO 8601 strings ending in `Z`.
• **Skip field** (optional, added by extraction): marks low-signal events —

see §3, never overridden by replay.

2. Protocol: Preflight → Extract → Bootstrap → Replay (Map+Reduce) → Finalize

Preflight: check if bundle can be rebuilt

if [ -d <repo>/.okf ] && ! [ -f <repo>/.okf/.backfill-state.json ]; then
  echo "ERROR: .okf/ exists but is incomplete. Delete it to rebuild from scratch, or pass --resume to continue from the last checkpoint."
  exit 1
fi

If `.backfill-state.json` exists, resume from the cursor; otherwise, fresh bootstrap.

Extract: generate event stream

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_backfill_events.py" <repo-dir> \
  --out events.jsonl \
  [--no-sessions] [--sessions-dir ~/.claude/projects] \
  [--max-text 2000] [--skip-globs "vendor/**"]

Write `events.jsonl` to the scratchpad (never committed). Report:

• Total events extracted, per-source counts, and per-rule skip counts.

Bootstrap: initialize bundle (fresh only)

Create `.okf/` with:

mkdir -p <repo>/.okf
echo 'okf_version: "0.2"' > <repo>/.okf/index.md
echo '# Update Log' > <repo>/.okf/log.md

Cursor (`.okf/.backfill-state.json`):

{"last_id": null, "done": 0}

Replay: two-phase map/reduce protocol

The replay is now structured in two phases to enforce semantic depth and anti-degeneration rules:

Phase 1: Map (parallel analysis, per-event)

Launch `okf:event-analyzer` agents for the live events (those without `skip` field), in waves of 4 to 10 (see the cost note in §5), via Claude Code's Workflow `agentType` parameter. Each analyzer receives its event ids, the `events.jsonl` path, the repo path, the output directory and the emitter path, and:

• Fetches its own event JSON with `jq` (the orchestrator dispatches ids, never content)
• Reads git evidence only through the capped diff emitter (§6); session events need no other call
• Writes `analyses/<event-id>.md` (event id with `:` sanitized to `-`) to scratchpad, with a

`truncated` flag copied from the emitter's last line

• Replies with one line of counts per event; the analysis never travels back in the reply
• Never touches `.okf/`
• Is resumable: skip events already in `analyses/`

**Dispatch rule** (deterministic, from `events.jsonl`, no content read): a live event is *small* when it is a session turn or a commit whose numstat totals at most 60 changed lines. Small events are grouped chronologically, eight per analyzer call; large commits go one per call. Measured on this repository (`benchmark/map-tier/RESULTS.md`): 57 calls instead of 147, a third off the map phase at the same tier, no loss on any per-event metric and no cross-event contamination.

jq -c 'select(.skip==null) | {id, small: (.source=="session" or (([.files[]?|.add+.del]|add)//0) <= 60)}' events.jsonl

**Host-agnostic fallback** (if no Workflow support): spawn generic subagents with the same system prompt as `agents/event-analyzer.md`, one per event, collecting analyses to scratchpad.

Phase 2: Reduce (sequential folding, one agent)

Run a single `okf:bundle-weaver` agent that:

• Reads all analyses in chronological order
• Folds them into `.okf/`, updating or creating concepts
• Enforces anti-degeneration rules (§4)
• Adds a dated `log.md` bullet for each lifecycle event only (a concept created, deprecated or

superseded); the "why" of a routine update goes into the concept body

• Manages cursor (`.okf/.backfill-state.json`) for resume capability
• Is the only actor that writes `.okf/`
• Replies with one line of counts (folded, created, updated, bullets, conflicts, superseded,

truncated inputs); the bundle never travels back in the reply

**Resume behavior:** both phases support resumption. Phase 1 skips already-analyzed event ids; Phase 2 restarts from `last_id` in the cursor.

Domain priming (advisory)

Before starting the map phase, read the repository's README and directory structure to sketch a candidate taxonomy of concepts (skills, integrations, decisions, etc.). This priming is *advisory only* — it helps the analyzer emit better candidate names. The *guarantee* that no events are lost comes from the deterministic coverage check in Fina