Skip to content

claims.md

Latest commit

 

History

History
154 lines (127 loc) · 7.88 KB

claims.md

File metadata and controls

154 lines (127 loc) · 7.88 KB
Raw
title Claims, Evidence, Decisions, and Actions Contract
version 0.5.1
status Pilot
provider_independent true
owner Engineering
last_updated 2026-08-25

Claims, Evidence, Decisions, and Actions Contract

Make material workflow reasoning traceable from an observed fact to an approved action.

This contract is the shared reasoning record for every playbook. It does not replace the work record or a playbook-specific artifact. It defines the IDs and relationships that let a reviewer challenge a conclusion without relying on an AI-generated summary alone.

Normative Language

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are normative. They mean respectively: required, prohibited, recommended unless a documented reason applies, discouraged unless a documented reason applies, and permitted.

flowchart TB
    evidence["Evidence: observed source-backed fact"] --> claim["Claim: interpretation supported by evidence"]
    claim --> decision["Decision: selected option or scope choice"]
    decision --> action["Action: approved change or next step"]
Loading

Definitions

Type Meaning
Evidence A source-backed observation, measurement, or external result. Evidence may be verified, inferred, hypothesized, contradicted, or unknown.
Claim A material statement derived from one or more evidence items. A claim must identify its supporting evidence and confidence.
Material assumption A claim with status: assumed: a necessary but unverified working premise that has an owner, impact, and validation method.
Decision A selected option, scope boundary, or disposition based on claims. A decision identifies its owner and approval status.
Action A concrete implementation, validation, documentation, or follow-up step derived from a decision.

Referential Integrity

A terminal work record MUST form a complete reasoning chain:

  • every action references an existing decision;
  • every decision references one or more existing claims;
  • every claim references one or more existing evidence records;
  • every evidence record names a source; and
  • no evidence, claim, or decision record is orphaned from the chain that reaches an action.

The framework validator checks these relationships for populated work records. Draft records may be incomplete while a run is active, but they MUST pass before terminal handoff.

Evidence refs is a typed field: every reference must be an exact ID present in the current record's Evidence table. IDs from another section, such as an experiment or check (CHK-*), are not evidence references; copy the source-backed result into an Evidence row and reference that Evidence ID. References must be individual IDs, never prose, grouped IDs, or ranges.

Required fields

Evidence

Field Required Description
evidence_id Yes Stable ID within the work record, such as evidence-001.
observation Yes What was observed, without adding interpretation.
source Yes Repository path, ticket, log, command, scanner, or other source.
observed_at Yes When the observation was collected.
worker Yes Worker that collected or preserved the evidence.
status Yes verified, inferred, hypothesized, contradicted, or unknown.
notes Recommended Scope, limitations, or conflicting evidence.

Claim

Field Required Description
claim_id Yes Stable ID within the work record, such as claim-001.
statement Yes The material conclusion being asserted.
evidence_refs Yes Evidence IDs supporting or challenging the claim; use Unknown when none are available.
confidence Yes high, medium, low, or unknown.
uncertainties Yes Remaining gaps, conflicts, or limits that explain the confidence level.
status Yes supported, inferred, hypothesized, assumed, contradicted, or unknown.
assumption_owner Required when status: assumed Person, team, or role responsible for validating or retiring the assumption.
impact_if_wrong Required when status: assumed Scope, safety, design, schedule, or operational consequence if the assumption is false.
validation_method Required when status: assumed Evidence, test, review, decision, or external check that can validate or refute it.

Decision

Field Required Description
decision_id Yes Stable ID within the work record, such as decision-001.
question_or_scope Yes The question, boundary, or choice being resolved.
claim_refs Yes Claims used to make the decision.
options_considered Yes Options and meaningful tradeoffs considered.
selected_option Yes The selected option or disposition.
rationale Yes Why the selected option follows from the claims.
decision_owner Yes Human or role accountable for the decision.
approval Yes not_required, pending, approved, or rejected.
approval_type Required when approval is not not_required scope, design, implementation, or release.

Action

Field Required Description
action_id Yes Stable ID within the work record, such as action-001.
decision_ref Yes Decision ID authorizing the action, or an explicitly recorded approved exception.
action Yes Concrete change, validation, documentation, or follow-up step.
owner Yes Worker, person, or team responsible for the action.
required_gate Yes Gate that must pass before the action may execute.
status Yes proposed, approved, in_progress, completed, blocked, or cancelled.

Rules

  1. Record evidence before using it to support a material claim. Do not present an interpretation as an observation.
  2. Every material claim must reference evidence or explicitly record why the evidence is unavailable. Confidence is an assessment of the claim, not proof of correctness.
  3. Explain high, medium, and low confidence through the evidence and uncertainties. Use unknown when no defensible assessment is possible.
  4. A decision is not the same as approval. A decision may recommend an option; its approval field controls whether an action may proceed.
  5. Every action must reference the decision and gate that authorize it. An action must not execute before its required gate passes.
  6. Preserve IDs when results move between workers, the work record, an implementation plan, and the final handoff.
  7. A material assumption MUST be recorded as a claim with status: assumed. It MUST identify an owner, impact if wrong, and validation method. It MUST transition to supported, contradicted, or unknown when new evidence resolves or limits it.
  8. A decision that materially depends on an assumed claim MUST record that assumption as residual risk and include its validation in the required gate or implementation plan.
  9. An approved decision MUST record its approval type. Source or configuration changes require implementation; deployment, cutover, or another external operational write also requires release.

Example

evidence-001: package X imports package Y.
claim-001: Component X has a runtime dependency on package Y.
  evidence_refs: [evidence-001]
  confidence: high
decision-001: Preserve package Y at the component boundary.
  claim_refs: [claim-001]
  approval: approved
action-001: Add or preserve package Y in the component dependency set.
  decision_ref: decision-001
  required_gate: implementation_approval

claim-002: The destination deployment may use the existing package mirror.
  evidence_refs: [Unknown]
  confidence: low
  status: assumed
  assumption_owner: destination-service owner
  impact_if_wrong: deployment design and rollout plan must change.
  validation_method: verify the destination deployment configuration.