Simulation Guide — From Suggestion to Modeled Impact

You think tightening the revenue-leakage threshold from 10 to 5 would catch more findings. Today you’d argue the case from intuition. With Sense 19, you author the change, build a scenario branch with it applied, and read the actual delta against production. Same data, two analytical worlds, one click between them.

This guide walks through that flow end-to-end. By the end you’ll have created a Suggestion, an Intervention, and a scenario branch whose KLS Compare can hold side-by-side against production.

The four nouns

Noun	What it is	Where it lives
Suggestion	A human-readable recommendation. What to do.	afs/suggestions/sug_*.yaml
Intervention	A deterministic, machine-executable edit. How to do it.	afs/interventions/int_*.yaml
Scenario	An AFS git branch with one or more Interventions applied.	scenario/<id> branch
Simulation	A jin make run against a scenario branch. Produces a scenario KLS to compare against production.	<scenario_id>_kls.duckdb in the store

The chain composes left to right. A Suggestion can spawn one or many Interventions. A Scenario applies one or many Interventions. A Simulation is just jin make on the scenario branch — the verb you already know.

A worked example: tighter revenue leakage

Suppose you’re looking at signal_revenue_leakage.yaml and you notice the threshold is set to 10 CHF. You suspect 5 would catch more real leakage without bloating the noise. Let’s prove it.

1. Author the Suggestion

A Suggestion is the prose recommendation. Free-floating expert speech that lives independently of any particular execution.

afs/suggestions/sug_tighten_revenue_leakage.yaml

suggestion_id: sug_tighten_revenue_leakage
version: '1'
category: threshold
target: signal_revenue_leakage
description:
  en: |
    Tighten the revenue-leakage threshold from 10 CHF to 5 CHF.
    Smaller leakages still represent real revenue loss; the OPALE
    feed has enough resolution that the noise floor sits below 5.
priority: high
status: proposed
origin: verdict_billing_workflow_gap
proposer:
  name: mig
  role: analyst
  date: 2026-05-22
interventions:
  - int_lower_revenue_threshold
modified_at: 2026-05-22T08:00:00Z

Validate before you build:

python3 scripts/suggestioncheck.py

A Suggestion is A-tier — it lives on the suggestions orphan branch alongside notes and bookmarks, and is automatically shared across every scenario you create. The “free-floating expert speech” shape is intentional: you might propose the same change in three different contexts; one Suggestion serves all of them.

2. Author the Intervention

The Intervention is the deterministic edit. It names a target file and exactly what to change, including the value it expects to find (from) so the apply step refuses if reality has drifted.

afs/interventions/int_lower_revenue_threshold.yaml

intervention_id: int_lower_revenue_threshold
version: '1'
suggestion_id: sug_tighten_revenue_leakage
type: yaml_edit
target_file: signals/signal_revenue_leakage.yaml
changes:
  - path: thresholds.amount_chf
    from: 10
    to: 5
deterministic: true
reversible: true
description:
  en: Lower the threshold to 5 CHF to catch smaller leakage cases.
author:
  name: mig
  role: analyst
  date: 2026-05-22
modified_at: 2026-05-22T08:00:00Z

Validate:

python3 scripts/interventioncheck.py

The Intervention is B-tier — it lives on whatever git branch you authored it on (main, or a scenario), because different scenarios are defined by different intervention sets. The same Suggestion can spawn an Intervention on main (the “merge this into production” version) and a slightly different Intervention on scenario/x (the “what if we also raised trailing_days” version).

3. Create the scenario branch

This is the moment your idea becomes an addressable analytical world.

jin scenario create tighter_revenue int_lower_revenue_threshold

You’ll see:

scenario: created branch scenario/tighter_revenue
  base:   main@a3b5c7f8
  commit: 4d2e9a1c
  interventions applied:
    - int_lower_revenue_threshold
  files changed:
    - signals/signal_revenue_leakage.yaml

What just happened:

• A git branch scenario/tighter_revenue was created off main.
• The Intervention was applied: signal_revenue_leakage.yaml now has thresholds.amount_chf: 5 on this branch.
• A structured commit was made naming the base and the interventions involved — JinDesk reads this back later.

You’re now checked out on scenario/tighter_revenue. The production main branch is untouched.

You can pass multiple interventions if your scenario stacks several changes:

jin scenario create tighter_or_documentation \
  int_lower_revenue_threshold \
  int_add_documentation_signal

4. Build the scenario KLS

Now the analytical world becomes data.

jin scenario build tighter_revenue

Under the hood this is jin make --branch scenario/tighter_revenue — a temp worktree, a full build against the scenario branch, and a KLS file at:

<live>/<pack>/<tenant>/store/<pack>_<tenant>_scenario_tighter_revenue_kls.duckdb

…coexisting with the production working KLS at <pack>_<tenant>_kls.duckdb. Two analytical worlds, two files.

You can inspect what’s been built:

jin scenario list

Output:

BRANCH                                   CREATED      BUILT  SUBJECT
scenario/tighter_revenue                 2026-05-22   yes    scenario: tighter_revenue
scenario/tighter_or_documentation        2026-05-22   no     scenario: tighter_or_documentation

The BUILT column tells you which scenarios have an actual KLS file you can compare against. An unbuilt scenario exists only as a git branch — its Intervention edits are committed, but the analytical result hasn’t been computed yet.

5. Compare against production

Open JinDesk and go to /{tenant}/compare. The Version A and Version B dropdowns are now split into two groups:

Version A:
  ── Production ──
    Working copy (main) — 553 MB
    post_audit (main) — 549 MB
  ── Scenarios ──
    tighter_revenue (vs main) — 552 MB

Pick tighter_revenue on one side, Working copy on the other. The side-by-side cards render — and on the scenario card, an amber panel shows the interventions applied:

┌──────────────────────────────────┐
│ SCENARIO                         │
│ tighter_revenue (base: main)     │
│                                  │
│ Interventions applied:           │
│   • int_lower_revenue_threshold  │
│                                  │
│ [Compare to production]          │
└──────────────────────────────────┘

The “Compare to production” button is a one-click shortcut for the default scenario diff — it sets the other side to the working KLS automatically.

The delta table below shows what changed: total findings, money-at-risk, confirmed theses, signal coverage. This is the quantitative answer to “would tightening to 5 catch more?“

6. Decide

If you like the result:

• Merge the intervention into main yourself (the scenario branch is a normal git branch — git checkout main, then git cherry-pick or git merge).
• Update the Suggestion’s status from proposed to accepted.
• Next jin make builds production with the change.

If you don’t like the result:

• Leave the scenario branch where it is (git checkout main to return to production).
• Update the Suggestion’s status to rejected with a note in description explaining why.
• The scenario branch and its KLS stay as record — a future audit can see what was tried.

If you want to iterate:

• Edit the Intervention’s changes (change to: 5 to to: 7, say), commit, run jin scenario build again. The same scenario branch, new build, new KLS, new delta.

Common patterns

Stacking interventions. A scenario can apply many Interventions in declared order. Each Intervention’s from value sees the post-previous state, so you can chain from: 10 → to: 7 then from: 7 → to: 3 cleanly.

Drift refusal. If someone changed the file’s actual value to 12 between when you authored the Intervention and when you create the scenario, jin scenario create refuses with a drift error. The intervention was authored against a different baseline; you need to either bump the from to the new actual or fix what drifted.

Retro scenarios. A scenario doesn’t have to fork from main — pass --base release/v1 and your scenario forks from there. Useful for “what would last quarter’s data have looked like with today’s thresholds?”

Listing what’s available. jin scenario list shows every scenario branch with its build status. The output is a useful artifact in itself when triaging — “we have 4 scenarios in flight; 2 are built, 2 are not.”

What this guide intentionally doesn’t cover

• Applying an accepted Suggestion to main — that’s a normal git workflow today (cherry-pick or merge). A future verb may automate it, but the substrate doesn’t need it.
• Deleting scenarios — also a normal git workflow today (git branch -D scenario/<id> + remove the KLS file). A jin scenario delete verb is the natural next addition.
• The “What if?” inline UX on a Verdict detail page — Phase 5, not yet shipped. The substrate is ready when the appetite arrives.

See also

• The Simulation — architecture — the structural framing for engineers and pack authors.
• Suggestion YAML reference — field spec.
• Intervention YAML reference — field spec.
• Sense 19 canonical doc: docs/design/sense_19_the_simulation.md in the engine repo.