SESSION-0005.0 — Shopify BDD analysis: final domains + library complete

Date: 2026-05-31 Driver: Ben Stull + Claude (Sonnet 4.6) Repos touched: wiggleverse-ecomm-meta (session record), Shopify Analysis workspace (~/projects/wiggleverse/ecomm/Claude/Shopify Analysis/ — not a git repo; flat file workspace)

Honesty note on this artifact. This is a session record authored by the assistant from the conversation — faithful and uncurated as to decisions, sequence, and wrong turns, but not the raw byte-for-byte transcript. OHM publishes raw transcripts via ohm-infra's publish-transcript.sh; ecomm has no such tooling yet. Building a transcript-dump path is a future roadmap item. Until then, records like this stand in — labeled as what they are.

Purpose

Complete the Shopify BDD scenario library. Session 4 left four domains in the queue (analytics/, finance/, markets/, sales-channels/) and marked apps/ as lower-priority / deferred. This session targeted those four, then Ben extended scope to include apps/ — bringing the entire library to completion in a single session.

What happened, in order

Session opened; memory loaded. Ben said "Continue the Shopify BDD work." Memory was read (project-shopify-bdd.md) — confirmed 4 remaining domains, locked style rules, and running totals (44 files, ~960 scenarios at session open). No realignment needed.
Task list created. Five tasks scaffolded upfront: one per domain plus an update task for memory and the domain map. apps/ was not yet on the list — it was still marked deferred in memory.
analytics/ — 3 files written. dashboard.md (overview metrics — today's KPIs, period comparison, date-range switching, sales by channel, top products, returning vs. new customer split, widget drill-through, zero- state for new store; sessions and traffic — time-series chart, source breakdown, top landing pages, engagement metric, device-type filter), reports.md (sales — over time, by product, by traffic referrer, by billing location, by discount code, export, date-range change, channel filter; customers — over time, returning, first-time vs. returning split, by location, predicted spend tier; inventory — snapshot, sell-through rate, ABC analysis, days remaining; behaviour/conversion — online store conversion funnel, drop-off identification, top referrers, sessions by device type, sessions by landing page), live-view.md (real-time monitoring — current visitor count, geographic map, top active pages, recent completed orders, add-to-cart events, source filter, flash-sale monitoring, zero-activity state; activity feed detail — event-type distinction, add-to-cart frequency read, order value visibility). ~65 scenarios. Memory updated.
finance/ — 3 files written. balance.md (account overview — current balance, pending vs. available distinction, transaction history, date-range filter, payout deposit identification, transaction detail, CSV export; card and rewards — card details, fund transfer to card, cashback view, cashback redemption), payouts.md (schedule and history — next payout amount/date, history list, payout detail breakdown, processing fees identification, bank account on file, bank account change, instant payout, schedule frequency view and change; holds and reserve — hold with reason, reserve amount, failed payout notification), bills.md (bill history — current cycle charges, history list, invoice detail, plan subscription line item, app charges, transaction fees, download/print invoice; payment method — card on file, card update, billing failure notice; credits and adjustments — credit line item, pro-rated upgrade charge). ~65 scenarios. Memory updated.
markets/ — 3 files written. international-markets.md (creating and configuring — view all markets, single-country market, multi-country grouping, activate, deactivate without deleting, delete, unassigned countries, set primary market; per-market settings — currency, customer access toggle, dedicated domain/subdomain, language assignment, shipping rates, product availability restriction), localized-pricing.md (currency and exchange rates — automatic rate, manual/fixed rate, percentage-based price adjustment, negative adjustment for discounting, price rounding, pricing preview, variant-level fixed override, removing an override; duties and import fees — enable duty collection, duty-inclusive pricing, DDP shipping terms, duty collection disabled), market-domains.md (domain and subdomain assignment — assign existing domain, assign subdomain, assign subfolder path, view domain per market, remove domain assignment, conflict warning; geolocation and redirection — automatic country-based redirect, selector banner vs. auto-redirect, customer override preference, wrong-market browsing behaviour). ~70 scenarios. Memory updated.
sales-channels/ — 5 files written. online-store.md (channel management — confirm active, product availability toggle, password protection on/off, storefront preview, channel performance metrics; customization entrypoints — themes, navigation, preferences navigation shortcuts), pos.md (setup — add channel, view locations, activate at location, staff access, hardware setup, receipt configuration; selling and checkout — add by search/scan, apply discount, split payment methods, card reader payment, refund, offline cash sale, orders in admin view; inventory and cash management — inventory deduction on sale, cash drawer open/close session, shift cash flow summary), shop-app.md (channel overview — enable, eligibility requirements, store profile customization, product availability, performance metrics; Shop Pay and post-purchase — accelerated checkout, order tracking, post-purchase offers, follower count, Shop campaign to followers), social.md (Facebook & Instagram — connect Business account, catalog sync, Facebook Shop setup, Instagram Shopping tags, sync status and errors, channel orders, Meta Pixel configuration; Google & YouTube — connect Merchant Center, product sync, Smart Shopping campaigns, free listings, resolve disapproval; TikTok — connect for Business, catalog sync, ad campaign), headless.md (Hydrogen — create storefront, view connected storefronts, Storefront API credentials, deploy via Oxygen, rollback deployment, performance metrics, custom domain, delete storefront; Storefront API — product catalog retrieval, cart management, checkout redirect, customer account data, metafield exposure). ~85 scenarios. Memory updated.
Memory and domain map updated — four-domain run complete. Running total at this point: 12 domains, 61 files, ~1,215 scenarios. Domain map (shopify-domain-map.md) updated with Status column for all rows.
Ben extended scope to apps/. After completing the four queued domains, Ben said "Go ahead and tackle that, too." apps/ had been flagged in memory as deferred/lower-priority. Two new tasks created on the spot.
apps/ — 4 files written. app-store.md (discovery — browse App Store, keyword search, category filter, app detail page, pricing preview, reviews, Shopify-built indicator; installation — free app install, permissions review and accept, decline and abort, paid app plan selection, free trial install, external-account setup redirect), installed-apps.md (list management — view all installed, open embedded app, billing status identification, last- used date, uninstall with confirmation, data retention post-uninstall, reinstall; permission review — view granted scopes, write-access risk understanding, permission upgrade prompt, revoke without uninstalling), custom-apps.md (custom app creation — navigate to section, enable custom app development, create app, configure Admin API scopes, generate access token, regenerate token, view API key and secret, delete custom app; collaborator access — approve collaborator request, grant section-level access, remove collaborator, seat-limit non-consumption, view all collaborators), webhooks.md (subscription management — view all, create, test, available topics, orders/create, products/update, update endpoint, delete, delivery failure retry, reactivate paused; security — HMAC verification, reject invalid HMAC, shop-domain header for multi-store routing). ~70 scenarios. Memory updated to final state.
Session record requested. Ben issued the record request with the exact filename pre-assigned (SESSION-0005.0-TRANSCRIPT-2026-05-31.md), target path, and format instructions matching SESSION-0001.0 house style.
Sessions folder not mounted; access requested and approved. Same pattern as Session 4 — the sessions directory is not a pre-connected workspace folder. request_cowork_directory called with explicit path; Ben approved it. SESSION-0001.0 and SESSION-0004.0 read for house style before writing.
Session record written (this file). Serial from main agent context; no subagents.

Decisions citable later

apps/ included in the BDD library. Originally deferred as lower-priority; Ben extended scope in-session. The library now covers all 13 domains in shopify-domain-map.md (all rows marked ✅).
Webhook HMAC verification captured as a scenario. The security contract (verify X-Shopify-Hmac-Sha256, reject non-2xx on mismatch, use X-Shopify-Shop-Domain for multi-store routing) is documented in apps/webhooks.md — relevant to any integration layer we build.
Custom app token is one-time visible. The Admin API access token is revealed and copyable exactly once after install; navigating away loses it. Captured in apps/custom-apps.md; our platform must decide whether to adopt the same security posture or offer re-display with re-auth.
Collaborator access does not consume a staff seat. Shopify's carve-out for Partner/collaborator access is documented. Our platform will need a similar concept (agency/developer access without burning a plan-tier seat).
Shopify-built apps are labeled distinctly in the App Store. Trust signal in the discovery flow — our platform's equivalent marketplace should consider the same first-party provenance marker.
POS offline cash sales sync on reconnect; card payments require connectivity. Captured in sales-channels/pos.md. Fundamental constraint for the POS design (Hasan and Connie are both in-person sellers).

Open / carried forward

general.md first-person inconsistency — carried from Sessions 2 and 3, still unresolved. Ben to decide.
No git history on Shopify Analysis workspace — still a flat folder with no version control. If the library is a reference artifact for the build phase, this is worth addressing.
Sessions folder must be re-approved each session — not a pre-connected workspace folder; request_cowork_directory will be needed again.
Shopify BDD library is now complete. The analysis phase is done. Next natural step is to consume the ~1,285 scenarios to drive platform design — either synthesising them into a capability map / requirements doc, or moving directly into the prototype (Wave 1 of the ROADMAP).

Next session

This is the next session of the ecomm project. The Shopify BDD analysis phase
is complete.

READ FIRST:
- Your memory for this project (project-shopify-bdd.md and any other loaded
  memories via MEMORY.md).
- ~/projects/wiggleverse/ecomm/git/wiggleverse-ecomm-meta/ROADMAP.md — confirm
  where we are in the wave plan and what Wave 1 says.
- ~/projects/wiggleverse/ecomm/git/wiggleverse-ecomm-meta/sessions/SESSION-0005.0-TRANSCRIPT-2026-05-31.md
  — especially "Decisions citable later" and "Open / carried forward."
- ~/projects/wiggleverse/ecomm/Claude/Shopify Analysis/shopify-domain-map.md
  — the full domain list; all 13 domains are now marked ✅.

CONTEXT:
The Shopify BDD library is complete: 13 domains, 65 files, ~1,285 Gherkin
scenarios covering every significant slice of Shopify admin functionality.
It lives at ~/projects/wiggleverse/ecomm/Claude/Shopify Analysis/.

The library was built to answer: "what does Shopify do, so we can decide what
to rebuild?" That question is now answered in scenario form. The next phase
is to act on it.

TASK OPTIONS — Ben to choose or direct at session open:

  A) Synthesis pass — read across the 65 files and produce a platform
     capability map: which Shopify features are must-have for Hasan & Connie
     on day one, which are nice-to-have, and which we intentionally skip or
     do differently (our wedge). Output: a CAPABILITY-MAP.md in
     wiggleverse-ecomm-meta/.

  B) Wave 1 — vibe-code the throwaway prototype in wiggleverse-ecomm-prototype,
     driven by the Hasan & Connie scenarios from the BDD library (POS sale,
     storefront browse + checkout, discount at spend). Per the ROADMAP:
     super wobbly, local-only, fake money, no engineering standards.

  C) Wave 2 — OHM concept RFCs for the core commerce entities surfaced by the
     BDD analysis (Product, Order, Cart, Payment, Merchant, Storefront, Credit).
     These need to land in ohm-rfc/ before binding code can be written.

Ben to decide direction. If unclear, do Option A first — the capability map is
a fast session and sharpens scope for whichever wave comes next.

NOTE: The sessions folder is not pre-connected — call request_cowork_directory
for ~/projects/wiggleverse/ecomm/git/wiggleverse-ecomm-meta/sessions before
writing the next record.

Session 5 closed here.

14 KiB Raw Blame History