Some cost hours, some cost days, one cost me three days of lost revenue. If this chapter saves you even one mistake, the whole guide was worth reading.
None of these are in any tutorial. They're all things I learned by making the mistake first and fixing it second. If this chapter saves you even one of these, the whole guide was worth reading.
Running grep -c before a cp command will silently kill the copy if the grep returns zero matches. The exit code cascades and your file never gets copied. Always run cp as a standalone command. This one cost me a day of debugging.
Supabase has a silent 1,000-row cap on SELECT queries. If you're running aggregates — COUNT, SUM, AVG — on a table with more than 1,000 rows and you're not using server-side aggregation, your numbers are wrong. Always use COUNT, GROUP BY, and other aggregation functions. Never pull raw rows and count them in application code.
AI will confidently write SQL queries using column names that sound right but don't exist in your database. user_id vs memberstack_id. created_at vs created_on. One wrong column name means a query that returns nothing — or worse, a migration that fails silently. Check actual column names before writing any query.
Every time I've skipped the sandbox and pushed directly to production, I've regretted it. Every single time. The fix is always harder than the sandbox test would have been. There are no exceptions to this rule, no matter how small the change seems.
For voice AI products, your voice provider is the source of truth for agent IDs and voice IDs. Your database follows the provider, never the other way around. If there's a mismatch between your database and ElevenLabs, the ElevenLabs value is correct. This principle applies to any third-party integration — the external service is the authority.
If you're building any kind of educational product with multiple-choice components, the quality of your wrong answers matters as much as the quality of your right answers. A distractor that's technically correct but was intended to be wrong is a product failure, not just a content issue. Users lose trust when your "wrong" answers are actually right.
If your product includes narrative content — stories, characters, worlds — never reference the product itself from within the narrative. A character saying "download the app" destroys the fiction. The narrative is its own world. Product references belong outside it.
Systems that show up for your users are better than systems that require your users to show up. Automated check-ins, character-initiated messages, progress updates that arrive without the user asking — these create the feeling that your product cares about them. Streak mechanics demand that the user serves the app. Flip that dynamic.
NOTE: The most expensive lessons aren't the ones that break something. They're the ones that waste your time building something wrong. Thirty minutes of alignment before a task saves three hours of debugging after it. Every time.