majiayu000 CE ADR Consult
You are identifying which ADRs govern a proposed change and extracting their binding constraints. ADR decisions take precedence over the release plan whenever they conflict (execution-plan.instructions.md §3).
ADRs live in docs/improvement/adrs/. Superseded ADRs are prefixed with
superseded and should not be consulted for new work.
Quick lookup by change type
| Changing / implementing | Governing ADR(s) |
|---|---|
| Module / package boundaries | ADR-001 |
| Exception types or validation | ADR-002 |
| Caching (key design, eviction) | ADR-003 |
| Parallel execution / fallback | ADR-004 |
| Explanation payload schema / JSON | ADR-005 |
| Plugin registration / trust | ADR-006, ADR-033 |
| PlotSpec / visualization IR | ADR-007, ADR-016 |
| Explanation domain model | ADR-008 |
| Input preprocessing / mapping | ADR-009 |
| Evaluation vs core split | ADR-010 |
| Deprecation or migration | ADR-011 |
| Documentation build | ADR-012 |
| Interval calibrator plugin | ADR-013 |
| Plot plugin | ADR-014 |
| Explanation plugin | ADR-015, ADR-026 |
| PlotSpec schema versioning | ADR-016 |
| Legacy user API changes | ADR-020 |
| Calibrated intervals / semantics | ADR-021 |
| Matplotlib test coverage | ADR-023 |
| FAST feature filtering | ADR-027 |
| Logging and observability | ADR-028 |
| Reject/abstain strategy | ADR-029 |
| Test quality enforcement | ADR-030 |
| Serialization / save_state | ADR-031 |
| Guarded explanations | ADR-032 |
| Modality extension / packaging | ADR-033 |
How to consult an ADR
- Locate the file:
docs/improvement/adrs/ADR-<NNN>-<slug>.md - Check
Status:— skip ifSuperseded. - Read the Decision section to extract binding constraints.
- Note the Consequences section for risk awareness.
- Check the
docs/improvement/RELEASE_PLAN_v1.mdentry for the ADR to see which release milestone closes outstanding gaps.
# List all active (non-superseded) ADRs
Get-ChildItem docs/improvement/adrs/*.md | Where-Object Name -NotMatch '^superseded'
Key invariants summary (most commonly hit)
ADR-001 — Core / plugin boundary
core/must never import fromplugins/.- New functionality →
plugins/; delegation → via registry incore/.
ADR-002 — Exceptions
- No bare
ExceptionorValueErrorin public-facing code. - Use
calibrated_explanations.utils.exceptions.*.
ADR-006 — Plugin trust
- Third-party plugins: opt-in trust required (
trust_plugin()/ env var / pyproject). - Built-ins: auto-trusted.
ADR-011 — Deprecation
- Minimum 2 minor releases before removal.
- Legacy User API (ADR-020) exempt; follows "Major Only" lifecycle.
ADR-013 — Interval plugin
predict_probamust delegate to VennAbers/IntervalRegressor reference.IntervalCalibratorContextis read-only; plugin must not mutate it.
ADR-021 — Interval semantics
- Invariant:
low ≤ predict ≤ highmust always hold.
ADR-023 — Matplotlib exemption
viz/matplotlib_adapter.pyis excluded from coverage reporting.- Tests run normally with
pytest --no-cov -m viz.
ADR-030 — Test quality
- Coverage gate: 90%+ (excluding ADR-023 exemption).
- Naming:
test_should_<behavior>_when_<condition>.
ADR-031 — Serialization
- All calibrators must implement
to_primitive()/from_primitive(). schema_versionmandatory; fail-fast on incompatible version.
ADR-032 — Guarded explanations
- Use
explain_guarded_factual/explore_guarded_alternativesfor unknown distributions.
ADR-033 — Modality extension
- Non-tabular modality code must NOT enter
core/. data_modalitiesandplugin_api_versionrequired inplugin_meta.
Conflict resolution
When a release plan step and an ADR conflict:
- The ADR takes precedence.
- Document the conflict in the PR.
- If the plan needs to supersede the ADR, a new ADR or ADR update is required first.
Evaluation Checklist
- All governing ADRs identified for the proposed change.
- Status field checked (not
Superseded). - Decision section read; binding constraints listed.
- No ADR constraint violated by the proposed implementation.
- Release plan milestone for outstanding gaps noted and respected.