239 lines
14 KiB
Markdown
239 lines
14 KiB
Markdown
# 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
|
|
|
|
1. **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.
|
|
|
|
2. **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.
|
|
|
|
3. **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.
|
|
|
|
4. **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.
|
|
|
|
5. **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.
|
|
|
|
6. **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.
|
|
|
|
7. **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.
|
|
|
|
8. **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.
|
|
|
|
9. **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.
|
|
|
|
10. **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.
|
|
|
|
11. **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.
|
|
|
|
12. **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.*
|