Yellow Wing Roasters — Master Technical Debt & Optimization Roadmap (`TODO.md`)

This document is the authoritative evaluation and backlog for the Yellow Wing Roasters Jekyll codebase. It consolidates the re-evaluation of:

DRY_OPTIMIZATION_RECOMMENDATIONS.md
AGENTS.md & .agents/rules/coding-principles.md
.agents/skills/ywr-coding-guidelines/SKILL.md
Operational tracking from TODO.txt (Email confirmation automation)

1. Executive Summary & Health Scorecard

Over the recent refactoring cycles, major architectural consolidations were achieved:

Category Engine Unification: Extracted _includes/category-section.html and _layouts/category.html, eliminating duplicate category markup across 6 listing pages and retiring 3 bespoke card includes (custom-cards.html, flight-cards.html, subscription-cards.html) in favor of universal _includes/roast-card.html.
Mascot Standardization: Retired the complex “Lazy Susan” component in favor of standard mascot_file: peck-your-own-transparent.png for Peck Your Own, stripping ~190 lines of specialized SCSS.
Data Centralization: Standardized grind levels in _data/grind_levels.yml, canonical brewing methods in roasts/index.markdown, badge colors in _data/badge_colors.yml, and store delivery radius in _config.yml.
Inline Style Reduction: Cut inline style="..." attributes from 791 down to 222.

However, deep re-evaluation reveals critical areas that still require immediate attention:

_data/bag_sizes.yml is orphaned: Created in config but not yet consumed by templates or scripts, leaving hardcoded '12oz', fabricated size arrays in gift.markdown, and static <option> tags in _custom/bring-your-own-burner.md.
Schema.org Multi-tier Ladders: _layouts/roast.html still has a 5-level fallback ladder for highPrice.
Silent Early Returns in Client JS: order-checkout.js, flights.js, byob-burner.js, and manage-subscriptions.js still contain silent if (!element) return; aborts that hide runtime errors.
Flight Mascot Mismatch in JS: js/flights.js hardcodes audubon-cardinal-transparent.png when adding Peck Your Own to cart instead of using the new peck-your-own-transparent.png.
Duplicate Form Submission Iframes: 4 separate client scripts independently create identical hidden <iframe> DOM nodes for Google Form submissions.
Email Confirmation Gaps: Gift subscriptions and BYOB submissions do not trigger recipient notification emails.

2. Re-Evaluation of `DRY_OPTIMIZATION_RECOMMENDATIONS.md`

2.1 Liquid Templates & Layouts

2.1 Category Pages Layout Consolidation
- Status: COMPLETE (Commit 85e52a4)
- Details: All category pages delegate to _layouts/category.html and _includes/category-section.html.
2.2 Status-Partitioned Roast Sorting & Collection Engine
- Status: COMPLETE (Commit 85e52a4)
- Details: 3-tier partitioning (active $\rightarrow$ incubating $\rightarrow$ flown_south) and collection resolution unified in _includes/category-section.html.
2.3 Roast Level & Dots Component
- Status: COMPLETE (Commit 0da4f5d & prior)
- Details: Centralized in _includes/roast-dots.html.
2.4 Grind Selector Dropdown
- Status: COMPLETE (Commit b7dc0f1)
- Details: Centralized in _data/grind_levels.yml and _includes/grind-options.html.
2.5 Minimal-Vertical Page Hero Layout
- Status: COMPLETE
- Details: Created _layouts/detail-page.html (inheriting from default.html) that standardizes the .roast-minimal-vertical hero header (divider, mascot_file, title/card_title, subtitle, intro, divider) driven strictly by frontmatter. Migrated _layouts/subscription.html, _flights/the-aviary.md, _flights/peck-your-own.md, _custom/bring-your-own-beans.md, _custom/bring-your-own-burner.md, and _custom/build-your-own-blend.md, eliminating over 110 lines of repetitive boilerplate markup.
2.6 Mascot Asset Standardization (Retired Lazy Susan Component)
- Status: COMPLETE (Commit 85e52a4)
- Details: Replaced with peck-your-own-transparent.png. Deleted _includes/lazy-susan.html and cleaned SCSS.
2.7 Checkout & Intake Form Snippets
- Status: KEPT SEPARATE (DECIDED)
- Details: Per user decision, form markup across order checkout and custom roaster intake forms will remain separate and localized to avoid tight coupling and maintain self-contained templates.

2.2 CSS & SASS Consolidations

3.1 Eliminating Remaining 222 Inline Styles
- Status: IN PROGRESS (Reduced from 791 to 222)
- Remaining Hotspots:
  - preview-pricing.html: 32 occurrences
  - _custom/bring-your-own-burner.md: 26 occurrences
  - _custom/build-your-own-blend.md: 25 occurrences
  - gift.markdown: 23 occurrences
  - _layouts/roast.html: 13 occurrences
- Action: Move inline form container styles (max-width, margin, display:none) into semantic classes (.u-hidden, .order-form, .price-bar).
3.2 Form Label Alignment Conflict
- Status: NOT STARTED
- Problem: .roast-mv-meta-label in _sass/_roast-detail.scss sets text-align: center, forcing labels on checkout and intake forms to override with style="text-align: left;" or display: block.
- Action: Set default form labels to text-align: left in _base.scss and use a modifier .roast-mv-meta-label--center specifically for detail page centered headers.
3.3 Sass Maps for Category Theming
- Status: COMPLETE (Commit b7dc0f1)
- Details: Refactored category backgrounds in _sass/_cards.scss with a Sass $category-colors map and @each loop.
3.4 Reusable Button / Pill Mixin
- Status: NOT STARTED
- Problem: Repetitive button shapes, display fonts, uppercase tracking, and hover transitions across .roasts-quiz-cta, .order-submit, .add-to-order-btn, .roasts-entry-quick-add, and .add-to-blend-button.
- Action: Define @mixin pill-button($bg, $color) in _sass/_variables.scss or _sass/_base.scss.
3.5 Backdrop Blur Mixin
- Status: NOT STARTED
- Problem: 10 duplicate declarations of backdrop-filter: blur(3.5px); -webkit-backdrop-filter: blur(3.5px); in _sass/_roast-detail.scss.
- Action: Define @mixin backdrop-blur($radius: 3.5px) and replace declarations.

2.3 Data Centralization (`_data/` & `_config.yml`)

4.1 _data/grind_levels.yml
- Status: COMPLETE
4.2 Standardize Brewing Methods
- Status: COMPLETE (Commit 0da4f5d)
- Details: Canonical brewing methods hardcoded into filter select in roasts/index.markdown, removing dynamic DOM generation and method maps from catalog-filters.js.
4.3 Google Forms Centralization Cleanup
- Status: COMPLETE
- Details: Migrated gift.markdown to consume site.google_forms.digital_gift.url and site.google_forms.digital_gift.entries, and deleted redundant root-level digital_gift_form_url and digital_gift_entries keys from _config.yml.
4.4 Connect _data/bag_sizes.yml Across Templates & Scripts
- Status: COMPLETE
- Details: Created _includes/bag-size-options.html driven by _data/bag_sizes.yml. Integrated into _custom/bring-your-own-burner.md, exposed window.YWR_BAG_SIZES in js/cart-data.js, and cleaned gift.markdown to derive sizes directly from r.price and s.sizes without fabricated size arrays.

2.4 JavaScript Modularization

5.1 Shared Cart Storage & Retrieval
- Status: COMPLETE (Commit 03a7cee)
- Details: Unified on window.ywrGetCart() and window.ywrAddToCart(). The old duplicate parts = ck.split('|') parsing has been removed.
5.2 Unified Google Form Iframe Submissions
- Status: KEPT SEPARATE (DECIDED)
- Details: Per design decision, hidden iframe generation and submission lifecycles are kept intentionally localized within each form script (order-checkout.js, form-submit.js, byob-mixer.js, gift-order.js) to maintain self-contained modularity and avoid tight cross-script coupling.

2.5 Defensive Coding & Silent Fallback Elimination

2.6 Repository Hygiene

7.1 Relocate Standalone Preview Files to _previews/
- Status: NOT STARTED
- Files in root:
  - coming-soon-preview.html
  - footer-icon-preview.html
  - main-icon-preview.html
  - preview-bags.html
  - preview-bags-v2.html
  - preview-pricing.html
  - roast-card-color-playground.html
  - roast-detail-preview.html
  - social-preview-generator.html
- Action: Move into _previews/ and update _config.yml exclude paths.

3. Re-Evaluation Against Coding Principles (`AGENTS.md`, `coding-principles.md`, `SKILL.md`)

Principle 1: Config-Driven Over Hardcoded (Fail Rather Than Guess)

“I’d rather a failure than a default value that doesn’t make sense.”

File	Line(s)	Violation	Status / Remediation
`gift.markdown`	415	`default_sub_sizes = "12oz,1lb,2lb,5lb"` fabricated string array	RESOLVED: Sizes derived dynamically from `r.price` and `s.sizes`
`_custom/bring-your-own-burner.md`	84–88	Static `<option>` tags for 12oz, 1lb, 2lb, 5lb	RESOLVED: Rendered via `_includes/bag-size-options.html` driven by `_data/bag_sizes.yml`
`js/flights.js`	28, 72, 73	`options.price \\|\\| 38`, `options.pricePerBag \\|\\| 10`, `minBags \\|\\| 4`	RESOLVED: Direct reads from frontmatter options without fallback numbers
`js/flights.js`	140	Hardcoded mascot `audubon-cardinal-transparent.png`	RESOLVED: Reads mascot from flight frontmatter
`js/order-checkout.js`	65–66	`params.get('size') \\|\\| '12oz'`, `params.get('grind') \\|\\| 'Whole Bean'`	RESOLVED: Reads from catalog entry sizes and `window.YWR_DEFAULT_GRIND`
`js/roast-detail.js`	21	`var defaultFreq = config.defaultFreq \\|\\| 'Monthly';`	RESOLVED: Deleted dead phantom variable and unused parameter

Principle 2: Simple & Direct Lookups (No Defensive Guessing, No Phantom Variables)

File	Line(s)	Violation	Status / Remediation
`gift.markdown`	421	`r_sub.price \\| default: r.price`	RESOLVED: Standard roasts only declare `price:`; reads `r.price` directly
`gift.markdown`	173–200	`roast.descriptor \\| default: roast.subtitle \\| default: 'Blend'`	RESOLVED: Direct `roast.descriptor` read
`_layouts/roast.html`	250	`sub_config.price \\| default: roast_prices`	RESOLVED: Reads `roast_prices` directly
`_layouts/roast.html`	275	5-level fallback ladder for `highPrice` in Schema.org	RESOLVED: Reads `roast_prices[sizes.last]` directly
`js/cart-data.js`	63	`site.data.roast_levels[lvl_num] \\| default: site.data.roast_levels[lvl_num_str]`	RESOLVED: Direct integer lookup in `roast_levels.yml`

Principle 3: Natural Runtime Exceptions (No Manual Guard Boilerplate)

File	Line(s)	Violation	Status / Remediation
`js/order-checkout.js`	29	`if (!form \\|\\| !emptyEl \\|\\| !itemsEl) return;`	RESOLVED: Removed silent guard; let `form.addEventListener` throw if missing
`js/flights.js`	79	`if (!addBtn \\|\\| !countEl) return;`	RESOLVED: Removed silent return; let DOM operations throw `TypeError`
`js/byob-burner.js`	34	`if (!originSelect) return;`	RESOLVED: Removed silent return
`js/gift-order.js`	183	`if (!customMenu \\|\\| !customTrigger) return;`	RESOLVED: Removed silent return and defensive ternaries
`js/manage-subscriptions.js`	59	`if (!lookupForm \\|\\| ... \\|\\| !resultsSection) return;`	RESOLVED: Removed silent return
`js/manage-subscriptions.js`	44	Silent `catch (e) {}`	RESOLVED: Added `console.error('saveMockDb: Failed to save mock subscriptions:', e)`
`js/order-checkout.js`	638–639	Silent `catch (e) {}` around storage removal	RESOLVED: Added `console.warn` if storage removal throws

Principle 4: Ask Rather Than Fall Back on Missing Data

Rule: If a field is missing in YAML frontmatter or configs, ask the user or supply the underlying data instead of writing fallback ternaries in templates.
Recent Example: When _custom/ and _flights/ were missing category, rather than retaining include.category | default: r.category, we added category: custom and category: flight to the frontmatter files, enabling direct r.category lookups.

4. Email Automation & Operational Gaps (from `TODO.txt`)

4.1 Gift Subscriptions Recipient Notification Email
- Status: COMPLETE
- Details: Implemented Option B dual-submission architecture. Created dedicated Google Form for Gift Subscriptions (site.google_forms.gift_subscription) with Apps Script trigger in scripts/google-forms/gift-subscriptions/ that dispatches purchaser-confirmation.html (receipt with price to buyer) and recipient-announcement.html (gift announcement without price to recipient). Updated js/gift-order.js to dual-post to the gift form while submitting recipient delivery details to site.google_forms.subscription. Both emails are sent intentionally to the recipient; added a direct link to the Subscription Management page in subscription.html, added ?email= auto-lookup in js/manage-subscriptions.js, and resolved doGet function name collision across Code.gs and Management.gs.
4.2 BYOB (Build Your Own Blend) Customer Confirmation Email
- Problem: BYOB submissions to site.google_forms.byob_blend.url are stored in Google Sheets, but there is no Google Apps Script trigger script in scripts/google-forms/ to email a recipe confirmation to the customer.
- Action: Create scripts/google-forms/byob/Code.gs and byob-confirmation-template.html to send a branded blend recipe summary to e.namedValues['Email'][0].

5. Master Prioritized Implementation Checklist

Phase 1: Critical Architectural & Coding Principle Fixes (Immediate)

Wire up _data/bag_sizes.yml to gift.markdown and _custom/bring-your-own-burner.md.
Fix hardcoded mascot audubon-cardinal-transparent.png in js/flights.js to use peck-your-own-transparent.png.
Expose window.YWR_FLIGHTS_DATA in js/cart-data.js and remove fallback numbers (38, 10, 4) from js/flights.js.
Remove 5-level Schema.org price ladder in _layouts/roast.html.
Remove default_freqs and sub_prices = sub_config.price | default: roast_prices fallback in _layouts/roast.html.
Clean up gift.markdown Google Form config to use site.google_forms.digital_gift and delete duplicate lines 10–19 from _config.yml.

Phase 2: JavaScript Hardening & Fast-Fail (Short-Term)

Replace silent if (!el) return; aborts in order-checkout.js, flights.js, byob-burner.js, gift-order.js, and manage-subscriptions.js with natural DOM reads and explicit error logging.
Iframe submission lifecycles kept intentionally localized within each script (Kept separate per design decision).
Replace levelDotsMap and dotNumberToLevel in js/byob-burner.js with window.YWR_ROAST_LEVELS.

Phase 3: Layouts & Template DRYing (Medium-Term)

Create _layouts/detail-page.html to eliminate 7 duplicate .roast-minimal-vertical hero blocks.
Form templates kept separate and localized across checkout & custom roasters (Kept separate per user decision).

Phase 4: CSS Consolidation & Repository Hygiene (Polishing)

Move inline styles from bring-your-own-burner.md, build-your-own-blend.md, and gift.markdown to SCSS classes.
Add @mixin pill-button and @mixin backdrop-blur to _sass/.
Move standalone preview HTML files into _previews/ and update _config.yml exclusion list.

Phase 5: Operational & Email Automation (Features)

Implement recipient notification in scripts/google-forms/subscriptions/Code.gs.
Implement BYOB recipe confirmation in scripts/google-forms/byob/Code.gs.

Yellow Wing Roasters — Master Technical Debt & Optimization Roadmap (TODO.md)