Original tutorialDocs reviewed

Design atomic Jev questions for reviewable routing

A reviewable three-question specification, edge cases and versioned routing suggestions.

Use caseSeparate category, evidence sufficiency and impact for fictional product reports, then combine the answers in code. Includes a specification and edge cases.

Source · JevLog editorialIntermediate15 min

Start reading

Separate category, evidence sufficiency and impact for fictional product reports, then combine the answers in code. Includes a specification and edge cases.

Source · JevLog editorial · Original guide

Source cover · TypeSafe AI

Source cover · TypeSafe AI

Published 2026-10-02 from current official docs with original exercises. No live service calls; source publication dates not established.

Problem

A combined importance and ownership question mixes criteria. Fix the state and independently evaluate category, context and impact. Questions in one Jev call see the same state and cannot consume each other’s answers.

Before you begin

Download question-design.json and label its four fictional inputs first.
The call example needs Python, typesafe-sdk and server-side TYPESAFE_API_KEY. Live execution consumes API quota; designing the specification does not.
Official docs
Official docs

Original JevLog diagram, not a product screenshot or measured result.

Original JevLog diagram, not a product screenshot or measured result.

Steps

1. Fix the state without inserting conclusions

Retain behavior, environment and reproduction conditions. For example: download fails in Firefox, works in Chrome, and still fails after clearing cache. Do not prepend a severity conclusion. Remove identifiers while keeping relevant context.

2. Give each question one job

Use Choice for category, Noul for context sufficiency and Score for impact. Criteria belong in instructions and criteria, with an other fallback. A question ID is an application key, not an instruction.

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score
questions = {
 "queue": Choice(instructions="Which team should review this report?",
   criteria={"engineering": "Software behavior", "content": "Wording or documentation", "other": "Neither or unclear"}),
 "context": Noul(instructions="Does the report describe a concrete failing action and its environment?"),
 "impact": Score(instructions="How much does this block the stated task?",
   criteria=["Task works normally", "A stated workaround works", "No stated workaround works"]),
}
with TypeSafeClient() as client:
 result = client.system_one("Download fails in Firefox but works in Chrome.", questions)
 print(result.choices["queue"].choice)
 print(result.nouls["context"].noul)
 print(result.scores["impact"].score)

3. Combine answers in code

Check fields, queue.confidence and context.noul. Missing evidence, uncertainty or other goes to review. Otherwise emit a suggestion, not a ticket. A cutoff such as 0.8 requires validation and is not an accuracy guarantee.

4. Probe overlapping criteria

The fixture covers clear context, missing context, wording and unrelated input. Label before calling and record case ID, version, expected and actual answers and disagreement. Revise one criterion at a time without moving labels to fit predictions.

5. Version the specification and handoff

Save routing-v1 and original evidence alongside the suggestion. Dependent questions require separate calls and an intermediate state. Application code still checks action allowlists and user permissions.

Practice sample: download question-design.json for local use; not a live run here.

Result and cautions