01 / Behavioral framing
Define a concrete trigger for reconsidering complexity
Group related findings by root cause and reassess the full diff against the original requirement. This stops review fixes from accumulating compatibility branches without revisiting the design.
Source excerpt starting at line 70.70When related findings repeatedly expand the same design, stop adding conditions, group root causes, and reassess the complete diff against the original requirement. A second related finding that adds another compatibility case or protocol hop triggers this reset. Prefer deleting unsupported branch-local machinery or rejecting unsupported inputs with an existing alternative. Follow `$implementation-strategy` for the detailed reset procedure; preserve released contracts and unrelated user changes.
02 / Contribution etiquette
Separate documentation need from release timing
Required documentation for behavior absent from the latest release belongs in separately timed work. The rule distinguishes missing content from content that would be inaccurate if published with the current feature PR.
Source excerpt starting at line 54.54Determine whether documentation is required separately from deciding which pull request should carry it. When required `docs/` content would describe behavior that is not available in the latest published release, classify it as separately timed documentation work rather than a missing deliverable or blocking finding for the feature or bug-fix pull request. This timing rule takes precedence over general documentation-completeness requirements in code-review rules, pull-request guidance, and repository skills. It applies to `docs/` content, not automatically to examples or code-level documentation that ships with the changed API.
03
Treat public argument order as compatibility
The guide includes positional parameters and dataclass fields in the exported API contract. That makes seemingly additive changes subject to the behavior existing callers rely on.
Source excerpt starting at line 80.80Treat the parameter and dataclass field order of exported runtime APIs as a compatibility contract.
04 / Verification by change type
Test the operation that survives a race
Concurrency evidence must control completion order and inspect surviving work and shared state. Merely running sequential happy paths cannot establish whether stale work overwrites a newer operation.
Source excerpt starting at line 124.124- Require representative regression coverage for the accepted behavior and intentionally unsupported category. For concurrency findings, require controlled completion ordering plus assertions about the surviving operation and final shared state. Do not request exhaustive tests for every constructible permutation.
05 / Behavioral framing
Require an independent oracle for test expectations
Tests must exercise the stable caller-visible boundary that owns the outcome. Assertions that mirror helper calls or recompute expectations with implementation logic are explicitly insufficient.
Source excerpt starting at line 123.123- Treat tests as contract evidence only when they exercise the highest stable caller-visible boundary that controls the observable result and derive expected behavior from the requirement, released behavior, a worked example, a baseline, or another independent oracle. Do not accept helper-only call-shape assertions or expected values recomputed with the implementation's own logic when another layer owns the outcome.
06 / Behavioral framing
Write source documentation for reliable translation
English source must state actors, ownership, ordering, and lifecycle explicitly while preserving API names and meaning. Ambiguity becomes a compatibility risk for generated translations.
Source excerpt starting at line 90.90- Treat translation-safe English as a documentation compatibility requirement. In new or materially rewritten translatable prose under `docs/` (excluding generated API reference pages), state the actor, scope, ownership, ordering, modality, and lifecycle boundary explicitly whenever they affect the meaning. Use exact API identifiers in inline code, and replace ambiguous pronouns, overloaded nouns, or shorthand when a small clarification can prevent a materially different translation. Do not change the documented behavior merely to make a sentence easier to translate.
