achieves

achieves

Declare the machine’s goal and success criteria. The achieves section defines what the machine is trying to accomplish, what success looks like, what it must never do, and provides concrete input/output examples. This is the machine’s specification: a human-readable contract that drives both testing and evaluation.

When to use

Every machine should have an achieves section. It serves three purposes:

1. Documentation: tells humans (and Koda) what the machine does
2. Implicit tests: for example blocks are executable test cases
3. Evaluation: succeeds when criteria are checked by mashin run --to evaluate

Omit it only for trivial utility machines where the purpose is self-evident from the name and contract.

Syntax

achieves
  goal "<description>"
    succeeds when "<success_criterion>"
    never "<constraint>"
    for example
      given { <input_field>: <value>, ... }
      expect { <output_field>: <value>, ... }

Components

Component	Required	Description
goal "<description>"	Yes	What the machine achieves. One sentence, specific and measurable.
succeeds when "<criterion>"	Recommended	Quantifiable success condition. Used by the evaluate interpretation mode.
never "<constraint>"	Recommended	Hard constraints the machine must not violate. Compiled into guardrail checks.
for example	Recommended	Concrete input/output pairs. Each for example block is an implicit test case.

for example blocks

Each example provides a given (inputs) and expect (expected outputs):

for example
  given {message: "My payment failed"}
  expect {team: "billing", confidence: 0.95}

These examples are:

• Executable as tests during mashin test
• Shown in Koda when inspecting the machine
• Used by mashin run --to evaluate to check metrics
• Displayed in the visual builder as documentation

Examples

Simple goal with examples

achieves
  goal "Classify support tickets by department"
    succeeds when "correct department >90% of the time"
    never "expose customer PII in routing metadata"
    for example
      given {message: "My payment failed"}
      expect {team: "billing"}
    for example
      given {message: "I can't log in to my account"}
      expect {team: "technical"}

Research assistant goal

achieves
  goal "Answer research questions with cited sources"
    succeeds when "answer != null and sources_count > 0"
    never "fabricate sources or citations"
    for example
      given {question: "What is Rice's theorem?"}
      expect {answer: "Rice's theorem states...", sources_count: 2}

Data pipeline goal

achieves
  goal "Clean messy data by handling missing values and reshaping for analysis"
    succeeds when "completeness >= 90% after cleaning"

Multi-constraint goal

achieves
  goal "Route incoming emails to the correct team and draft responses"
    succeeds when "routing accuracy > 95% and response quality rating > 4.0/5.0"
    never "send a response without human approval for VIP customers"
    never "include internal notes or ticket IDs in customer-facing responses"
    for example
      given {subject: "Billing question", body: "Why was I charged twice?", is_vip: false}
      expect {team: "billing", priority: "high", needs_response: true}
    for example
      given {subject: "Thanks!", body: "Just wanted to say thanks for the quick resolution", is_vip: false}
      expect {team: "general", priority: "low", needs_response: false}

Relationship to verifies

achieves > for example blocks and verifies > test blocks serve related but distinct purposes:

	for example (in achieves)	test (in verifies)
Purpose	Specification by example	Explicit test cases
Focus	What success looks like	Edge cases, error paths, integration
Visibility	Shown in documentation and Koda	Used by test runner
Mocking	No assuming support	Full assuming support for mocking steps
Granularity	Input/output only	Can assert on intermediate step values

Both are executed during mashin test. A well-specified machine has for example blocks for the happy path and test blocks for edge cases and failure modes.

Governance

The achieves section directly informs governance:

1. never constraints compile into guardrail checks. The governance interpreter can reference them during step execution.
2. succeeds when criteria are used by mashin run --to evaluate to assess machine performance against declared targets.
3. for example blocks provide the reference data for evaluation metrics in the optimizes section.

The achieves section is a compile-time declaration with runtime implications. It does not directly cost anything to declare, but the governance features it enables (guardrails, evaluation) are active during execution.

Translations

Language	Keyword
English	achieves
Spanish	logra
French	atteint
German	erreicht
Japanese	達成
Chinese	达成
Korean	달성

Sub-keywords

English	Spanish	French	German	Japanese	Chinese	Korean
goal	meta	objectif	Ziel	目標	目标	목표
succeeds when	exito cuando	reussit quand	erfolgreich wenn	成功条件	成功条件	성공 조건
never	nunca	jamais	niemals	禁止事項	禁止	금지
for example	por ejemplo	par exemple	zum Beispiel	例えば	例如	예를 들어

See also

• verifies - Explicit test cases with mocking
• ensures - Governance rules that enforce constraints
• optimizes - Metrics and fitness criteria
• accepts - Input fields referenced in given blocks
• responds with - Output fields referenced in expect blocks