Skip to content

Gotchas

Hard-won lessons. Each one cost us something once. Do not relearn them. When something new bites us, add it here.

Hosting and gating

  • Cloudflare Pages, not GitHub Pages. GitHub Pages will not serve a private repo on the free plan. In the Cloudflare wizard, use the "Looking to deploy Pages?" link; the default flow creates a Worker, which is wrong.
  • Gate both URLs. Always gate the custom domain and the .pages.dev fallback (as a second destination on the Access app). The fallback leaks private content if you forget it. This burned Hard Hat (client-hardhat.pages.dev was left ungated).
  • Never add clients as Cloudflare account Members. That is dashboard admin. Clients only go on the Access policy email list.
  • Confidential content only after the gate is live. Keep placeholders until Access is confirmed in incognito.

Build and cache

  • Stale CSS after deploy. docs/_headers sets no-cache on stylesheets/js/data so they revalidate after a deploy. Locally, hard-refresh (Ctrl+Shift+R).
  • MkDocs rewrites Markdown links but not raw-HTML src/href. Iframes to sibling assets need ../assets/..., not a bare filename.
  • Build --strict before committing. Zero warnings, or the deploy risks breaking.

Windows and Git

  • PowerShell 5.1 has no &&. Chain with ; and if ($?).
  • [...] in filenames breaks Move-Item (treated as wildcards). Use -LiteralPath.
  • "Dubious ownership" in GitHub Desktop for AI-sandbox folders: fix from the Windows user context with git config --global --add safe.directory "…/<folder>".

Data

  • Drop null-title product rows from exports.
  • The "Other" channel bucket can show an impossible CVR (orders exceed tracked sessions from attribution spread). Blank the rate and add a caveat rather than publishing a nonsense number.
  • Two Shopify export naming styles exist ("All Metrics…" vs "Total sales by day…"). The builder handles both; do not assume one.
  • Filter glitched vitals rows (for example an absurd multi-minute LCP). The builder already does this.
  • Call out anomaly weeks (session spikes with collapsed ATC/CVR) instead of letting them distort the trend.

Research

  • WebFetch reads static HTML only. Late-loading JS widgets (reviews, timers, some pricing) are invisible to it. Verify any "this element is missing" finding with a real browser before recording it. This burned us once on Hard Hat's reviews.

Connectors and data access

  • Do not pull client store data unprompted. Manual exports are the default: no credentials, no PII. Using a connector (Shopify, etc.) requires Bryan's explicit go-ahead per store.
  • Client hubs link clients to the public CRO methodology. The live paths are docs.dalayon.work/cro/methodology/ and /cro/process/ (note the /cro/ segment). Links to /cro-methodology/ or /cro-process/ return 404. When adding a client's Resources/Links page, use the /cro/... form.