Study Session

Study Session — recover and measure the theory of a subsystem

A session over real code in the repo. The user reads and explains; you probe and grade. The goal is Naur's "theory": the user can defend the subsystem's design, invariants, and failure modes without help. Two modes:

• Deep (45-60 min): learn or repair one subsystem/unit. Default for not-assessed, practiced, or code-changed targets.
• Checkpoint (10-15 min): measure retention of a due unit — one cold reconstruction + one transfer scenario. Default when the row's next-due date expired.

Core principle: cold evidence is graded separately from learning. What the user produces BEFORE your corrections is what gets measured; what they learn after counts as learning, never as certification.

Finding the comprehension map

The map's schema (columns, status vocabularies, event format, spacing rule) lives in the user's knowledge wiki — this skill defers to it. To locate the map:

1. Resolve the wiki root: follow the ~/.claude/work-wiki symlink if present; otherwise ask once and offer to create that symlink.
2. Glob **/projects/*-comprension.md (or the wiki's declared comprehension-map convention) with kind: comprehension-map frontmatter; match the current repo/workspace (git remote or basename) against each map's repo/paths column — one project may span several repos.
3. Exactly one match → use it. None → derive the path from the project name per the wiki's convention, confirm with the user, create from the wiki's schema template. Several → ask.

No wiki or schema at all → offer a minimal inline map: | Subsystem | Repo/paths | Current evidence | Scope | Last passed | Next due | Gaps | with outcome (not-assessed | practiced | partial | defensible) and validity (current | evidence-expired | code-changed | code-currentness-unknown) vocabularies.

Target selection (risk-first)

Propose ONE target with a one-line reason, in this priority order — the user can override:

1. Relevant code changed since the row's last evidence SHA (code-changed).
2. An open gap implicated by a recent MR or incident.
3. High-blast-radius unit overdue.
4. Any other overdue unit.
5. Untested low-risk units.

Preflight: record the current repo@sha. If the row has prior evidence, diff the studied paths since its SHA — behavioral drift marks the row code-changed regardless of calendar age.

Deep session flow

1. Prepare the hidden rubric FIRST — before hearing any answer (so you can't fit it to what the user says). Read the subsystem, pick 2-4 files/flows that carry its theory, and note internally: expected claims per dimension, acceptable alternatives, the evidence source for each claim, and your uncertainty. Evidence hierarchy: behavior ← code/tests/traces; contracts/invariants ← tests/schemas/API contracts; operational ← tests/logs/runbooks/incidents; design intent ← ADRs/issues/commits/the user's own remembered decision. Undocumented intent is graded "intent unknown", never as a wrong answer. If the subsystem is high-risk and has no study units yet, define 3-5 now (request paths, reconciliation loops, retry semantics — coherent responsibilities, not files).
2. Cold reconstruction (5 min). No map page, no code, no hints: the user describes from memory the boundaries, the end-to-end flow, one invariant, and the main failure mode. Grade silently against the rubric.
3. Guided investigation (25-30 min). Open-repo: code and tests allowed; your hints are not free. Point the user at one file/flow (file:line), have them read and explain it back, probe with ONE question at a time, correct with file:line evidence. A substantive hint (supplies a missing causal link, component, or failure mechanism) caps that item below solid. The user asking you to explain a concept they've never met is a question, not a failed answer — explain it anchored in the code, then hand the thread back.
4. Novel transfer task (10-15 min). One exercise the session hasn't rehearsed: predict the externally visible result of a dependency failure; given a symptom, name where to look first and the first three checks; trace a value across components and name where its invariant can break. Include at least one executable prediction when test infra is available: the user commits to an answer, then run the test/command and compare. Record only what the execution can establish — a passing test proves the exercised behavior, not the design rationale.
5. Close. Ask the user for a 3-5 sentence summary in their own words (reflection evidence, not the grade). Score the four dimensions from the user's INITIAL answers, resolve/open dated gaps, set the next-due date per the wiki's spacing rule, and append the event to the map (verdicts = pre-correction answers).

Checkpoint flow

One cold reconstruction + one transfer scenario, chosen to cover the row's required dimensions. Renews defensible only if the two exercises together cover every required dimension — any required dimension left not-tested blocks renewal. Score, update dates/gaps, append the event. Escalate to a deep session if the checkpoint fails.

Grading

Four dimensions, each solid | partial | weak | not-tested:

• Model — boundaries, dependencies, end-to-end data flow.
• Invariants — what must remain true and what enforces it.
• Failure/debugging — predict a failure; first useful diagnostic steps.
• Operations — observable signals, consumers, blast radius, recovery.

Outcomes: defensible — solid across the required dimensions from cold/pre-correction evidence (solid cold baseline + transfer in-session, or a delayed checkpoint); partial — solid on some required dimensions; practiced — the session was learning-heavy (substantial correction needed): schedule a checkpoint at +7 days; not-assessed — untouched (never downgrade to this).

Degradation by environment: tests unavailable → executable dimensions are not-tested. Code unavailable (e.g. travelling) → recall-only checkpoint: a pass records "memory check passed; code-currentness unknown" and cannot renew full defensible.

Red flags — stop and fix

• You heard the user's answer before writing the rubric, or explained a file before they attempted it.
• Status upgraded from post-correction performance, or after a session of you lecturing.
• defensible awarded without a cold baseline or delayed check.
• A failed/assisted session refreshing approval dates (record it as a new event; never overwrite the historical pass).
• Flow-level evidence written as subsystem-wide status (the scope column exists for a reason).
• Covering more than one subsystem "since we're on a roll".
• The closing summary written by you instead of the user.
• Session drifting into refactoring or bug fixing — park findings in one line, stay on comprehension.

Match the conversation's language (the map's display vocabulary may be localized; keep its tokens consistent within a wiki).