Sense 26: The Workshop — the pack ships its own design

Sense 26 · Steady · Last touched 2026-08-20

• last_verified: 2026-07-27

Synced from docs/design/sense_26_the_workshop.md in the engine repo — that’s the source; this page is a build-time mirror.

A pack is not a product. It is the thinking that produced the analytics, with the analytics as a side effect.

Every pack ships with its own design notes, in the pack itself — browseable, searchable, translated, and updatable like any other note. A clone of the pack is a workshop.

Status: proposed Author: the owner + Claude (conversation, 2026-05-04 — emerged while folding the hrcentral architecture session into the pack notebook)

---

What pulled us in

A jinflow pack is the encoded result of an analytical conversation that took weeks or months. By the time it ships, the conversation is over — the thinking lives in scattered Markdown drafts, in chat logs, in commit messages, in someone’s head. The pack itself is silent about how it got there.

That silence is a loss in three ways:

For the client. They get analytics they don’t fully understand. The signals fire, the verdicts read true, but the why — why this entity model, why these signal thresholds, why this Subject Matter prose — is invisible. They consume the analytics; they don’t learn from them.

For the next pack author. Numerix took three months and a hundred conversations to settle on its shape. hrcentral starts from scratch. The reasoning that worked, the dead ends that didn’t, the surprising turns mid-design — all of that lives in jazzisnow’s collective memory and nowhere else. Each new pack pays the cost of forgetting.

For jazzisnow itself. The reasoning is the moat. Without it visible, the pack looks like SQL + YAML — copyable, replaceable, commodity. With it visible, the pack looks like institutional expertise embodied in queryable form. The same artifacts, but the frame sells differently.

Hiding the design is a posture mistake.

---

The Move

Every pack ships with its own design notes — in the pack itself, as notebook YAMLs. JinDesk renders them. They’re searchable, translatable, linkable, and updatable like any other note.

A pack’s notebook now holds two distinct kinds of content:

1. Tenant-attached operational notes — the existing kind. SME captures, incident retrospectives, hand-curated investigations, workshop output. Each note attaches to a specific tenant (scope.tenant_id).
2. Pack-level design notes — the new kind. Architecture papers, entity models, design rationale, glossary, scrape strategies, protection model, Sense links. Each note is tenant-blind (scope.tenant_id: '*').

A tenant viewing JinDesk sees both. The first answers what happened here; the second answers why is the pack shaped this way.

---

The Three-Step Pattern

1. Author in Markdown. Working drafts live as .md in etc/<pack>/<topic>/ (or packs/<pack>/docs/). Markdown is the working surface — fluent for editing, mergeable in git, linkable.

2. Generate notes from Markdown. A pack-aware generator reads the Markdown and emits notebook YAMLs into the right place:

• packs/<pack>/notebook/nb_<pack>_<topic>.yaml for pack-level docs
• packs/<pack>/tenants/<tenant>/afs/notebook/nb_<tenant>_<topic>.yaml for tenant-level docs

YAML frontmatter at the top of each Markdown declares scope, author, status, tags. Sections (## headers) become cells. Mermaid blocks stay as mermaid (JinDesk’s notebook page already renders them). Quadrilingual content uses parallel files in de/ en/ fr/ it/ subdirectories or a single file with locale-tagged blocks.

3. Update by updating. No drafts, no versions, no clones. If the thinking moves, the Markdown moves; the next jin make regenerates the note. JinDesk always shows the current truth, dated by modified_at. Older states live in git history, not in parallel documents.

Why no drafts? A “draft” mindset normalises permanently-stale documents. If something is worth writing, it’s worth being the truth — and the truth is whatever the latest commit says.

---

What This Changes

For the client. They open VAI in JinDesk. Sidebar shows Notebook → Architecture. They click. They read why hrcentral has BlockPeople as a peer of Person. They click entity_model → Booking spine. They click a Mermaid diagram. They search “scenario” and find Sparky’s operational design. They learn the pack from the inside.

For the next pack author. They clone hrcentral. They see packs/hrcentral/notebook/nb_hrcentral_assessment.yaml and nb_hrcentral_protection_model.yaml and nb_hrcentral_diagrams.yaml. They read how the architectural choices were made, in voice, with diagrams. They start their pack with a template instead of a blank page.

For jazzisnow. Every pack delivery ships with its own demonstration of authorship. The reasoning is right there, signed, dated, version-tracked, translatable. Replicating the SQL is easy; replicating the thinking is what’s hard, and the thinking is now the deliverable.

---

What it Means for Pack Design

A pack with a notebook/ of pack-level design notes becomes a self-explaining object. Three implications:

Pack-blindness preserved. Pack-level notes are tenant-blind by construction (scope.tenant_id: '*'). They describe the pack itself — its entity model, its design rationale, its analytical posture — and never name a specific tenant. Sister’s pack-blindness work (Sense 20 / pack scope) holds.

Tenant notebook stays tenant-specific. VAI’s notebook holds VAI-specific things: the synthetic org chart, the cast of fictional persons, the injected anomalies, the workshop tour. Pack-level design lives in the pack; tenant-specific colour lives in the tenant. Two layers, both readable.

Sense docs become pack docs. A pack can include the relevant Sense (or a pack-specific specialisation) as a note. Sense 14 (the Signal) lives in jinflow’s docs/design; a pack-specific note about how that pack uses signals can live in the pack’s notebook. Same shape, different scope.

---

The Generator

The Markdown-to-note generator is a small, per-pack-aware engine script. Reads frontmatter for routing, splits by ## for cells, preserves Mermaid + code blocks, emits notebook YAMLs validated by notecheck.py. Idempotent.

Hooked into jin make (after the existing notebook compile step): edits to the Markdown propagate to the note on the next make. Notebook YAMLs are not hand-edited — they’re build artifacts.

This is the same shape as signalcompile.py, thesiscompile.py, etc. — declarative source (Markdown) compiled to dbt-loadable artifact (notebook YAML). Consistent with the rest of the pack build pipeline.

---

Risks and Edges

Drift between Markdown and generated note. Avoided by single-source: Markdown is the truth, notes are generated. Notes in git are convenience for review; the regeneration is deterministic.

Notebook bloat. A 932-line operational design becomes one note with many cells. Some readers want a TOC; some want one long scroll. JinDesk’s notebook page already handles long notes; cell-level anchoring + collapsible sections is a v2 ask.

Translation lag. Quadrilingual is the principle, but architectural docs typically start in EN. The validator already accepts EN-only with DE/FR/IT slots empty (with a warning). Translations land over time; they don’t gate publishing.

Pack-level vs tenant-level confusion. Pack-level notes describe the pack; tenant-level describe the tenant. Misclassification is mostly cosmetic, but pack-level mentioning a tenant by name violates pack-blindness. The frontmatter scope directive makes this explicit and reviewable.

---

What it Asks of the Engine

Modest:

• A new Markdown-to-note generator (~200-300 LOC, modelled on notecompile.py).
• A docs/ subdirectory convention in pack stores (alongside signals/, theses/, etc.).
• Tooling support in JinDesk to render mermaid in narrative cells (already shipped 2026-05-03).
• Eventually: cross-note references (reference cells with kind: note) so design notes can link to one another and to signals/theses they motivate.

Nothing that changes the core data model. Just one more compile step in the pack build, and a stronger habit of writing the thinking down where it can be found.

---

Closing

A pack is not just analytics. A pack is a workshop. Every clone is an invitation to learn how the analytics were made.

The architecture is generous to whoever comes next. That’s the point.

---

How this manifests in jinflow

The Workshop is the principle that a pack ships its own design — docs, decision papers, contracts, Subject Matter catalogues travel inside the pack itself. When a new tenant runs jin init --pack numetrix, numetrix’s full thinking inheritance comes with the kit: contracts, the Wisdom catalogue, the field manual, the dbt macros, the source-system adapters. Every pack carries its own design and ships it together with its analytics.

• What’s carried: per-pack contracts/, docs/, field_manual/, smebits/, bitbundles/, dbt models, source-system adapters
• CLI: jin init --pack <name> (copies the workshop into the new tenant’s AFS) · jin afs update (syncs forward when the pack’s design evolves)

Status: shipped. Every active pack (nuMetrix, hrcentral, Millésime) ships its workshop today.

---

Numerical neighbors: ← Sense 25: The Pass — what you can do here, today, in this scope · Sense 27 — Lever 2 — Decoupling shell from panels →