Skip to main content

The Three Scenarios

The BWS machine does three different things, distinguishable by what is new each time. This page enumerates them as doctrine: layer arrangement, gap worked, definition-of-done.

The mechanism underneath all three is the Process Library three-layer model. If you have not read that page, read it before this. This page assumes it.

At a glance​

Scenario 1Scenario 2Scenario 3
What's newA customerA vertical (reuse-led)A vertical (canon-led, pre-client)
L1 (code)Shared, unchangedHarvest core + repurpose/retire tissueHarvest portable core only
L2 (vertical canon)Shared, unchangedAuthored fresh for the verticalAuthored fresh, before any client
L3 (SME)The only bespoke stepAfter the build queueA small delta on a working product
Gap workedL3 \ L1 (small, surface)L2 \ L1 (the vertical queue)L2 \ L1, pre-client
CostMinutes + an L3 conversationA knower's canon + queue buildA knower's canon + queue build
Client needed?Yes, for L3Not until the queue is builtNo — that's the point

The portable core (per the Substrate Line) is harvested once and reused forever. Each new vertical pays for a new L2 canon and the build-down of its L2 \ L1 gap — and inherits everything commercial retail has in common for free. That inheritance, made addressable in SQL by concept_key, is the machine.

Scenario 1 — Same vertical, new customer​

Goal: stand up a second (third, tenth) bike shop on the existing bike template. This is the cheapest operation the machine performs.

Layer arrangement: L1 and L2 are already correct and shared — they belong to the vertical, not the shop. The only new work is L3: capturing how this shop differs.

Mechanical steps​

Per the Onboarding a new shop runbook:

wrangler d1 create helm-{slug}-db
wrangler r2 bucket create helm-{slug}-assets
wrangler kv:namespace create "helm-{slug}-kv"

git switch -c shops/{slug}
# wrangler.jsonc: add env.{slug} block with the new IDs
# shop-overrides/{slug}/branding.json: colors, logo, copy
git commit -am "Onboard {slug}: bindings + branding"
git push -u origin shops/{slug}   # CI deploys

wrangler d1 migrations apply helm-{slug}-db --remote
wrangler d1 execute helm-{slug}-db --remote --file=seed_permissions.sql

# Then seed L1 (idempotent on code_anchor) and inherit L2:
python scripts/extract_processes.py

Now sit with the owner. Everything they describe that the canon doesn't cover is authored as L3 (layer='sme') in the Library editor. Run the vetter:

python scripts/pull_new_l3.py

It surfaces every L1/L2 row that might be prior art for each new L3, emitting a Markdown report. A human renders the verdict:

  • Redundant — capability exists; mark programmed, no build.
  • Partial — exists but incomplete; scope the delta.
  • Gap — genuinely new; mark needs_code — joins the build queue.

For a same-vertical customer, the L3 \ L1 gap is usually small and almost always surface, not substrate. Most is configuration the owner can do themselves in-situ via the helm-editable chassis; only the true gaps become code.

Definition of done​

  • New instance answers on helm-{slug}.kvick.bike, audit chain verifies clean
  • L1 seeded from the deployed code; L2 canon present
  • Owner's L3 captured, vetted, and triaged (programmed / needs_code)
  • The needs_code list — small, surface-level — is the only bespoke build work

Scenario 2 — New vertical, maximum reuse​

Goal: produce a system for a different industry (a motorcycle shop, an outdoor-gear outfitter) using what the bike vertical already gives us. L2 no longer applies — the bike canon is not the motorcycle canon — and some vertical tissue in L1 is wrong for the new trade.

Layer arrangement: harvest the portable core of L1, repurpose or retire the vertical tissue, author a new L2 canon for the target vertical, read the gaps. All before the client.

Mechanical steps​

  1. Apply the Substrate Line test to every L1 capability. Sort into three buckets:

    • Harvest verbatim — portable core (identity, audit, customers, money, tax, inventory, purchasing). Moves unchanged with its concept_keys intact.
    • Repurpose — vertical tissue whose pattern generalises. The bike service kanban → a generic intake-to-collection job board for the new trade. The bikes-on-record entity → whatever serial-numbered customer asset the new trade tracks (motorcycles, kayaks, instruments), or nothing.
    • Retire — vertical tissue with no analogue. Rentals for a trade that doesn't rent; trade-in for a trade with no used market.

  2. Fork the template, strip the retired tissue, rename the repurposed tissue, re-seed L1:

    python scripts/extract_processes.py   # L1 now reflects the new vertical's code

  3. Author the new vertical's L2 — done by a Knower, not a coder. Mechanically mirrors the bike canon: a hand-maintained playbook feeds a generator analogous to generate_l2_canon.py, plus a links generator analogous to generate_l2_links.py. Each L2 row is flagged:

    • programmed if a harvested L1 row shares its concept_key
    • needs_code if no L1 row matches

  4. Read the gap — the vertical's standing build queue:

    -- L2 \ L1 : every workflow the new vertical expects that the code lacks
    SELECT l2.concept_key, l2.name, l2.review_status
    FROM processes l2
    WHERE l2.layer = 'vertical'
      AND l2.is_active = 1
      AND NOT EXISTS (
        SELECT 1 FROM processes l1
        WHERE l1.layer = 'code'
          AND l1.is_active = 1
          AND l1.concept_key = l2.concept_key
      )
    ORDER BY l2.concept_key;

Because the portable core was harvested with its concept_keys intact, a large share of the new vertical's L2 will light up programmed on day one — every sale, refund, customer, tax, and purchasing workflow the new trade shares with a bike shop. That is the reuse dividend, made visible in SQL.

Definition of done​

  • Portable core harvested verbatim; tissue repurposed / retired per an explicit sort
  • L1 re-seeded from the new vertical's source
  • New L2 canon authored, generated, and link-graphed by a Knower
  • L2 \ L1 computed → the vertical's build queue exists before the first client

Scenario 3 — New vertical, pre-client (canon-led)​

Goal: create a new vertical from L1 + L2 processes before sitting with the client for L3. This is Scenario 2 viewed as a discipline: the explicit commitment that two of the three layers can — and should — be complete before the client speaks.

Why pre-client L1 + L2 is the whole point​

The bike vertical was built in the wrong order, and it had to be: L1 (code) came first, and L2 (canon) was reverse-derived from it. Migration 085 backfilled the hand-seeded rows into layer='vertical' because they had been the bike canon all along; the schema just hadn't known it. A new vertical reverses that order on purpose:

  1. L1 first, by harvest — the portable core, already proven in production at the bike shop, moved across with its concept_keys intact. This is L1 you trust because it already runs.
  2. L2 second, by a Knower — the new vertical's canon, authored from industry knowledge, each row flagged programmed/needs_code against the harvested L1.
  3. L3 last, with the client — and only the client's true idiosyncrasies, because the canon already absorbed everything generic.

The payoff: when you finally sit with the first client in the new vertical, you are not staring at a blank system. You are demonstrating a working product that already does every workflow their industry shares with retail, and you are asking a much smaller question — "what do you do that your industry's canon doesn't?" That is the L3 conversation Scenario 1 runs, but now reachable for an industry the machine has never served.

The pre-client sequence​

1. Harvest the portable core
   - Apply the Substrate Line test to bike L1; take the "portable core" bucket
   - Carry concept_keys across unchanged so L2 can line up against them
   - Strip bike tissue (bikes-on-record, trade-in, rental fleet, bike kanban)

2. Stand up the new vertical's L1
   - Fork → strip → (optionally) repurpose one or two patterns the Knower is sure of
   - python scripts/extract_processes.py   → L1 reflects the harvested core

3. Author the new vertical's L2  (the Knower's work — no client yet)
   - Hand-maintain the vertical playbook
   - generate_l2_canon.py analogue  → L2 canon rows, flagged vs harvested L1
   - generate_l2_links.py analogue  → typed process_links among them

4. Read the gaps (still no client)
   - L2 \ L1  → the vertical build queue (what the industry needs, we lack)
   - L1 \ L2  → harvested capability the canon didn't name (audit it: keep or cut)

5. Build down the L2 \ L1 queue to a credible demo
   - Enough of the canon is `programmed` that the system is showable
   - Remaining needs_code is the honest roadmap you can show the first client

Steps 1–5 happen with zero client input. The vertical exists — as running code (L1) and as a documented theory of the industry (L2) — before the first sales conversation.

Then, and only then, L3​

The first client of the new vertical is onboarded exactly as Scenario 1's L3 step: capture L3 in the Library editor, run pull_new_l3.py, triage each row against the now-rich L1+L2. The difference is that the canon you built catches most of what they describe, so the L3 \ L1 gap is small — and the client experiences a system that already understands their business.

Definition of done​

  • Portable core harvested with concept_keys intact; bike tissue stripped
  • New vertical's L1 standing and extracted
  • New vertical's L2 canon authored by a Knower, generated, link-graphed, flagged against L1 — all before any client
  • L2 \ L1 build queue worked down to a demonstrable system
  • The first L3 conversation is a small delta on a working product, not a spec session against a blank page

See also​