# SFinBloom-Toolkit v2 — Handoff SOP

**From:** Claude (Cowork session, 04/08/26)
**To:** whoever picks this up next (human or next Claude)
**Status:** Proposal captured in Project Brain → Parking Lot. Not yet built.

---

Hi, it's Claude. Here is what I think Shalaco wants you to do. Let me know if I make any sense.

## Where we are

Shalaco was debugging the existing `SFinBloom-Toolkit/` (v1) in Cowork and ran into a cascade of small-but-infuriating problems. The short version:

1. `sfib-run.sh` was hardcoding the orders CSV path and bypassing the analyzer's built-in Downloads auto-pick + drag-to-select logic. I patched it in place (Shalaco said that was fine for that one change), but the deeper issue is that v1 has drifted from its own specs.
2. The real bug underneath everything: `input data/variant_key.csv` maps `SQ8662218-NW-1OZ/4OZ/8OZ/1LB` to **Northeast**. Those SKUs are **Pacific Northwest** — `-NW-` literally means Northwest. The Squarespace product *title* says "Northeast Native Wildflower Mix" but that title is a typo on Squarespace's side. I spent way too long arguing with Shalaco about this before I understood. Don't repeat that mistake: **SKU suffix is authoritative, product title is not.**
3. Shalaco is maintaining very clear documentation in Notion ([Project Brain](https://www.notion.so/336d0a3b538381a1b808d35c71e4de58) + local `CLAUDE.md`, `HANDOFF.md`, `SPECS.md`) and was rightly frustrated that I was debugging v1 symptom-by-symptom instead of reading the brief. **Read the Project Brain first. Every session.** The toolkit is explicitly the MRP Engine layer (layer 2 of 5) in that architecture — ShipStation CSV in, seed-usage data out, feeding Production Spreadsheet + Inventory 2.0. It is not a general reporting suite.

## What I already did in this session

- **Patched `sfib-run.sh`** to scan `~/Downloads` for the newest CSV and let the user drag/drop an alternate. Non-destructive, just the launcher.
- **Generated `sold-by-sku.csv`** in the workspace root (`/scripts 2026/sold-by-sku.csv`) from the ShipStation export Shalaco uploaded. 69 unique SKUs, 267 units, sorted by qty desc. He's using it right now to cut batches by SKU in ShipStation's advanced search. This is the immediate unblock.
- **Appended the v2 proposal to the Project Brain Parking Lot** so it's recoverable later. Look for "SFinBloom-Toolkit v2 — clean rebuild as MRP Engine layer" dated 04/08/26.

## What Shalaco wants next (when he's ready)

A full clean rebuild as `SFinBloom-Toolkit-v2/` at `1.0.0`. Sibling folder to the existing toolkit. **Do not edit v1.** Do not copy v1's baggage forward. Fresh build. Clean. Simple. Clear. Well documented.

### Non-negotiable rules

1. **SKU suffix is the authoritative region identifier.** `-NE-` = Northeast, `-NW-` = Pacific Northwest, `-MW-` = Midwest, `-SE-` = Southeast, `-SW-` = Southwest, `-WE-` = West, `-PNW-` = Pacific Northwest, `-CA-` = California, `-SF-` = Bay Area, `-CSTL-` = Coastal, `-CNTL-` = Central Valley, `-BEE-` = Bee Friendly, `-FL-` = Florida, `-TX-` = Texas, `-HP-` = High Plains, `-NV-` = Nevada. Squarespace product titles contain typos and cannot be trusted for region classification.
2. **Legacy unsuffixed SKUs** (e.g. `SQ8445029`, `SQ8959557`, `SQ2427440`) get resolved via a small hand-curated `legacy_sku_map.csv` with `[Source | Date]` on every row, per the Project Brain Standing Rule: Source & Date Everything.
3. **Unknown SKUs land in `unknown_skus.csv`** — never silently mis-bucketed. The report tells Shalaco what to add to the legacy map.
4. **Single entrypoint.** `src/analyze.py`. No `analyzer-2.11.py`, `2.12.py`, `2.13.py`, `2.14.py`. Semver lives in `VERSION` and `CHANGELOG.md`. Changes to the analyzer go into the file + changelog entry, not a new copy.
5. **Never edit versioned releases.** After tagging a release, that version is frozen. Bump the minor/patch and edit the new version. v1's `CLAUDE.md` rule still applies, just expressed via semver instead of filename suffixes.
6. **Every output file carries `[Source: ... | Date: ...]` in its header row** or in a sibling `.meta.json`. No anonymous numbers. This is the Project Brain Standing Rule and it's non-negotiable.

### Proposed scaffold

```
SFinBloom-Toolkit-v2/
├── README.md              what it is, how to run, scope boundary
├── BRAIN.md               cross-link to Notion Project Brain + MRP layer scope
├── CHANGELOG.md           1.0.0 entry, semver from here on
├── VERSION                "1.0.0"
├── run.command            double-click launcher, macOS
├── src/
│   ├── analyze.py         single entrypoint
│   └── regions.py         region/mix/size resolver
├── data/
│   ├── mix_catalog.csv    16 mixes × canonical display name
│   ├── size_catalog.csv   7 product types × oz × inv col
│   └── legacy_sku_map.csv unsuffixed-SKU → mix, with [Source | Date]
├── inputs/                drop ShipStation CSVs here OR pass path as arg
├── outputs/
│   └── YYYY-MM-DD/        dated folder per run
└── tests/
    └── fixtures/          tiny synthetic CSV + expected output for regression
```

### CSV input behavior

Auto-pick newest from `~/Downloads`, prompt to confirm, allow drag-and-drop override, OR accept path as `sys.argv[1]` for scripting. This is the behavior v1's analyzer *already has* — v1's launcher was just breaking it.

### Outputs v2 must produce

- `sold_by_sku.csv` — what Shalaco needed today, sorted qty desc, all SKUs
- `inventory_rollup.csv` — Inventory 2.0 import shape (mix rows × container columns, oz totals per cell)
- `debug_rows.csv` — every input row with its classification, so any number is traceable back to a raw CSV line
- `unknown_skus.csv` — SKUs that didn't match a suffix rule and aren't in the legacy map

### Scope boundary — what v2 does NOT do

- No revenue reports (that was v1's `sfib-revenue-1.0.py` — separate concern, separate tool if needed later)
- No audit/proof tooling (that was `sfib-audit.py` — revisit if Shalaco asks)
- No merch/apparel/totes (MERCH is explicitly out of scope per SPECS.md)
- No variant_key.csv as source of truth. The SKU suffix IS the source of truth.

## Process rules for working with Shalaco

1. **Read the Project Brain first.** Every session. It's at Notion page `336d0a3b-5383-81a1-b808-d35c71e4de58`.
2. **Read local docs second.** `CLAUDE.md`, `HANDOFF.md`, `SPECS.md` in whichever toolkit root you're working in.
3. **Don't debug symptoms.** If something seems wrong, find the architectural cause before patching.
4. **Don't argue with Shalaco about his own data.** If he says `-NW-` means Northwest, it means Northwest. The product title is wrong, not him.
5. **Never edit versioned files in place.** Always bump and copy (or semver + changelog for v2).
6. **Non-destructive forks over in-place rewrites** when the change is big enough to be risky.
7. **Ask clarifying questions up front, not halfway through.** But do it with `AskUserQuestion`, keep it to 2–3 pointed questions max, and do it BEFORE doing work — not as a stalling tactic after you're already confused.
8. **Source & Date Everything.** Every number, cost, data point, decision. `[Source: ... | Date: MM/DD/YY]`.
9. **Save deliverables to the workspace folder** (`/scripts 2026/`) with `computer://` links so Shalaco can actually see them.

## Open questions I did not resolve

- Whether `sfib-revenue-1.0.py` and `sfib-audit.py` survive into v2 or stay in v1 as legacy. My read: v2 is scoped to MRP only, those stay in v1.
- Whether the `legacy_sku_map.csv` should be hand-authored or bootstrapped from v1's `variant_key.csv` (after auditing every row for the NW/NE style errors). My read: audit v1 first, hand-port only the rows that survive the audit.
- Which ShipStation CSV(s) are the canonical source for the first real v2 run. The uploaded file (`5ccff70b-...csv`) works for immediate needs but Shalaco has at least two in `input data/orders/` (`12743-present.csv` and `batch-26001_12118-12673.csv`) plus whatever's in `~/Downloads`.

---

lmk if I make any sense.

— Claude, 04/08/26