TM-203: Wisdom Archive
Curated carefully. Never overwritten automatically. Updated only when a pattern holds across 3+ runs, an instruction is explicitly confirmed, or an action produces a measurable outcome.
Last updated: 2026-10-27 (Design v2 — Seasonal wisdom entries added)
Wisdom: OH=0 Stores Must Be Included in All Pillar Queries
Established: 2026-10-26
Source: Observed outcome — previous runs excluded OH=0 stores from Uneven Distribution, causing transfer candidates to miss confirmed stockout sites
Rule: Every pillar query must include OH=0 stores. The Uneven Distribution pillar had AND current_on_hand_units > 0 removed. The add_candidate() function in build-transfers.py uses STOCKOUT_CONFIRMED classification to handle OH=-1 stores universally. Never re-add OH>0 filters to any pillar query without explicit approval.
Applies to: All 3 Pillars, Transfer Options Action
Wisdom: Transfer Options Runs AFTER Patterns/Dangers/Opportunities Are Updated
Established: 2026-10-26
Source: Tesfa instruction — "re-run Transfer_Option action since it will need to use some information from the Above structural components"
Rule: The Transfer Options action (build-transfers.py / build-transfers-html.py) must always run AFTER the 4 structural reports (Patterns, Dangers, Opportunities, Wisdom) have been updated for the current run. The Reasoning column in the HTML dashboard draws from these reports to contextualize each transfer recommendation.
Applies to: Transfer Options Action (Component 6), Run Checklist
Wisdom: HTML Generator Must Always Be build-transfers-html.py, Not Inline Generator
Established: 2026-10-26
Source: Observed outcome — when build-transfers.py ran its own HTML generation, it overwrote the improved dashboard features (sortable columns, Donor OH, Recipient OH columns, LOW conviction filter, Trend filter, Clear Sort). The authoritative HTML generator is build-transfers-html.py, which preserves all UI features.
Rule: After every run of build-transfers.py, always run build-transfers-html.py separately to regenerate the HTML dashboard. Never rely on build-transfers.py's built-in HTML output.
Applies to: Transfer Options Action
Wisdom: Reasoning Column Enriches Transfer Recommendations with Structural Context
Established: 2026-10-26
Source: Tesfa instruction — "let us add on Reasoning column on the Transfer_Options rows so I can see how you have reasoned those multiple outputs for each action"
Rule: Every transfer candidate row must include a Reasoning field that explains: (1) which pillar identified it, (2) what signal triggered it, (3) any Danger or Opportunity context relevant to the donor or recipient site, (4) conviction level rationale. The Reasoning column must be visible in the HTML dashboard.
Applies to: Transfer Options Action, build-transfers-html.py
Wisdom: Christmas Category Transfers Must Complete by Dec 1
Established: 2026-10-27
Source: Design v2 — seasonal window urgency rule, confirmed as defensible from known retail calendar
Rule: Any Christmas-category item (ornaments, Christmas cards, Christmas decor, Christmas gift wrap) that has not been transferred to its recipient site by December 1 has less than 25 days of peak selling remaining. After Dec 1, the urgency to transfer drops sharply and the item risks becoming post-holiday dead stock at the recipient. Transfer decisions for Christmas items must be executed before Dec 1 or reconsidered.
Applies to: Transfer Options Action (seasonal category items), Opportunities, Dangers (Seasonal Window Closing)
Wisdom: Ornament Velocity Window — Sept 1 to Dec 15
Established: 2026-10-27
Source: Design v2 — known retail calendar seasonality for Hallmark-channel ornament sales
Rule: Ornament category peak velocity window runs September 1 through December 15. After December 15, ornament demand drops sharply. Markdown threshold is January 15 — ornaments remaining after Jan 15 are write-off candidates, not transfer candidates. Transfers executed before Nov 15 have the highest chance of sell-through. Transfers after Dec 1 are speculative.
Applies to: Dead Stocks (Seasonally Overdue), Transfer Options, Opportunities
Wisdom: Post-Window Seasonal Stock — Transfer If Window Still Open at Recipient, Markdown Otherwise
Established: 2026-10-27
Source: Design v2 — logical rule for seasonal product past its primary sell window
Rule: When a seasonal item's primary sell window has closed at the donor site, check if the recipient site's window is still open (e.g., a Halloween item with a closed window in a Virginia store vs. an open window in a market with extended seasonal). If the recipient window is also closed, the item is a markdown candidate — do not recommend transfer. If the recipient window is still open, transfer is valid. When no recipient window distinction exists, default to markdown recommendation.
Applies to: Dead Stocks (Seasonally Overdue Dead, Never Sold — Seasonal), Transfer Options Action
Wisdom: Three Output Levels Required for Every Structural Component
Established: 2026-10-27
Source: Tesfa instruction — "we don't want it to be too high level nor too low level. we just want it to be effective and smooth" (2026-10-27 TM-203 conversation)
Rule: Patterns, Dangers, Opportunities, and Curiosity must each produce three output levels: (1) chain summary — one aggregate number for orientation, (2) item cluster — top 10-20 specific UPCs or UPC+site pairs ranked by retail value x urgency, (3) item-store pair — surfaced only in the Action (Transfer Options) table. The item cluster is the critical missing tier. Chain summaries alone are too general; full row dumps are too granular. The item cluster is the effective middle.
Applies to: All structural components (2 through 6), Run Checklist