Build the deterministic investigator

This is the first thing we build

The deterministic investigator is intentionally modest. It receives an incident, reads scenario evidence, applies a small set of rules, and produces a report that explains its route.

It does not use a model. That makes this the most important checkpoint in the course: every capability we add later has to preserve this clarity.

The core loop

def investigate(scenario, hypothesis_outcomes=None):
    findings = collect_findings(scenario)
    hypotheses = collect_hypotheses(scenario, hypothesis_outcomes)
    route, reason, next_step = choose_route(scenario)
    events = collect_workflow_events(scenario)
    return InvestigationReport(findings, hypotheses, route, reason, next_step, events)

Each function owns one job:

• collect_findings reads facts and their sources.
• collect_hypotheses keeps explanations separate from facts.
• choose_route applies explicit rules.
• collect_workflow_events records retries and duplicate delivery; the investigator records transitions.
• InvestigationReport explains the result without changing it.

That is a harness without a model. We are learning the shape before putting a probabilistic component inside it.

What success looks like

At the end of this checkpoint, you can take a synthetic incident and answer:

• What did the system observe?
• Which rule selected the route?
• What state is the incident in?
• What will happen next?
• What would cause the system to ask a human instead?

If you can answer those questions, you have built something useful.

Try it

The Workbench is a small local Python project. Set it up from the companion repository, then run:

workbench
python -m streamlit run app.py

Choose Checkout regression in the browser view. Its observed error rate is 8.2%. In the sidebar, raise High checkout error rate from 5% to 9%. The selected route should move from possible-deployment-regression to normal-observation; set it back to 5% and the original route returns. You changed one explicit input and saw one explainable consequence. No source edit and no model are needed.

Then run pytest to see the rules the project protects.

At this point, try each scenario once: Checkout regression, Delayed metric, and Duplicate alert. The application changes shape only where the input and the explicit workflow say it should.

Optional: use OpenCode as a reading companion. OpenCode is an open-source coding agent that can inspect the files on your machine and explain a small change. It is not required for this course or for the Workbench. If you use it, ask: “Show me where the high-error rule is evaluated and explain both routes.” Read the answer against src/workbench/investigator.py; do not accept a proposed change until you can explain its effect on the route.

Keep this with you

The point is not to write a lot of Python. The point is to make the work legible. That is a skill models cannot do for us.