Zettle

0021-foundation-pass-workflow

7 min read

ADR-0021: Foundation-pass workflow with parking lot

Status: Accepted Date: 2026-05-22 Amended: 2026-05-24 — productionized by ADR-0023 (process_batch.py atomize). REVIEW.md lean shape gains one extra ## Linking applied sub-section when output is script-generated; ADR-0023 governs the contents. Variant-2 (foundation-pass) semantics and parking-lot behavior unchanged.

Context

ADR-0009 established a single batch-staging review workflow. In practice that workflow has produced two distinct rigor profiles:

  • Thorough rigor (BR ch 0–8; CSG Book 1 ch 1–4 + secondary pass). Per-chapter REVIEW.md grows to 5–12k words. Each batch synthesises atomics AND seeds threads AND verifies counter-arg citations AND assesses cluster support. Time-per-chapter is hours; the final secondary-pass batch upgrades earlier work to current-rigor parity (_meta/batch-reviews/csg-01-secondary-pass-phase-2.md).
  • Foundation rigor (this ADR). The user wants atomics extracted across all remaining DP (~25–30 ch), CSG Books 2–16 (~150 ch), and WS (22 ch) — ~200 chapter-sessions total — before threads, counter-arg research, or secondary rigor pass are sensible. Threads emerge cleanest from cross-chapter cluster recognition over an existing atomic corpus; pulling them into a per-chapter session forces seeding on isolated material and produces threads that get re-done in any case.

ADR-0009 doesn’t accommodate this split. A second pain point: live judgements made during a foundation session (“this would make a good thread once the cluster exists”, “this question needs answering once DP is ingested”, “this counter-argument needs a primary critic before it’s defensible”) get buried in per-chapter REVIEW archives. A future weaving pass that scans the full _meta/batch-reviews/ archive across ~200 batches is reading ~750k tokens — not a workable index.

Two changes needed: a leaner batch profile for foundation work, and a structured parking lot to carry deferred judgements forward.

Decision

Two variants of the ADR-0009 workflow, opted into per batch via batch ID convention and REVIEW.md shape.

Variant 1 — Thorough (default for one-off / load-bearing work)

Unchanged. ADR-0009 § “Gate 2 — Batch review” governs. REVIEW.md uses the full shape (summary + tag requests + suspected duplicates + ADR-0014 “Proposed work” with full reasoning + cost report). Used for: secondary-pass rigor upgrades, content-cleanup batches, and any chapter the user designates load-bearing.

Variant 2 — Foundation-pass (atomics-only, lean REVIEW, parking lot)

Used during the foundation-pass project (DP → CSG Books 2–16 → WS). REVIEW.md uses a lean shape; deferred judgements append to _meta/parking/.

Lean REVIEW shape

# Batch Review — {batch-id}

**Source:** {resource file path}
**Scope:** {N} atomics + {M} glossary stubs (if any)
**Date:** {YYYY-MM-DD}
**Variant:** foundation-pass

## Atomics
{table: file | title | tags}

## Glossary / Person updates
{any new stubs, or atomics that filled out a pre-stubbed entry's body}

## Suspected duplicates / cross-batch notes
{1–3 lines per item; reference existing atomic by wikilink}

## Tag-registry requests
{none, or a small table with justification}

## Parked items (also appended to _meta/parking/)
- Threads: {N entries — see _meta/parking/threads.md}
- Questions: {N entries — see _meta/parking/questions.md}
- Web-search: {N entries — see _meta/parking/web-search.md}

## How to review
{terse: review atomics in /staging/{batch-id}/, accept or edit; say "approved" to finalize}

No counter-argument verification section. No secondary-pass commentary. No cost report (pilot mode — Anthropic dashboard suffices). Target: ≤3k words per REVIEW.

Parking-lot files

Three append-only files under _meta/parking/:

  • threads.md — thread candidates surfaced during foundation work
  • questions.md — question candidates not yet promoted to /questions/
  • web-search.md — counter-arg citations / primary critics to verify in weaving pass

Entry format (one line per entry; breadcrumbs back to REVIEW and source):

- [{batch-id}] **{title-hint}** — anchors: [[atomic-a]], [[atomic-b]] | trigger: {source-section ref} | one-line: {why-it-might-thread} | review: {batch-review filename}

Adapt fields per file:

  • threads.md — anchors are atomics; one-line is the thread-claim seed
  • questions.md — anchors are the triggering atomic(s); one-line is question text + priority
  • web-search.md — one-line is “verify {critic name} ({work}) {year}” with the thread/atomic that needs it

Finalize step (Variant 2)

In addition to ADR-0009’s finalize (move atomics, copy REVIEW to _meta/batch-reviews/{batch-id}.md, update Person/Glossary ## Referenced by for any pre-stubbed entry hit by new wikilinks, delete now-empty staging folder, commit):

  1. Append each parked item from REVIEW.md’s “Parked items” section to the matching _meta/parking/*.md file under a ## {batch-id} — {YYYY-MM-DD} heading.
  2. The append is part of the same commit as the staging move.

The parking-lot files are the index the weaving pass reads. REVIEW.md remains the audit trail (in _meta/batch-reviews/) for any item that needs cold-context recovery.

Default-promote rule for questions (ADR-0014) still applies — adapted

ADR-0014 specifies that proposed questions default-promote to /questions/ unless the user rejects specific ones. Under Variant 2 the default flips: proposed questions default-park to _meta/parking/questions.md (not promoted to /questions/). Promotion to a real Question note happens during the weaving pass, when cluster support and answering threads are in scope. Rationale: ~200 foundation sessions × 1–3 questions each = ~400 Question notes most without an answering thread anywhere near; that’s index pollution. The parking lot keeps them visible without polluting /questions/.

If the user wants a foundation-pass question promoted immediately (“this one’s worth a Question note now”), they say so during review and the AI promotes it the normal way.

Batch ID convention

Variant 2 batches use the same {class}-{NN}-{slug} pattern. The Variant: foundation-pass line in the REVIEW frontmatter / header is the marker. No separate ID namespace.

Alternatives considered

  • A. Keep one workflow; just truncate REVIEW shape per-batch by judgement. Rejected — invites drift and “is this thorough or lean?” ambiguity per batch. Explicit variants are cheap to maintain and clearly auditable in _meta/batch-reviews/.
  • B. Parking inside REVIEW.md only (no separate _meta/parking/ files). Rejected — at ~200 lean REVIEWs the weaving pass would scan ~600k tokens of REVIEW archive to inventory parked items. Structured parking files are ~100k tokens for the same inventory and grep-able.
  • C. Parking-only (skip REVIEW.md duplication). Rejected — REVIEW.md remains the audit trail for the user’s per-batch review (need to see the parked items in context of the batch they came from). The duplication is small (one-line entries echoed from REVIEW into parking on finalize).
  • D. Single _meta/parking.md with H2 sections per type. Rejected — file grows unbounded; threads/questions/web-search benefit from separate grep-able files (different consumers at different times during weaving).
  • E. Promote all proposed questions immediately per ADR-0014 default. Rejected — see “Default-promote rule” above; foundation pass would produce ~400 mostly-orphan Question notes.

Consequences

  • (+) Foundation pass is achievable in bounded time (~200 lean sessions @ ~30–45 min each vs ~hours each at thorough rigor).
  • (+) Parked judgements survive the foundation-pass-to-weaving-pass transition without scraping the REVIEW archive.
  • (+) /questions/ index stays meaningful (only promoted questions, not foundation-pass speculation).
  • (+) Pre-commit hook (ADR-0017, scripts/pre-commit-hook.py) requires no changes — it operates per-file by type and doesn’t inspect REVIEW.md shape.
  • (+) Thorough rigor is still on the table — secondary-pass-style batches (e.g., csg-01-secondary-pass) remain Variant 1 and stay rare but allowed.
  • (−) Two REVIEW shapes to remember. Mitigated by the Variant: header field and explicit examples in _meta/batch-reviews/ (the first foundation-pass batch becomes the canonical example).
  • (−) _meta/parking/*.md files grow long over the foundation pass. Acceptable — they are append-only, grouped by {batch-id} heading, and the weaving pass is their consumer. If a parking file gets unwieldy mid-pass, split by class (e.g., threads-dp.md, threads-csg.md); decide then, don’t over-engineer now.
  • (−) Some thread/question candidates surfaced during foundation will turn out wrong (cluster never materialises). Acceptable — parking is cheap; the weaving pass triages.

Graph View