Co-locate concept rules and caveats

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

Write a retry runbook where readers need both candidate-error definitions and a non-idempotent-write exception. Teaching rules treat a transient network failure as a candidate, but a write without idempotency guarantees cannot be retried automatically just because of that failure. Scattering these pieces exposes incomplete rules.

Mechanism

Choose shared-step versus branch-reference tiers, then organize one concept together at the chosen location. The retry decision points to one maintained policy containing definition, eligibility, non-idempotent exception and stop conditions. Shared tasks reference it instead of duplicating versions. Reading the rule should also expose its limits.

Bad example

Put network-error definitions at the beginning, retry eligibility at the end and non-idempotent restrictions in setup notes. Let a reader retry as soon as a network error matches the table.

Good example

Create one retry-policy section containing candidate definitions, eligibility, the non-idempotent-write exception and stop conditions. Read it at the retry decision. In this teaching contract, a transient failure is a candidate only: establish safe repeatability first, and do not automatically retry writes lacking that guarantee. Keep one maintained reference, not hidden exception copies.

Why the change matters

Scattering makes it easier to read a general rule without its exception. Co-location supports decisions based on complete conditions, while information hierarchy still determines entrypoint versus disclosed material.

Observable expectation

For a teaching non-idempotent write with a transient network failure, the reader sees the exception in the same section and stops automatic retry. A safely repeatable operation still needs eligibility and bound checks.

Inspect reachable maintained references and adjacent caveats, not merely the word idempotent somewhere in the document.

Limits

Co-location does not mean putting every resource into one file or duplicating shared references. Real eligibility, attempt counts and idempotency follow the service contract. The example is not a validated production retry policy.