Artifact Schemas¶

This page defines the canonical schemas for CDS artifacts. These schemas are stable across CDS Core and can be extended by profiles (e.g., Software Delivery Profile) without changing the underlying structure.

Each field includes:

Purpose (why it exists)
Guidance (how to write it well)
Common smells (early warning signals)

Meaning Handshake schema¶

Situation¶

Purpose: Anchor why the work exists now.
Guidance: One short paragraph or 3–5 bullets: trigger, urgency, why now.
Smells: “Because leadership said so” with no observable trigger; pure solution framing.

Conditions¶

Purpose: Capture reality that shapes what is possible and what matters.
Guidance: List the few conditions that must be true for the framing to hold (constraints, context, climate).
Smells: Too generic; missing constraints; stated as opinions rather than observable conditions.

Needs¶

Purpose: Define what must become true for the situation to improve.
Guidance: Write needs as “must be true” statements; include tensions where relevant.
Smells: Needs written as features/solutions; vague “improve/optimize” language.

Frictions / Problems¶

Purpose: Explain what prevents needs from being met today.
Guidance: Describe causal blockers (bottlenecks, decision gaps, rework loops, unclear ownership).
Smells: A feature backlog disguised as problems; blaming individuals instead of describing system friction.

Stakeholders & Stakes¶

Purpose: Make meaning multi-perspective and politically real.
Guidance: Identify performers/beneficiaries/payers/blockers/operators and what each risks or protects.
Smells: “Stakeholders = everyone”; missing acceptance owner; stakes assumed aligned.

Evidence & Signals¶

Purpose: Ground meaning in signals instead of narrative.
Guidance: Include at least one qualitative and/or quantitative signal that supports the framing.
Smells: No evidence; only anecdotes; metrics without interpretation context.

Assumptions & Unknowns¶

Purpose: Preserve uncertainty explicitly so later stages stay inspectable.
Guidance: Separate “assumptions we believe” from “unknowns we must learn”; include disputes.
Smells: Assumptions presented as facts; unknowns hidden inside confident statements.

Intent Package schema¶

Outcome statement¶

Purpose: Define the intended change in the world (not the solution).
Guidance: Express as a change for a specific group; avoid implementation verbs on first pass.
Smells: Outcome is a project (“build X”, “migrate Y”); outcome is too broad to disagree with.

Success signals & evidence¶

Purpose: Define how success will be recognized and validated.
Guidance: Provide leading and/or lagging signals; state how evidence will be collected/reviewed.
Smells: “Success = delivered”; signals are undefined or unobservable.

Scope boundaries (in / out / unknown)¶

Purpose: Prevent silent scope creep and misalignment.
Guidance: Explicitly name what is included, excluded, and not yet known.
Smells: Everything is “in”; unknowns buried; boundaries depend on implied understanding.

Constraints (non-negotiables)¶

Purpose: Define what must not be violated.
Guidance: Separate true non-negotiables from preferences; name constraint owner where relevant.
Smells: Constraints deferred (“later”); contradictions; no ownership for enforcement/validation.

Tradeoffs accepted¶

Purpose: Make sacrifices visible and owned.
Guidance: State what is being optimized and what is being sacrificed; name who accepts it.
Smells: “No tradeoffs”; tradeoffs discovered only when conflict erupts.

Assumptions & Unknowns (decision impact)¶

Purpose: Identify what could invalidate intent or reshape scope.
Guidance: Prioritize assumptions by impact; note disconfirmation paths where possible.
Smells: Assumptions unprioritized; high-risk unknowns ignored.

Learning plan (if uncertainty is material)¶

Purpose: Turn uncertainty into timeboxed learning that unlocks decisions.
Guidance: Define smallest learning actions + what decision they enable.
Smells: Learning treated as optional; no timebox; no decision linkage.

Decision rights¶

Purpose: Prevent decision vacuum during inevitable tradeoffs and change.
Guidance: Define who decides scope changes, constraint exceptions (if any), tradeoffs, acceptance evidence.
Smells: “We’ll align later”; committee-by-default; unclear veto paths.

Revisit triggers¶

Purpose: Define when intent must be revisited instead of silently drifting.
Guidance: Tie triggers to signals/events/constraint shifts; define what happens on trigger.
Smells: No triggers; triggers are unrealistic; triggers exist but no action is defined.

Commitment Envelope schema¶

Parties, roles, and accountability¶

Purpose: Define who is committing and who is accountable for what.
Guidance: Name accountable owners; distinguish contributors from deciders.
Smells: “Everyone accountable”; accountability split without decision rights.

Commitment statement¶

Purpose: Freeze intent into a short binding statement.
Guidance: Outcome + boundary + horizon/checkpoints + quality bar.
Smells: Too long; ambiguous; depends on implied knowledge.

Deliverables¶

Purpose: Define what will be produced.
Guidance: Keep to key deliverables; avoid turning this into a full plan.
Smells: Deliverables explode into backlog; deliverables replace outcomes.

Evidence & acceptance¶

Purpose: Define how value is evaluated and who accepts it.
Guidance: Separate “delivered” from “valuable”; define acceptance owner and evidence cadence.
Smells: Acceptance = demo; acceptance owner missing; value evidence undefined.

Constraints & non-negotiables¶

Purpose: Carry forward constraints as commitment rails.
Guidance: Include validation ownership and evidence expectations where relevant.
Smells: Constraints acknowledged but not enforceable; validation is undefined.

Tradeoffs accepted¶

Purpose: Preserve the intentional sacrifices behind the commitment.
Guidance: Restate the key tradeoffs and owners; keep short.
Smells: Tradeoffs disappear at commitment time; later disputes repeat old decisions.

Governance cadence¶

Purpose: Provide a stable forum to review progress, risks, and decisions.
Guidance: Define cadence, attendees, minimum agenda, and decision recording.
Smells: Meetings without decisions; attendance unclear; no record of decisions.

Change protocol¶

Purpose: Ensure changes are routable without escalation-by-default.
Guidance: Define what counts as change, proposal path, approval path, urgent path, recording.
Smells: Change = chaos; approvals unclear; urgent path abused.

Risk posture & escalation¶

Purpose: Make risk explicit and manageable.
Guidance: Name top risks, early signals, mitigation stance, escalation path.
Smells: Risks listed as generic boilerplate; escalation path is “raise to leadership”.

Revisit triggers & expiry¶

Purpose: Define when the commitment must be re-confirmed or re-formed.
Guidance: Tie triggers to meaningful events/signals; define renewal points if relevant.
Smells: Frozen commitment in moving reality; no renewal point for long engagements.

Profile extension rules¶

Profiles extend schemas without breaking them.

CDS Core fields remain stable.
Profile fields should be:
additive (not renaming core fields)
minimal (only what the runtime requires)
traceable (clearly mapped to a runtime need or failure pattern)

Example: the Software Delivery Profile adds fields such as quality attributes, dependency obligations, and operational posture — but keeps the underlying Meaning/Intent/Commitment structure unchanged.

Minimum viable versions (v0)¶

When stakes are low and reversibility is high, you can use compressed versions:

Meaning Handshake v0: situation, top conditions, top needs, top frictions, key stakeholders, unknowns
Intent Package v0: outcome, one success signal, boundary, one constraint, one tradeoff, decision right
Commitment Envelope v0: accountable owner, commitment statement, acceptance evidence, change protocol

Use v0 intentionally. If a v0 artifact starts growing, switch to the full schema.