Zettle

0009-review-workflow

2 min read

ADR-0009: Batch staging review workflow

Status: Accepted Date: 2026-05-19

Context

AI must produce content faster than the user can review per-note, but full autopilot lets drift catch you weeks late. Need a workflow that gets bulk efficiency AND tight control.

Decision

Batch staging with two hard review gates.

Gate 1 — Ingestion review

When AI ingests a new resource:

  • AI shows: file count, heading structure, citation form sample
  • User confirms before AI produces any atomics from it
  • Prevents: ingesting a misformatted source and generating 50 broken-citation atomics downstream

Gate 2 — Batch review

For each work batch:

  1. AI processes a bounded chunk (e.g., one DP chapter)
  2. Output lands in /staging/{batch-id}/ — proposed notes + REVIEW.md
  3. User reviews in Obsidian or VS Code — edits, rejects, or accepts in place
  4. On approval, AI copies REVIEW.md to _meta/batch-reviews/{batch-id}.md, moves accepted files to final locations, updates Person/Glossary indexes, commits in one atomic operation

Batch ID naming

Primary pattern: {resource-class}-{chapter-slug} (e.g., csg-01-03, br-07-methods-for-transitioning). Fallback for non-resource batches: short topic slug (e.g., worship-leader-grilling). Sequential batch-0## IDs are deprecated — they gave no signal about batch content without opening the file.

REVIEW.md

Every batch’s REVIEW.md includes:

  • Summary of what was added/changed
  • Tag requests (new tags AI wants to add, with justification)
  • Suspected duplicates AI couldn’t resolve
  • Proposed work section (see ADR-0014): open questions / proposed threads / stale wrestling
  • Cost report (script-mode only; see ADR-0011)

Pre-commit hook

A small Python script (~50 lines) enforces the AI hard rules from CONTEXT.md. AI cannot bypass — failed hook = failed commit = AI must fix and retry.

Alternatives considered

  • A. Full autopilot (no review gates): rejected — drift detected too late.
  • B. Per-note pre-commit review: rejected — every note = a conversation turn; slow, token-expensive, no chance to see notes in context of each other.
  • Review in chat instead of in Obsidian: rejected — chat review forces serial reading, loses spatial context. Obsidian/VS Code lets user see multiple drafts at once and catch duplicates.

Consequences

  • (+) Bulk efficiency with bounded review effort per sitting
  • (+) Spatial review (graph view, multi-file open) catches near-duplicates
  • (+) Pre-commit hook = drift insurance, hardcoded
  • (−) /staging/ adds folders to track; staging folders are retained in git as a permanent record of exact proposals reviewed
  • (−) Hook = a small piece of code to maintain (small price for the safety net)

Graph View