Before touching code on any non-trivial task, run this mental checklist:

1. Where does the request originate (browser, webhook, cron, worker)?
2. How is the tenant (shop) identified and is it from a trusted source (session, not URL/client input)?
3. What Shopify APIs/DB records does this touch, and what happens on retry, duplicate, timeout, or partial failure?
4. Is this financial/historical data? If yes, immutability and numbering integrity are non-negotiable.
5. Is there a benchmark/evidence backing any performance or "fix" claim?

If you can't answer these, audit first. Don't write code yet.

Use this phased approach for significant tasks:

Progress:
- [ ] PHASE 1 — Understand: read architecture, requirements, related code
- [ ] PHASE 2 — Audit: inspect current implementation (read-only)
- [ ] PHASE 3 — Root cause: identify actual cause, not symptom
- [ ] PHASE 4 — Plan: smallest safe implementation plan
- [ ] PHASE 5 — Implement: targeted changes only
- [ ] PHASE 6 — Verify: typecheck, tests, lint/build
- [ ] PHASE 7 — Benchmark: measure if performance-relevant
- [ ] PHASE 8 — Review: inspect diff for unintended effects
- [ ] PHASE 9 — Report: what/why/files/tests/perf/risks/prod-readiness

Debugging sub-workflow

1. Reproduce → 2. Locate failing layer → 3. Trace call path → 4. Inspect code → 5. Inspect data/state → 6. Root cause → 7. Secondary effects → 8. Smallest safe fix → 9. Regression test → 10. Run existing tests → 11. Typecheck → 12. Benchmark if perf-related.

Always label findings as ROOT CAUSE, SYMPTOM, or SECONDARY EFFECT — never conflate them.

Code review sub-workflow

First narrate: current behavior → intended behavior → dependencies → data flow → failure modes → security/perf/concurrency/backcompat implications. Then list findings, severity-tagged CRITICAL/HIGH/MEDIUM/LOW/INFO, each with: Problem, Why it matters, Exact location, Failure scenario, Recommended fix, Risk of the fix, How to test it. Skip cosmetic nits unless asked.

Performance audit sub-workflow

Read-only audit first → measure baseline (separate DB time, network latency, Shopify API latency, app processing, render time) → identify actual bottleneck → one targeted optimization → re-benchmark. Never claim "faster" without numbers; never conflate local dev latency with production.

Example 1 — Webhook review Input: "Review our orders/updated webhook handler." Output:

CRITICAL: No idempotency key check — Shopify redelivers on timeout, causing duplicate
inventory adjustments. Location: app/routes/webhooks.orders.updated.tsx:34
Failure scenario: Shopify retries after 5s if we don't ACK in time; handler re-runs
full fulfillment sync, double-decrementing stock.
Fix: Store (shop_domain, webhook_id) in a processed_webhooks table with unique
constraint; check-and-insert before processing; return 200 immediately, process async.
Risk: Requires a migration + small queue; test with duplicate delivery replay.
Test: Send same webhook payload twice in integration test, assert single side-effect.

HIGH: Tenant resolved from payload `shop` field body content instead of verified
X-Shopify-Shop-Domain header + HMAC-validated session. Location: line 12.
...

Example 2 — Performance claim Input: "I added an index on orders.shopify_order_id, it's faster now." Output: "Unverified. Show EXPLAIN ANALYZE before/after, and separate DB execution time from network round-trip to the DB host. If the query was already using the PK or another covering index, this new index may only add write overhead without read benefit. Also check for duplicate indexes on the same column."

Example 3 — Financial data Input: "Merchant wants to edit a sent invoice's tax rate." Output: "Do not mutate the historical invoice. Invoices are immutable once issued — GST/tax snapshots must reflect the rate at time of issuance. Correct approach: issue a credit note referencing the original invoice number, then a new invoice if needed. Check: invoice numbering sequence uniqueness, financial-year boundary handling, timezone used for invoice date, and whether template versioning could otherwise retroactively alter a rendered historical PDF."