Design review template

Reference: DATA_MODEL_DESIGN_CHARTER.md. Replace bracketed prompts with evidence. Remove irrelevant sections with a brief scope note rather than inventing requirements. For a small change, use a compact version of this template.

1. Decision and scope

Proposal: [Name and short description.]
Status: [Proposed / interface-checked / implemented / tested; use claim-specific labels.]
Reviewer / author: [Person, agent, or accountable role.]
Affected revisions: [Model/schema/implementation identifiers as applicable.]

Observable outcome: [What becomes possible, safer, simpler, or measurably better?]

Baseline: [Existing design and relevant limitations.]

Supported scope and non-goals: [State which capabilities and guarantees are actually in scope.]

Constraints and uncertainty: [Scale, deployment, compatibility, correctness, external interfaces, unknowns.]

2. Authority and lifecycle map

Deliberately opaque behavior: [What is outside the declarative model, why, and which contract governs it?]

Identity behavior: [Rename, reorder, reserialize, regenerate, duplicate, split/merge if applicable.]

3. Semantic contracts and invariants

Absence and uncertainty: [Distinguish unspecified, unknown, not applicable, uncertain, invalid, partial, failed, or other relevant states.]

Equivalence requirements: [Byte / structural / semantic / approximate; tolerances and assumptions.]

4. Derivation and execution design

Relationship structures: [Distinguish ownership, connectivity, dependency, scheduling, provenance, and other graph meanings.]

Provider selection and limitations: [Selected version, required capabilities, supported subsets, unsupported behavior.]

Boundary contracts: [Schema, identity, metadata, encoding, ownership/lifetime, batching, conversions, and possible loss.]

Coherent publication: [What becomes visible, when, and under which consistency protocol?]

5. Representative journeys

Ordinary extension

[Trace one realistic new rule, entity, provider, or policy. Identify new semantic decisions, specialized implementation, generated artifacts, and tests. Distinguish multiple files from duplicated meaning.]

Meaningful change

[Trace a changed specification, policy, structural definition, or assumption. Explain identity, invalidation, retained artifacts, and semantic diff.]

Boundary or alternate representation

[Trace meaning through serialization, a language bridge, a backend, or another physical layout. State what is preserved or deliberately omitted.]

Interruption or failure

[Trace cancellation, crash, retry, unsupported capability, or invalid input. Explain observable state, valid partial outputs, effects already performed, and recovery.]

6. Acceptance gates

An unresolved gate is not a pass. A high score elsewhere cannot offset a failed required gate.

7. Principle findings

Applicability: [Which groups are relevant and why? Do not restate all 60 principles for every change.]

Optional maturity assessment: [Use charter dimensions only when helpful. Separate current evidence-supported scores from proposed targets and disclose reweighting.]

8. Alternatives and architectural leverage

Abstractions justified by current needs: [Explain registries, compilers, generators, services, stores, and engines that add material complexity.]

What remains ordinary code: [Specialized algorithms and mechanisms that should not be turned into an unnecessary DSL.]

9. Verification and measurement plan

Include relevant round-trip, differential, metamorphic, negative, migration, concurrency, and interrupted-publication checks. Do not assume independent-looking backends constitute independent correctness oracles.

Cost accounting: [Construction, validation, preparation, transfers, execution, storage, recovery, inspection, memory; only the material categories.]

10. Exceptions and unresolved decisions

Principle IDs: [IDs.]
Scope: [Where the deviation applies.]
Reason and alternatives: [Why the preferred default is not suitable.]
Consequence and compensating controls: [What is weakened and how risk is managed.]
Evidence: [Support for this choice.]
Owner / accountable role: [Who maintains the exception.]
Revisit trigger: [A concrete change, scale, capability, or other condition.]

A SHOULD-level exception can be accepted with justification. A MUST-level gap requires narrowing the supported claim or recording the design as unresolved for the affected requirement.

11. Decision and implementation changes

Decision: [Accept / accept scoped design with documented SHOULD deviations / revise / reject.]
Reason: [The strongest evidence and remaining limitations.]

Final check: The design’s claims match the evidence; the scope matches the implemented guarantees; and later extensions have a clear, validated path.