Skip to content

Session start

When opening a fresh Claude Code session in this repo, run this protocol before proposing any work.

(1) Read these in order

  • docs/pipeline/session-<latest-date>-handover.md — the most recent dated handover (the previous session's wrap)
  • docs/pipeline/decisions/0001-component-library.md
  • docs/pipeline/decisions/0002-primitive-neutrality.md
  • docs/pipeline/decisions/0003-assembler-fulldev.md
  • docs/pipeline/decisions/0004-adapter-pattern-and-loud-fail.md
  • docs/pipeline/decisions/0005-image-pipeline.md
  • ...and any newer ADRs in numerical order
  • docs/pipeline/known-patterns.md
  • docs/pipeline/known-issues.md

(2) Forced summary in your own words, under 200 words

Tell the user, in your own words, in under 200 words:

  • The architectural shape of the system today
  • The loud-fail discipline and where it operates
  • The top 3 open questions from known-issues
  • What you understand the next priority to be

The forced-summary step is non-negotiable. It surfaces misreadings before they become wrong work.

(3) Wait for confirmation

Don't propose work yet. Wait for the user to confirm or correct your understanding before planning the hour.

The session-wide rule

The wiki is the source of truth. If you find yourself uncertain about a past decision, check the ADR. Don't re-derive.

…but a DECISION is not a DIAGNOSIS, and neither is a proposed fix

The rule above applies to decisions (ADRs) and to measurements. It does not apply to a proposed fix that no session ever ran. Those have been wrong every time it mattered:

  • "make the ranker prefer a high-confidence logo cluster" → would have broken garvanbay
  • "re-run the dup-collapse after the re-match" → would have collapsed zero pairs
  • "widen the heading-gated regex" → would have hidden the missing-video debt

In every case the observation beside the proposal was correct. The failure is the inference, not the evidence.

Entries marked Fix candidate — UNTESTED HYPOTHESIS are leads, not plans (see session-end). Older entries pre-date the marker and are not labelled — so apply the test yourself: does this proposal claim to know WHY? If so, re-measure before you build on it. A wiki claim that something works, is reproducible, has no source, or would be fixed by X deserves one command's worth of scepticism.

And when you brief a subagent, do not launder an unverified wiki claim into a stated fact. That happened on 2026-07-14: the orchestrator asserted a fabricated mechanism in a brief, and it was caught only because the subagent measured the DOM instead of believing it.

Example of the rule applied

A fresh session asks "should we use the per-site bucket or the single bucket for CMS images?" — don't reason from principles. Open decisions/0005-image-pipeline.md §1. The answer is locked.

Forced summary catches drift

The forced-summary step is non-negotiable for a reason: when the wiki and the user's mental model have drifted apart, the user can catch it before any work lands on top of the wrong picture.

2026-05-11 example. A session-start summary stated the next priority as "Slice 3 — SDK swap". The user corrected: Slice 3 has always been transformer integration; the SDK swap is Slice 4 (a new slice added during Slice 2's wrap-up). The wiki had been retroactively renumbered in three files (handover, ADR-0005 Slice tracker, known-issues, implementation-slice example), treating slice numbers as reorderable rather than as stable identifiers. The summary surfaced the drift; a 10-minute pre-Slice-4 wiki numbering correction restored the original numbering across all four files before any code work began.

If the summary had been skipped — or had paraphrased the wiki without the user's eyes on it — the SDK swap would have shipped under "Slice 3", silently making the renumbering canonical. The correction would have been twice as expensive after the fact, with commits and protocol-doc examples already referencing the wrong numbers.

Detection rule: treat slice numbers, ADR numbers, and any identifier the wiki uses as a stable handle as append-only. A new slice gets a new number; an existing slice's number doesn't change because its execution order shifted. The forced-summary step is where number drift is cheapest to catch.