Tutorial: Exploring with evolve

In this tutorial you will use jin evolve — jinflow’s AI colleague — to investigate the findings in a tenant, ask follow-up questions in plain English, and let the AI draft a thesis you then commit to your AFS. The point is pair investigation: you bring the question, evolve brings the SQL.

Time: 15 minutes Prerequisites: Tutorial: Your First Build completed. An Anthropic API key configured via jin us --api-key sk-ant-... (see the AI guide for setup).

1. What evolve is

jin evolve is a conversational REPL with full read access to one tenant’s Knowledge Store. It can run SQL, inspect signals, read your AFS YAML, and walk back the lineage from a finding to its source rows. It does not mutate the KLS or push commits — every change you accept is written to your AFS as plain YAML, the same way you’d write it by hand.

Two design rules anchor the feature:

• Single-tenant scope. evolve is opened against exactly one tenant and cannot peek into others — even if the KLS holds more than one.
• Deterministic outputs. Anything evolve produces (a signal YAML, a thesis YAML, a SQL snippet) goes through the normal jin make pipeline. The deterministic build is the contract; evolve is one of many ways to author into it.

2. Open a session

jin evolve --tenant numetrix.inspire

You land in a REPL prompt. The first message you’ll see is a short orientation — which tenant, which pack, which Knowledge Store snapshot. From here you can type plain-English questions and follow-ups.

3. Ask the first question

A reasonable opener:

You: What are the three signals with the most findings right now, and what do they detect?

evolve will run a signal_registry query, summarise the answer in prose, and show the underlying SQL it ran (so you can read it, copy it, or correct it). On the Inspire tenant the answer is something like:

The three signals with the most findings are signal_negative_margin (402,830 findings), signal_billing_below_internal_price (393,196), and signal_controlled_substance_traceability (36,382). The first two are about pricing — billed-out prices below the internal acquisition price. The third is about controlled substances missing traceability metadata.

Notice what just happened: you didn’t have to know the schema, the table names, or the registry’s column conventions. evolve translated your question into a query and gave you the answer in your domain’s vocabulary.

4. Follow up

Try a follow-up that goes one step deeper:

You: For signal_negative_margin, what does a single high-severity finding look like? Show me the worst one by money_at_risk.

evolve will fetch a row from signal_findings__signal_negative_margin, pretty-print the evidence JSON, and explain the meaning of each field in context. This is where the AI colleague shines — it’s not just running SQL, it’s reading your registry + glossary + Gold contract together to translate the row into a sentence you can act on.

5. Ask evolve to draft a thesis

Now turn the investigation into something durable:

You: This looks like a real pattern. Help me draft a thesis that aggregates signal_negative_margin, signal_billing_below_internal_price, and signal_overpriced_generics as evidence. Call it thesis_pricing_health. Tri-lingual interpretations are fine to be short.

evolve will produce a complete thesis_pricing_health.yaml proposal — statement, evidence chain with weights, verdict thresholds, four interpretation blocks in en/de/fr. You read it, push back where needed (“weight the negative_margin probe higher; it’s the strongest signal”), and iterate.

When you’re happy, ask evolve to save it:

You: Looks good. Write this to my AFS.

evolve writes the file to afs/theses/thesis_pricing_health.yaml and tells you the next step.

6. Build and see the verdict

Exit the REPL (/exit) and run the build:

jin make numetrix.inspire

thesischeck validates the new YAML, thesiscompile generates SQL, and the build produces a verdict row in thesis_verdicts. Open JinDesk:

jin explore --tenant numetrix.inspire

Navigate to Theses → click thesis_pricing_health. The verdict is computed against the same signals evolve referenced in your conversation — the loop from question to answer to durable artefact is now closed.

7. The pattern

Every evolve session has the same shape:

You ask, evolve answers and shows its work, you steer, and the result is a YAML commit in your AFS. The AI is the colleague; the AFS is the record.

Notes on cost and scope

• A typical investigation session costs ~$0.10–0.50 in API usage (Claude Opus or Sonnet, configurable via jin us --model).
• The AI sees only what it queries — no telemetry leaves your machine besides the prompts and the rows it asks for.
• The jin evolve --tenant flag is mandatory. You cannot open evolve across tenants. This is a design invariant, not a UX gate.

What you learned

• evolve is a single-tenant REPL that pairs natural language with deterministic SQL
• Every answer ships with the SQL it ran — you can read, copy, or correct
• The AI can draft new YAML (signals, theses, Subject Matter entries) and write it directly into your AFS
• Once written, the artefact is built like any hand-authored one — jin make is the contract
• The privacy boundary is structural: scoped to one tenant, no cross-schema queries

Next steps

• AI Integration Guide — every setting, every model option
• Tutorial: From Finding to Verdict — the same path, by hand
• Tutorial: Capturing Expert Knowledge — what to do with the why evolve helps you uncover
• Glossary — every term explained