# USA Clean — backlog & upcoming work

The single tracker for everything not yet done. Two parts:

1. **Roadmap & upcoming work** — phase work, deferred decisions, and queued cleanups, hand-maintained. This is the planning surface; the *why* behind each item lives in the linked brief or in [`decisions.md`](decisions.md).
2. **Review notes** — a page-grouped rollup of `review`-labeled GitHub Issues, generated by the `triage-notes` skill from the in-prototype annotation layer (PD-002). The issues are the source of truth; this is the readable rollup.

Companion logs: settled product/UX calls live in [`decisions.md`](decisions.md) (PD-NNN); token & component calls in [`../design-system/decisions.md`](../design-system/decisions.md).

What from the prototype is already live on shop.usaclean.com is recorded in [`live-site-audit.md`](live-site-audit.md), with the evidence. This backlog holds only what is left.

_Last updated: 2026-10-01_

## Status legend

| Icon | Meaning |
|---|---|
| 🔜 | Next up — scoped and ready to pick up |
| 🧭 | Planned — phase/roadmap work, not yet scoped in detail |
| ⏸️ | Data-gated — waiting on a named signal (cross-ref `decisions.md`) |
| 🔌 | Source-ready but not deployed/wired |
| 🧹 | Cleanup / tech debt |
| ⛔ | Blocked — waiting on an external dependency |

Items added from the live-site audit carry word tags with the same meanings, in the same order: [Next], [Planned], [Data-gated], [Source-ready], [Cleanup], [Blocked].

---

## Roadmap & upcoming work

### National Account
- **[Planned] Phase 0 — the account number in the account header.** (live audit [F15](live-site-audit.md#f15))
- 🔜 **Phase 0.5 — native personalized account home.** `v2/account-home.html` is built as a prototype and flagged as the recommended next implementation step. Dividing line: if BigCommerce returns it natively → Phase 0.5; if we must compose/aggregate it → Phase 1. → [account-concepts.md](account-concepts.md), [account-phases.html](account-phases.html)
- **[Planned] Phase 1 — the full dashboard, the composed hub.** → [account-phases.html](account-phases.html) (live audit [F15](live-site-audit.md#f15))
- 🧭 **Phase 2 — account sub-pages + reorder pad.** Scoped, not yet built.
- 🧭 **Phase 3 — enterprise integrations.** Future.

### Search (HawkSearch × Caster)
- **[Next] Stop the search results page jumping as it loads.** In a lab test it measures a layout shift well above the 0.1 guideline. The IA roadmap (#11) lists images without dimensions, late-loading web fonts, and HawkSearch injecting its results after first paint as likely causes. (live audit [section 04](live-site-audit.md#fixes))
- **[Planned] Phase 1 — the rest.** Saved machines and a "Shopping for" pill for signed-in buyers, the hero search as the main homepage interaction, and the Caster look on the HawkSearch results page. (live audit [F03](live-site-audit.md#f03))
- 🧭 **Phase 3 — replace Hawk's Handlebars results UI** with its React/headless SDK on Catalyst. → [search-experience-concepts.md](search-experience-concepts.md)
- 🧹 **Promote queued search patterns to Caster** on their 2nd consumer: `search-autocomplete`, `search-hero`, facet-group accordion, removable `filter-chip`, `facet-drawer`.
- 🔌 **Fix the searchRequest race** in the theme `index.js` (IA roadmap #4/#1, confirmed in the theme-source audit). Two-file fix: edit the `.hbs` template + port `hawksearch-custom-styles`.
- ⛔ **HawkSearch dashboard access.** Blocked — the BC login doesn't yet expose the Hawk panel, so facets / synonyms / autocomplete config can't proceed. Access request outstanding.

### Subscribe & Save (PDP)
- 🧭 **Recurring auto-ship / Subscribe & Save.** PDP CTA mockup is built (`v2/pdp.html` — `.buy-mode` / `.sub-detail`: One-time vs Subscribe toggle, 10% off / `$38.16`, 30/60/90-day + 6-month cadence, expandable terms). **Not shippable on native BC** (no recurring billing) — needs a subscription app or a Catalyst/custom build. Full brief → [subscribe-concepts.md](subscribe-concepts.md). Awaiting client decision on app-vs-custom and the savings-% / cadence policy. Promote `.buy-mode` to Caster on a 2nd consumer (rule #7).
- **[Planned] The Subscribe badge and auto-ship price hint on listing cards.** (live audit [F19](live-site-audit.md#f19))
- 🔌 **Phase 2 Cloudflare Worker** (`tools/ucnote-worker/`). Source-ready, **not deployed**. Holds a fine-grained PAT so non-GitHub clients can file issues directly. Switch on by setting `window.UCNOTES_CONFIG.proxyUrl` / `proxyKey`. (PD-002)

### Model landing pages (PD-008)
_Phase 1 is scoped to **four elements** — model info header, documentation, dispatch-a-tech, related models — per [PD-008](decisions.md). Prototype → [`v2/model-tennant-t500e-phase1.html`](../v2/model-tennant-t500e-phase1.html); the full hub kept as the Phase 2/3 target → [`v2/model-tennant-t500e.html`](../v2/model-tennant-t500e.html). Full brief → [model-landing-concepts.md](model-landing-concepts.md)._
- 🔜 **Phase 1 — top-20 models, four elements.** One custom category template plus ~8 custom fields per model (`hero_image_url`, `machine_class`, `description`, `operator_manual_url`, `service_manual_url`, `parts_catalog_url`, `video_playlist_url`, `related_models`). No `compatible_models[]` tagging required, so it does not wait on the catalog work. Roughly half a day of content per model once the template exists.
- 🔜 **Inventory the top 20 models** by part-search traffic and equipment-sales volume — the input the Phase 1 build needs before any page is created.
- 🔜 **Bulk 301 the old `/parts-and-supplies/{brand}/{model}/` URLs** to `/parts/by-machine/{brand}/{model}/` via the BC redirect manager, and regenerate `sitemap.xml`.
- 🔜 **Instrument the Phase 1 signals from day one** — especially **"Shop parts for this machine" click-through**, the stand-in for the deferred parts grid and the number that decides whether Phase 2 is worth funding. Also: doc-download rate per model, "Dispatch a tech" CTA rate, traffic shift off the old URLs, bounce/session depth.
- ⏸️ **Phase 2 — full hub layout + top-100 automation.** Adds most-bought parts, the compatible-parts grid, the specs card, and the hero stat bar; plus the CSV-import admin tooling. Data-gated on Phase 1 traffic paying off **and** `compatible_models[]` tagging being underway. The deferred sections are already designed and marked `DECISION PD-008` in the full-hub prototype, so this is closer to uncommenting than redesigning.
- ⏸️ **Tag ~12k parts with `compatible_models[]`.** The single largest content-ops task across the whole prototype — a 2–3 month structured effort, probably seeded from OEM cross-reference data. **Shared with three features**: model-landing Phase 2, [search](search-experience-concepts.md) Phase 2, [recently-purchased](recently-purchased-concepts.md) Phase 2, and it also unblocks [PD-004](decisions.md) (the model-fit badge). Sequence it once, fund it once.
- 🧭 **Phase 3 — interactive parts diagrams + fleet-aware parts ordering.** Catalyst-replatform candidate. Until then the exploded view ships as a static PDF; do not put a "click to add" affordance on a Stencil page.
- 🧹 **Promote the Phase 1 patterns to Caster on their 2nd consumer** — `.model-hero`, `.doc-grid` / `.doc-card`, `.service-block`, `.related-model`, `.section-head` (rule #7). Carry the narrow-viewport fix with `.section-head`: its nowrap "more →" link overflows below ~640px unless the row stacks. `.mini-part`, `.specs-card`, and `.model-hero__statbar` wait for Phase 2.

### Manufacturer (brand) pages
_Three directions for the ~399 manufacturer pages, with Tennant as the example: A machine-first (recommended base), B parts-first, C brand hub. Brief → [brand-page-concepts.md](brand-page-concepts.md) · deck → [`reviews/brand-pages.html`](../reviews/brand-pages.html) · prototypes → [`v2/brand-tennant-a.html`](../v2/brand-tennant-a.html), [`-b`](../v2/brand-tennant-b.html), [`-c`](../v2/brand-tennant-c.html). Live audit 2026-09-29._
- **[Next] Fix the homepage finder's links.** Tracked once, under [Find by Machine](#find-by-machine); it does not wait for the direction decision.
- 🔜 **Clean the model list (merch, OOTB).** Merge T1-B → T1B, V BP 10 and V-BP 10 → V-BP-10, V BP 6 → V-BP-6, V-WA 30 → V-WA-30 with 301s; move "36V BATT CHARGR" out; re-point or remove the "355" tile (it links to Atlas Material Handling's 355); make the OEM flag agree with "Aftermarket" names; fix the "Browse by & Price" label and the "Tennat" alt text.
- 🔜 **Client decisions.**
  - Pick a direction (logs as the next free PD-NNN).
  - Confirm the plan tier (custom-field filters).
  - HawkSearch dashboard access.
  - How model categories are maintained (T500E lists 713 parts: fitment may already exist).
  - Approve the merges and redirects.
- 🧭 **Quick wins (recommended path).** Category sort order; native Category and in-stock filters through the Contextual Filters API; search within the brand at the top; the live finder pre-set to the brand; document and service links in the description.
- 🧭 **Near-term.**
  - One brand template (A, plus C's documents and service strip) for the top 20 brands. Machine-type tags: about 245 rows for Tennant, about 780 for Nilfisk-Advance.
  - HawkSearch landing pages for filtering.
  - Trigger: over 30 days after the quick wins, the finder or a model tile is the first click on most visits, and brand-page quick-back is still above 25.6%.
- ⏸️ **Future.** Serial lookup; identify a machine from a photo (after the AI Parts Finder evaluation); your machines first (the PD-003 fleet phase); OEM-to-aftermarket cross-reference; clickable diagrams.
- ⏸️ **Check the fitment signal before re-planning.** Model categories already map parts to machines. If they are trustworthy, the `compatible_models[]` gate on PD-004 and three Phase 2s is closer than planned.
- 🧹 **Move the four older inline concept ribbons** (equipment A/B, both model-landing pages) onto `assets/concept-ribbon.js`.
- 🧹 **Promote to Caster on the decision.**
  - Shared by the three pages: `.model-tile`, the machine directory, `.machine-combobox`, `.product-card__label` (its Tennant variant duplicates Caster's `.product-card__badge-oem`: reuse that rather than add a second class).
  - Second use: the search page's filter group, chips and drawer; model-landing's `.doc-card`, `.service-block` and `.section-head` (with its 640px stacking fix).
- 🧹 **Fix the v2 announcement bar's sideways scroll on phones.** The bar is one non-wrapping row that needs 392 px (its link text does wrap), so the bar alone pushes 24 of 25 v2 pages 72 px sideways at 320 px wide and 17 px at 375; other header chrome adds more on most of them (cart and pdp reach 104 px at 320). Found while measuring the manufacturer pages; the prototypes' checks treat 17 px at 375 as the baseline.

### Equipment commerce (PDP + compare)
- 🔜 **Client decision: equipment PDP Option A vs Option B.** Both concepts are built and clickable (`v2/equipment-pdp-a.html` spec-forward, `v2/equipment-pdp-b.html` guided) with a review deck at [`reviews/equipment.html`](../reviews/equipment.html). Recommendation: A's architecture as the base, B's calculator/expert modules grafted on later. Logs as **PD-005** when decided. Full brief → [equipment-concepts.md](equipment-concepts.md).
- 🧭 **Phase 1 — native data fixes.** Populate spec custom fields from the existing PDF, correct the warranty field (5-yr parts / 2-yr labor), host docs on-domain, wire related products, enable native compare + B2B quotes + native reviews. No custom code.
- **[Planned] Name each machine one way across its page.** Today the page title and the heading name the machine differently; the title, meta description and breadcrumb should agree. Part of the Phase 1 native fixes. (live audit [F11](live-site-audit.md#f11))
- 🧭 **Phase 2 — custom compare + moat modules.** Compare template to the prototype's spec (`v2/equipment-compare.html` + `js/equipment-compare.js`), commonly-replaced-parts module, cost-of-ownership table, financing app. Data-gated on the Phase-1 analytics triggers (brief §08).
- 🧹 **Promote queued equipment patterns to Caster on PD-005** — `.spec-table`, `.unit-toggle`, `.warranty-banner`, `.parts-rail`, `.equip-card`, compare tray/grid (rule #7 promotion queue in the brief §07), then `/bump-cache-bust`.

### Loyalty (self-serve individual)
_Scoped deliberately to the **self-serve** buyer — technician, single-location buyer, owner-operator. National Accounts are out: a company user's `customer_group_id` is already spent on their contract price list, and their Net-30 / PO / EDI orders never reach checkout, so they need an off-invoice rebate instead. Full brief → [loyalty-concepts.md](loyalty-concepts.md) · deck → [`reviews/loyalty.html`](../reviews/loyalty.html)._
- 🔜 **Run the retention query that decides everything.** Of customers with ≥1 prior purchase, what share of their *subsequent* orders are placed logged-in? This isolates the real retention failure from ordinary anonymous browse traffic, and it decides whether the program is urgent or optional. **It's a query, not a project.** Nothing else here should be built first.
- 🔜 **Quick wins — all OOTB, ~zero cost.** (1) Turn on auto-create-account-at-guest-checkout (a radio button — and the precondition for *every* other mechanic); (2) the login-gated free-freight threshold ($50 signed in / $125 guest — two automatic promotions, Zoro's move); (3) native promotion `notifications` for the tier-aware "you're $18 from free freight" nudge; (4) enable multi-coupon + `can_be_used_with_other_promotions: true` so a promo code doesn't silently cancel a member's tier discount.
- 🔜 **Client decision: reward mechanic (freight status program vs points).** Recommendation is freight — on a $60 basket it's worth 5–10× what the richest points program returns, and it's free to build. Logs as **PD-006** when decided.
- 🧭 **Phase 1 — USA Clean Pro.** Silver/Gold/Platinum on native Customer Groups + a nightly tier job (Orders API → `PUT /v3/customers` `customer_group_id`). Prototypes built: [`v2/account-rewards.html`](../v2/account-rewards.html), freight nudge in [`v2/cart.html`](../v2/cart.html). **No app, no recurring fee.**
- 🧭 **Phase 1 — "claim your past orders" backfill + passwordless login.** Link orphaned guest orders by email so a new account is full of the buyer's own history on day one. **Test first:** is `customer_id` writable on `PUT /v2/orders/{id}` for an existing guest order? (Half-day sandbox spike — the highest-leverage unknown in the brief.)
- ⏸️ **Phase 2 — store credit + our own earn ledger.** Data-gated on logged-in order share being high enough that credits are actually seen and spent. BC stores the *balance* but keeps no history and has no outstanding-liability report — the ledger is ours.
- ⛔ **Blocked on client answers before any build:** BC plan tier (Customer Groups need **Growth or above** — the engine doesn't exist on Core); are any consumables bulk-pricing rules **fixed-amount** (they'd silently void the tier discount on the highest-velocity SKUs); freight as a share of a typical self-serve order; consumables gross margin.
- 🧹 **Promote `.freight-nudge` to Caster on its 2nd consumer** (likely PDP or mini-cart) — rule #7. Inline in `v2/cart.html` today; no cache-bust needed yet.

### Navigation & taxonomy
- **[Planned] Build out the IA roadmap's sections.** A Find Parts section at `/parts/`, Equipment led by machine type, and a Chemicals & Supplies section. (live audit [F01](live-site-audit.md#f01))
- **[Planned] Add a Resources section to the nav, make Service a full section, and move Returns out of About.** Service is a single page today. (live audit [F01](live-site-audit.md#f01))

### Find by Machine
- **[Next] Fix the homepage finder's dead end for Tennant.** Choosing Tennant Company and T500E leads to `/parts-and-supplies/Tennant-Company/T500E/`, a "page not found" error; the real page is `/parts-and-supplies/tennant/t500e/`. The theme passes through the address the legacy parts system supplies, so either that data has to be corrected or the theme has to build the address itself, for every brand whose name differs from its web address. The manufacturer-page audit found 8 of 11 other names failing the same way, including Floorcare.biz, Clarke (Alto), and APA and Kent (Nilfisk-Advance). Once the links reach the real categories, retire the near-empty `tennant-company` category. (live audit [F02](live-site-audit.md#f02); [brand-page-concepts.md](brand-page-concepts.md))
- **[Planned] Phase 1 — the rest.** The "filter to fit your machine" prompt on results pages, the find-by-machine column in the nav (see the megamenu), and the finder card's typed model number, serial lookup and diagrams link. (live audit [F02](live-site-audit.md#f02))
- **[Data-gated] Phase 2.** The machine-lookup band on model pages, the compatibility filter on results, the "Fits (model)" badge on cart lines, the nav form wired to the lookup, and a fleet machine select in the fit checker. Most of it waits on the part-to-model compatibility mapping (PD-004; see the tagging item under Model landing pages). (live audit [F02](live-site-audit.md#f02))

### Find Parts megamenu
- **[Planned] Build the megamenu.** The full-width Find Parts panel with brand, grouped-category and promoted columns; compact dropdowns for the other sections; and the mobile drawer. The nav is the theme's stock dropdown today. (live audit [F04](live-site-audit.md#f04))

### PDP bundles
- **[Next] Settle the bundle saving, and add the quantity steppers.** The Frequently Bought Together block shows the bundle total as a plain sum, because the theme's discount was set to zero on 2026-09-01. The prototype takes 10% off the bundle total. Confirm whether a store promotion applies the saving: if it does, show it as designed, with the "Save 10%" line; if not, drop the saving from the design. Add the per-item quantity steppers either way. (live audit [F07](live-site-audit.md#f07))

### Volume discounts
- **[Planned] Phase 1.** The "Buy more, save more" tier table on product pages, the Bulk save badge on listings, and the cart's bulk pill, nudge and savings strip. (live audit [F08](live-site-audit.md#f08))

### Install & repair guides
- **[Planned] Phase 1.** A Guides & Videos tab carrying the part's own install and repair files, links that open this part's documents, and the mobile "Guides & Videos" button (on phones the sticky bar is Add to Cart). The theme's Videos tab, for products that have videos, is a start. (live audit [F09](live-site-audit.md#f09))

### Inventory urgency
- **[Planned] Phase 1.** "Only N left" counts on product pages and cards, the cart line's stock counts ("N left", "ships within N days"), backorder states, and notify-me. (live audit [F10](live-site-audit.md#f10))

### Save for later & named lists
- **[Planned] Phase 1 — Save for Later (pilot).** (live audit [F13](live-site-audit.md#f13))
- **[Planned] Phase 2 — named lists and a Saved Lists page.** Follows Save for Later. (live audit [F14](live-site-audit.md#f14))

### Recently purchased / Buy again
- **[Planned] Phase 1.** The Buy Again list and account tab, and the sign-in bridge for guests. (live audit [F16](live-site-audit.md#f16))

### Storefront pages without a brief
_Designed in the prototype only, with no brief or phase plan._
- **[Planned] Product page: the breadcrumb, image thumbnails where a product has several images, and the Shipping & Returns tab.** (live audit [F06](live-site-audit.md#f06))
- **[Planned] Cart: the benefits list under checkout.** (live audit [F12](live-site-audit.md#f12))
- **[Planned] Homepage: the hero's calls to action and stats bar, equipment-type tiles, subscription bundles, and the "Why USA Clean" band.** (live audit [F20](live-site-audit.md#f20))
- **[Planned] Header: the notifications bell, the announcement bar (warehouses, hours, Pro Account, Help, Track Order), the signed-in name and company, and the "Talk to a parts expert" call-out in the nav bar.** (live audit [F21](live-site-audit.md#f21))
- **[Planned] Shop Parts landing: the machine-first hero, with brand chips and model or serial entry; shortcuts to saved machines and parts-diagram upload; the machine illustration with part-number callouts; and the value-props strip.** "Shop Parts" leads to the A-Z brand directory today. (live audit [F22](live-site-audit.md#f22))
- **[Planned] Caster's component library on the live theme.** Buttons, product cards, pills, stock badges, machine cards and the rest, plus the product page styles still missing: the price block and the compatibility checker. (live audit [F23](live-site-audit.md#f23))

### Data-gated product decisions
_These are deferred-on-purpose in [`decisions.md`](decisions.md); listed here so the trigger conditions are visible alongside the rest of the upcoming work._
- ⏸️ **PD-001 — bundle Concept C** ("Build Your Bundle" configurator). Reopens on measurable AOV lift + observable swap intent + meaningful FBT add-all completion.
- ⏸️ **PD-003 — fleet / equipment view.** Reopens when the National Account fleet phase enters scope (markup is commented out, not deleted, in `v2/account.html`).
- ⏸️ **PD-004 — model-fit badge** ("Fits <model>"). Reopens when a part-to-model compatibility mapping exists (tied to the search / model-mapping work).

### Q&A assistant (UC Assist, PD-007)
- **[Next] Redeploy the assistant Worker** so it serves the corpus rebuilt on 2026-09-29, which includes the live-site audit. The Worker is deployed and `WORKER_URL` is set in `assets/ucassist-loader.js`; it answers from the corpus committed at its last deploy. Runbook in `tools/ucassist-worker/README.md`.
- 🧭 **Regenerate the corpus when docs change.** `node tools/ucassist-worker/build-corpus.mjs` after editing any brief, then redeploy the Worker. `--check` reports drift; `GET /health` reports which corpus is live.
- 🧭 **Close the three missing replatform verdicts** — `account-concepts`, `bundle-concepts`, `saved-cart-concepts` carry no Catalyst section, which is the gap called out in [platform-strategy](platform-strategy.md) § 7. The account one is the highest value.

### Process & docs
- 🧭 **Spin up more review decks** from `reviews/_template.html` as features come up for review.
- 🧹 **Refresh CLAUDE.md "Where things stand."** Currently a couple of commits stale — it predates the 2026-06-03 client-review round (PD-003 / PD-004) and the Claude Code playbook.

---

## Review notes

_Generated from `review`-labeled GitHub Issues by the `triage-notes` skill. The issues are the source of truth; this is the readable rollup. Severity order within a page: 🐞 bug → 🔧 update → 💬 comment._

_No review round has been triaged yet — run the `triage-notes` skill after a review round to populate this section (one `##` sub-section per page)._