Outcomes and Claims

Outcomes and Claims are the verification spine of a Playbook. The Outcome says what the Run is meant to achieve. Its Claims say what must be true before Doku can treat that result as verified.

Write Outcomes for the user

An Outcome is a user-facing result, not a workflow step.

Prefer: “A launch decision is ready.”

Avoid: “Review the launch files.”

The first names the durable result. The second is only one activity that might contribute to it.

Every Outcome requires at least one Claim:

const recommendationIsDefensible = claim("recommendationIsDefensible", {
  statement: "The recommendation follows from the recorded risks and constraints.",
  evidence: "Map each recommendation to its supporting observation and constraint.",
});

const decisionReady = outcome("decisionReady", {
  title: "A defensible decision is ready",
  description: "The owner can act on a recommendation with traceable supporting evidence.",
  claims: [recommendationIsDefensible],
});

Make Claims testable

A Claim contains two separate ideas:

• statement: the condition that should be true;
• evidence: what an agent must submit so that condition can be evaluated.

Avoid vague evidence such as “Confirm it works.” Name the artifact, observation, result, URL, command output, or decision record that a reviewer would need.

Use human approval deliberately

Agent approval is appropriate when the evidence can be evaluated through the governed runtime. Use .approval("human") when completion requires accountable judgment: accepting a launch, approving externally visible copy, choosing a tradeoff, or acknowledging residual risk.

const ownerAccepted = claim("ownerAccepted", {
  statement: "The owner accepts the final recommendation and residual risks.",
  evidence: "Record the exact recommendation, residual risks, and the owner's decision.",
}).approval("human");

A human-approved Claim is not a decorative sign-off. It is part of the completion contract and remains attached to the Run's evidence history.

Required and optional Claims

Claims are required by default. Use .optional() only when the Claim improves trust without defining whether the Outcome succeeded.

const performanceBaseline = claim("performanceBaseline", {
  statement: "A performance baseline is available for later comparison.",
  evidence: "Attach the measurement method, environment, and baseline values.",
}).optional();

If a Claim is necessary to call the Outcome complete, keep it required.