> ## Documentation Index > Fetch the complete documentation index at: https://agentconcepts.io/llms.txt > Use this file to discover all available pages before exploring further. # grain > The level of resolution at which an entity is individuated — its identity-grain. Confused grains produce locally-correct but aggregation-wrong bugs. computer-science # Grain ## Description The *level of resolution* at which an entity is individuated — its identity-grain. Every named entity has a grain: a session has session-grain, a user has user-grain, a field has field-grain, a program has program-grain. Grain matters because decisions that look like single choices are often two entangled decisions — "what rule applies?" and "at what grain does it apply?" Confusing grains produces bugs with a characteristic signature: behavior that seems correct locally but breaks at the wrong level of aggregation or disaggregation. The *grain-coupling move* is the key diagnostic: when a decision behaves differently depending on the grain at which you inspect it, you've found grain-coupling. The move is to *decouple* the grains — identify that what looked like one decision was actually two, each operating at a different level of resolution. This is structurally analogous to separating orthogonal axes of variation in matrix decomposition: what appeared as a single blob has identifiable components. ## Triggers **User-initiated:** User is asking about granularity, resolution, or the "unit" of something. Also when a bug is described as "correct in some cases but wrong in aggregate" or "works for one X but breaks for multiple Xs." **Agent-initiated:** Agent notices a rule or design decision that appears to operate at multiple levels simultaneously without explicit handling for the level mismatch. Candidate inference: "this decision is grain-coupled — what are the two (or more) distinct grains entangled here, and which grain is load-bearing for each sub-decision?" **Vocabulary cues:** "per-session," "per-user," "per-field," "per-item," "per-request," "granularity," "resolution," "unit of X," "what counts as one X," "level of detail," "aggregate," "disaggregate." **Situation-shape signals:** A rule that feels right at one level of inspection but wrong at another. A design decision where reasonable people disagree because they're implicitly using different grains. ## Exclusions * **Uniformly single-grained systems** — a system where all decisions operate at a single, unambiguous grain has no grain-coupling to diagnose. The concept earns its keep when multiple grains are in play simultaneously. * **When "granularity" is just a detail choice** — adjusting resolution along a dimension that doesn't affect correctness (e.g., choosing how many decimal places to display) doesn't require the grain frame. Grain matters when the resolution choice affects *what rules apply* or *what counts as the same entity*. * **Pure aggregation** — when explicitly summing over a dimension (total users, total events), the grain is the aggregate itself and usually isn't ambiguous. ## Structure Internal structure of grain: a table of its component slots and the concepts that fill them. ## Relationships Relationship neighborhood of grain: a graph of the concepts it connects to and the concepts it is a part of. * [stack-layer](/concepts/stack-layer) — *composition relationship* — grain and stack-layer often co-occur: layers in a stack operate at different grains, and grain mismatches across layers produce characteristic bugs. The grain diagnostic complements the load-bearing-layer diagnostic. * [load-bearing](/concepts/load-bearing) — *composition relationship* — "what is the grain of this decision?" is a load-bearing question: it determines which operations are valid at which level. A decision at the wrong grain is not load-bearing in the right place. * [uniformity-dividend](/concepts/uniformity-dividend) — *composition relationship* — a uniformity dividend requires all instances to share the same grain. If grains differ, uniformity is illusory (the invariant doesn't hold across the dimension being standardized). * [cadence](/concepts/cadence) — *composition relationship* — cadence choices are implicitly grain choices: "daily cadence" is day-grain; "per-event cadence" is event-grain. Cadence mismatches (process grain ≠ data grain) are a common source of accumulation error. * [doctrine](/concepts/doctrine) — *composition relationship* — a doctrine applied at the wrong grain is ineffective or harmful. Doctrine entries should specify their grain explicitly: "when \[condition] at \[grain], apply \[rule]." ## Examples In Ralph Kimball's dimensional modeling, the second step of designing a fact table is *declare the grain*: fix exactly what one row represents — one row per order line, or per whole order, or per daily snapshot — before choosing any dimension or measure. The grain is a binding contract; every column added afterward must be true at that level. Get it wrong and the arithmetic silently breaks: mixing an order-grain row in with line-grain rows double-counts revenue, and totals that looked right per-order come out wrong in aggregate. Declaring the grain first is naming the resolution at which the table's rows are individuated — and it is what keeps the sums honest. a policy that should apply per-field is incorrectly applied per-record, or vice versa; the bug appears as incorrect aggregation. a "session" in Claude Code has session-grain for some properties (conversation history) and program-grain for others (working directory). Confusing them produces context-management bugs. "daily" vs. "weekly" vs. "per-event" cadences are grain choices. A process whose grain mismatches its data source accumulates systematic error. what constitutes "a program" varies by grain: file-level, module-level, repository-level. The level at which identity is asserted determines which operations are valid. whenever this question produces disagreement, grain-coupling is present.