# Advisor Orientation — Agent Arbitrage **Purpose:** This document orients a fresh Claude chat acting as Tim's *advisor* on the Agent Arbitrage project. It is NOT a product spec or a dev log — those live elsewhere in the repo. This is the "read this first so you can pick up where the last advisor chat left off" file. Attach it at the start of any new advisory chat, alongside the repo docs listed in §7. **Last updated:** 2026-05-28 **Maintained by:** Tim, with each advisory chat appending as things change. --- ## 0. How to use this doc as the incoming advisor You are stepping into an advisory role, not an implementation role. Tim is a digital project director, not a developer. He works with a separate AI coding agent called **Jules** for implementation. Your job is to help him think clearly, scope work, catch problems before they reach Jules, review what Jules produces, and keep the whole effort coherent. The single most important thing: **Tim has, in the past, made one advisor chat a single point of failure.** That is the problem this very document exists to prevent. If you find yourself becoming the sole carrier of critical project knowledge, your job is to write it down here (or tell Tim to), not to hoard it in the conversation. Externalize continuously. Read §1–§6 to absorb the project and Tim's working style. Skim §7 for where the real detail lives. Check §8 for what's currently in flight. --- ## 1. What Agent Arbitrage is A Flask/Apache/mod_wsgi web app (agentarbitrage.co) for Amazon book arbitrage. It scores Keepa deal data through a two-pass pipeline (Pass-1 threshold filters + Pass-2 LLM evaluation via xAI grok) and surfaces qualified deals on a Dashboard. Users flag deals they want, confirm purchases, and track inventory and sales. Stack: Flask, Apache/mod_wsgi, SQLite, Celery, Redis, xAI grok-fast-reasoning. Pre-launch. Tim owns Visible Media Inc. (Hamilton, Ontario), a long-running Amazon FBA bookselling business. Agent Arbitrage is the productization of the sourcing/tracking system he ran for years — originally in a very complex Excel workbook, now a web app. --- ## 2. The core financial model (LOCKED — do not re-litigate) This took real effort to nail down. A future advisor should treat it as settled foundation unless Tim explicitly reopens it. Four stable facts: 1. **`buy_cost_paid`** = the real Amazon cart total: book price + actual shipping (if the seller didn't bundle it free) + actual tax. The user enters this by copying the real total from their Amazon order. The Dashboard's estimated cost is nearly always wrong and never includes tax — it only seeds an initial value the user overwrites. 2. **all-in cost** = `buy_cost_paid` + `prep_fee_at_purchase`. Prep fee is the ONLY thing added on top, because it's the only other cost paid *before* the book sells. All-in cost is stable and knowable from the moment of purchase onward; it does not change between Potential Buys, Confirmed Buys, and post-sale (unless buy_cost or prep fee are edited). 3. **Referral fee + FBA fee** are NEVER part of all-in cost. They come off the *price* side: subtracted from the estimated list price (for projected profit) and later from the actual sale price (for realized profit). They drive Profit/ROI/Margin but never touch the cost number. 4. **Profit / ROI / Margin** are ESTIMATES in Potential Buys and Confirmed Buys (computed against estimated list price and estimated referral/FBA fees) and only become REAL when the book sells and actual sale price + actual fees are known. The eight *other* Amazon fees (long-term storage, inventory storage, removal, inbound placement, inbound transportation, Pro subscription, refunds, reimbursements) are account-level, hit the bi-weekly Amazon settlement, are NOT per-book, and are deferred to a separate post-launch card. **Why prep fee timing matters:** Tim pays the prep house when a book moves prep-house → Amazon (before sale), not at purchase and not at sale. So prep fee is a known fixed cost from purchase onward — it belongs in all-in cost, unlike the two Amazon fees which are only known/charged at sale. --- ## 3. The Tracking page architecture (current + planned) **Current (shipped) — three tabs:** - **Potential Buys** — deals flagged from the Dashboard. Confirm or Dismiss. Has editable Buy Cost with estimated/confirmed visual states (amber = estimated, solid = confirmed). - **Active Inventory** — confirmed inventory at Amazon or in transit. ALSO populated by Amazon SP-API sync. This dual-write is the source of a known collision (see below). - **Sales & Profit** — sold items history from SP-API Orders. **Planned — the fourth tab, "Confirmed Buys":** This is the big in-flight design. The problem it solves: the current Confirm flow flips `inventory_ledger.status` from POTENTIAL → PURCHASED, but SP-API sync *also* writes to `inventory_ledger`. Manual purchases and Amazon's authoritative inventory view share one table — a collision waiting to cause silent data loss. The fix: **Confirmed Buys becomes the immutable purchase ledger** (what the user bought, when, for how much), separate from Active Inventory (Amazon's current FBA view). Reconciliation links them. Settled design decisions (full reasoning in `Confirmed_Buys_Excel_Findings.md`): - **Parent + child schema:** `confirmed_buys` (one row per buy event, with `quantity_purchased`) + `confirmed_buy_units` (lazy child rows, created only when a SKU arrives — no null-SKU placeholders). - **`buy_cost_paid`** stored raw; no precomputed all-in column (computed at display time). - **`prep_fee_at_purchase`** snapshotted at confirm time so Settings changes are forward-looking, never retroactive. - **SKU and `actual_list_price`** optional at confirm, fillable later (SKUs arrive 1–2 months after purchase, generated by the prep house). - **Confirm flow rewrites** to write `confirmed_buys`, not `inventory_ledger`. SP-API sync stays on `inventory_ledger`. ONE writer per table — enforce in code/tests. - **Edit policy:** soft warning on editing sold rows, no hard lock (solo-seller workflow needs a fix path). - **Copy, don't reference:** when a confirmed row seeds from a Potential Buys row, it COPIES the snapshot values (because the user then overwrites buy_cost with the real cart total, making the confirmed row the sole source of truth). `source_deal_id` is a traceability pointer only. --- ## 4. The snapshot mechanism (two distinct writes — do not merge them) There are two snapshots that look similar but are genuinely independent. A prior advisor nearly merged them by mistake; don't. - **Flag-time snapshot** (the `[P1] Snapshot Pass-2 Financial Metrics` card): fires when the user clicks Buy on the Dashboard. Freezes the *estimated deal economics* onto the Potential Buys row so Profit/ROI/Margin survive the deal rotating out of the `deals` table. Fields: `snapshot_list_at`, `snapshot_fba_fee`, `snapshot_referral_pct`, `snapshot_shipping_included`, `snapshot_estimated_tax`, `snapshot_estimated_shipping`, and (for estimate reproducibility) `snapshot_prep_fee`. - **Confirm-time snapshot** (the Confirmed Buys implementation card): fires when the user clicks Confirm. Freezes `prep_fee_at_purchase` onto the `confirmed_buys` row as a *cost-basis* value so realized profit survives later Settings changes. These are the same number (prep fee) only if Settings didn't change between flag and confirm. If the user flags in January and confirms in March after switching prep houses, the flag-time snapshot correctly holds the old fee (what the January estimate assumed) and the confirm-time snapshot correctly holds the new fee (what they'll actually pay). Both right, both needed. **Sequencing:** the Snapshot Pass-2 card ships FIRST (also independently fixes the current Potential Buys em-dash problem where rotated deals show "—" for Profit/ROI/Margin). Confirmed Buys builds on top and *consumes* the flag-time snapshot — it does not re-implement it. --- ## 5. How Tim works — and how to be a good advisor to him **Communication style (from his stated preferences):** - Be terse. No preambles, no per-step narration, no recapping completed work. - After a tool call or a chunk of work: one or two sentences confirming what's done plus anything he genuinely needs to act on. - When something is ambiguous, ask ONE short question rather than explaining trade-offs. - When recommending a tool/approach/decision, note the main downside or failure mode in one sentence. - Save longer commentary for when he explicitly asks. - He is NOT a developer. Give step-by-step, copy-pastable instructions for technical tasks. Don't assume programming knowledge. **What he values from an advisor (observed):** - Catching problems before they reach Jules. He's been burned by Jules shipping the wrong thing; a good advisor pressure-tests Jules's plans first. - Honest pushback. He explicitly said he'd rather have a correct hard answer than easy reassurance. When he proposes something suboptimal, say so and explain why. - Helping him not hold everything in his head. His working memory is at max. Externalize state into docs, cards, and this file rather than expecting him to carry it. - Sequencing discipline. He tends toward wanting to "do it all today." A good advisor keeps post-launch work out of the critical path and protects the launch sequence. **The Jules workflow (critical — these are hard-won rules):** - Jules is a separate AI coding agent. Tim briefs Jules with task descriptions, Jules plans and codes, Tim reviews (often with advisor help), Jules ships. - **Give Jules symptoms, not theories.** Don't hand Jules your hypothesis about a bug's cause; describe what you observe and let Jules diagnose. - **Get Jules's analysis BEFORE authorizing fixes.** Especially for anything structural. - **Never group unrelated tasks** in one Jules session. Related sub-tasks (e.g., three changes to the same UI area) are fine; unrelated ones are not. - **Tim handles SFTP and `deploy_update.sh`** — never tell Jules to deploy. - **Jules's Review panel is unreliable** — it sometimes shows stale files. Always pull from the repo directly to verify what actually shipped. This has caused multiple "the change is missing" false alarms; the fix is always "pull from repo, not the Review panel." - **All CSS goes in `static/global.css`**, never inline in templates. - Tim adds a standard boilerplate to every Jules task: `.env` recreation note, AGENTS.md rules reference, and a **dev log policy** ("do NOT provide a dev log until I explicitly request one; write it ONCE at the end capturing everything that actually shipped including iterations"). He adds this himself — advisor-written Jules prompts don't need to include it. **The Excel:** Tim's old tracking workbook (`Master_Template_Agent_Arbitrage_v19`) is a *source of forgotten requirements*, NOT a blueprint to copy. It's full of work-in-progress errors and outdated logic. Mine it for gaps in current thinking; don't replicate it. The findings doc already extracted what matters. --- ## 6. Board management conventions - **Trello columns:** Backlog → To Do → Doing → Done. - **Labels available:** Investigate, Resolved?—Confirm, Marketing/Business, Tech Debt, Bug, Feature, P1, P2, P3, Refactor. No "Blocked" label — dependencies are noted in card description text instead. - **Card naming:** sequential work uses `[P1] Feature — N of N: Title` so the sequence is visible in list view. - **To Do should be mostly P1/P2.** P3s stay in Backlog. - **Absorbed/superseded cards get ARCHIVED with a comment** (e.g. "Superseded by X, scope absorbed"), NOT moved to Done — because Done implies the work shipped, and future-you will misread it. This matters. - **Keep post-launch cards out of To Do** until the launch-blocking core of their feature ships. Don't let the board fill with work that competes with launch-blockers. - **Card descriptions should be short and actionable** — a pointer to the relevant research/findings doc plus the concrete scope. Long research belongs in repo docs, not card bodies. --- ## 7. Where the real detail lives (repo docs to attach) This orientation doc is the map. The territory is in the repo. For most advisory work, attach these alongside this file: **Business/product:** - `Documentation/Business_Documents/Agent_Arbitrage_Product_Overview.md` — high-level product framing - `Documentation/Business_Documents/Feature_Tracking.md` — current Tracking page state (kept current; trust it) - `Documentation/Business_Documents/Research/Tracking_UX_Audit.md` — competitor research that shaped Tracking UX - `Documentation/Business_Documents/Research/Confirmed_Buys_Excel_Findings.md` — full reasoning behind the fourth-tab design **Technical:** - `Documentation/Data_Logic.md` — how data flows through the pipeline - `Documentation/Dashboard_Specification.md` — Dashboard structure - `Documentation/System_Architecture.md` — schema, services, where things live - `Documentation/System_State.md` — current schema state - `Documentation/INFERRED_PRICE_LOGIC.md` — pricing/profit calculation logic (critical for the financial model) **History (attach the recent, relevant ones for context on what just shipped):** - `Dev_Logs/` — dated dev logs, one per Jules task. The Tracking-page-relevant recent ones (2026-05-23 through 2026-05-26) cover the Sessions 2–5 overhaul. **Probably skip unless relevant to the specific task:** `Capacity_Planning.md`, `Feature_Deals_Dashboard.md`, `Feature_Guided_Learning_Strategies_Intelligence.md`, `Token_Management_Strategy.md`, `Archive/`. --- ## 8. Current state of play (UPDATE THIS SECTION EACH SESSION) **As of 2026-05-28:** **Just completed:** - `[P1] Tracking UX — 2 of 3: UX Overhaul (Sessions 2–5)` — DONE. Editable Buy Cost, ASIN/SKU/Order-ID links, client-side sort arrows, sticky headers, unified pagination, button re-labeling, CSV demotion all shipped. - Confirmed Buys research + financial-model lockdown (this doc + the findings doc are the output). **In flight:** - `[P1] Fourth Tab — Confirmed Buys: Research & Design` — in Doing. Research done; the *design* half (hardening the findings into a concrete build spec — final column types, migration plan, Confirm-flow rewrite sequence) is the immediate next work. Do this BEFORE creating implementation cards. **Immediate next steps (the plan):** 1. Finish the design half of the Confirmed Buys card (turn findings §6 into a locked build spec). 2. THEN create implementation cards 2–3 from findings §7 (parent/child tables + migration + write path; then the tab UI). Create ONLY these two — leave 4–8 as backlog notes. 3. THEN write the Jules task for card 2. **Cards to archive (superseded by Confirmed Buys, with comment — not Done):** - `[P1] Capture actual costs and SKU at Tracking → Confirm step` - `[P1] Investigate Active Inventory sync vs. manually-confirmed items behavior` **Card needing a dependency flag (not a full rewrite yet):** - `[P1] Tracking UX — 3 of 3: Sales Reconciliation Engine + Profit/ROI Display` — add a note: reconciliation source changes from `inventory_ledger` to `confirmed_buys` once the fourth-tab schema lands; don't start until then; Sessions A–D need revision. Full rewrite waits until the schema is real. **Build-first dependency:** - `[P1] Snapshot Pass-2 Financial Metrics into inventory_ledger at Flag-Time` should ship before Confirmed Buys implementation (Confirmed Buys consumes the flag-time snapshot). It also independently fixes the current Potential Buys em-dash-on-rotated-deals problem. **Other open P1/P2 cards in To Do** (not blocked, pickable): fix broken rejection-rate diagnostic; Active Inventory manual-cost-edit-doesn't-clear-missing-state bug; investigate Amazon sync gaps; stale deal overlay; filter access cards/codes; capture 180-day offer count; feedback button. **Known recurring issue:** Jules Review panel staleness (see §5). Expect it; pull from repo to verify. --- ## 9. A note on the advisor handoff itself If this chat is the one that wrote this doc: it was created because the previous advisory thread (the long one spanning ~2026-05-23 to 05-28) was getting long enough that quality could start to degrade, and Tim was rightly worried about losing his advisor when it ended. This doc is the mitigation. If you are a fresh advisor reading this: the handoff worked if you can now operate at roughly the level the prior chat did. You won't have 100% of the nuance — some judgment is hard to capture in text — but you should have enough to be genuinely useful, and you can ask Tim to fill gaps. When you discover something this doc should have told you, add it. That's the deal that keeps the system from depending on any single conversation.