Designing Error Messages That Don't Blame the User
Most error copy is written by backend exceptions and shipped unchanged. Here's a working framework for error messages that tell users what happened, what to do next, and whose fault it actually is.
Two new essays per day, written by our team in collaboration with Claude. Original work only. Filter by category to dial in.
Most error copy is written by backend exceptions and shipped unchanged. Here's a working framework for error messages that tell users what happened, what to do next, and whose fault it actually is.
Function calling fails in boring, predictable ways: invented arguments, wrong enums, nested JSON that half-parses. Here's how we design tool schemas so Claude, GPT, and Gemini stop improvising.
Discovery phases rot. They produce PDFs nobody reads and estimates nobody trusts. Here's the paid architecture sprint we run instead, and why clients actually pay for it twice as often.
Keyword cannibalization on a 12k-page site isn't a content problem — it's a clustering problem. Here's the embeddings pipeline we built to merge, redirect, and consolidate pages that were fighting each other in Google.
A field report on dragging Shopify product page LCP from the mid-3s into the low-2s. The usual advice doesn't cut it — here's what actually worked across three merchants in 2025.
A half-applied Terraform run, a stuck DynamoDB lock, and a VPC that almost lost its NAT. Here's how state locking actually fails, and the backend hygiene we wish we'd had six months earlier.
We shipped a design system with CSS variables, theme toggles, and server components. Then half our pages flashed white on reload and the other half rendered the wrong theme entirely. Here's what we learned.
Face ID and fingerprint login look simple until a user updates their OS and gets silently logged out. Here's how we wire biometric auth in React Native without torching trust.
The empty state is the first screen most users actually read. Here's how to design zero-data screens that teach, convert, and stop looking like bugs.
An SOW isn't paperwork. It's the first thing your client reads in anger when a project goes sideways. Here's how we rebuilt ours to actually protect both sides.
Inline hreflang tags break once you hit a dozen locales. Here's the sitemap-driven setup we use on programmatic sites with 40+ locales, including the validation pipeline that catches drift before Google does.
We've shipped WhatsApp commerce flows for stores in Mexico, Colombia, and Brazil. Here's what actually converts, what the Meta sales deck won't tell you, and the integration patterns that survive contact with real customers.
Head sampling is cheap and lies to you. Tail sampling is honest and expensive. Here's the sampling config we actually run in production, and the traces we deliberately throw away.
Server Actions feel like a free lunch until you profile a page that fires twelve of them on mount. Here's how we found a 3-second TTI regression hiding behind what looked like clean React code.
Skeletons aren't a universal upgrade over spinners, and sometimes the best loading state is no loading state at all. Here's how to pick the right one based on wait time, layout stability, and user intent.
Structured output modes from OpenAI, Anthropic, and Google look identical on the slide deck. In production they fail in very different ways. Here's how we handle schemas without getting burned.
Taking equity from a client sounds like free lottery tickets. It isn't. Here's the framework we use to decide when stock beats a wire transfer — and when it's just a discount with extra paperwork.
Most 'content refresh' programmes are vibes. Here's the data pipeline we use to detect decaying URLs, score them by recoverable traffic, and feed a refresh queue writers actually ship against.
We've shipped the same storefront architecture on both Hydrogen and Next.js for Shopify clients. Here's where each one wins, where each one hurts, and the decision tree we now use before writing a single line of code.
We moved 2.4 TB/month of application logs off CloudWatch Logs onto Grafana Cloud. The bill dropped, but not by as much as the slide decks promised, and two things broke in ways we didn't expect.
`revalidateTag` looks like a free lunch until you ship it to a site with 80,000 cached entries. Here's what we learned about Next.js tag invalidation when it stopped being instant.
Focus rings are the most-deleted accessibility feature in modern design systems. Here's how to design ones that keep keyboard users safe without making your brand team cry.
Prompt caching sounds like free money until you read the invoice. Here's how Anthropic, OpenAI, and Gemini caches actually behave, and the patterns that make them pay off.
Most agencies bolt on retainers as glorified bug-fix contracts and burn goodwill within six months. Here's the tiered model we use to convert project clients into monthly revenue that engineers actually want to work on.
Faceted navigation is where programmatic sites quietly burn crawl budget and dilute rankings. Here's the rules engine we use to decide which facet combinations deserve an index, a noindex, or a hard block.
Shopify's checkout.liquid sunset forced every Plus merchant onto Checkout Extensibility. Here's what actually breaks during migration, what doesn't, and the patterns that held up for us in production.
ISR and on-demand revalidation look interchangeable until traffic shifts or a CMS webhook misfires. Here's what we've learned shipping both patterns across e-commerce and content sites.
Edge runtime promised faster cold starts and lower latency. For three of our routes, it delivered the opposite. Here's what we measured, why it happened, and the rules we now use to decide.
Hover is a desktop luxury your mobile users don't have. Here's how to redesign interactions so hidden affordances stop costing you conversions on touch devices.
Most agent failures aren't reasoning failures — they're loop failures. Here's how we design budgets, stop conditions, and fallbacks so our agents don't burn $40 proving they can't book a flight.
Most agencies lose margin not to bad estimates but to changes they never logged as changes. Here's the protocol we use to separate real change requests from scope creep — without wrecking the client relationship.
Keyword-stuffed briefs stopped moving the needle in 2025. Here's the entity-first brief format we now ship to writers, and the small pipeline that generates it from GSC, SERP data, and a graph store.
Open rates on abandonment flows have cratered. Here's what we're building for clients instead — a mix of on-site intent capture, WhatsApp, and server-side retargeting that actually moves revenue.
A quiet NAT Gateway line item grew into the second-largest cost on our AWS bill. Here's how we found it, what was actually causing it, and the three fixes that stuck.
A war story about a Next.js app where middleware ran twice per request, doubled our auth bill, and broke rate limiting. Here's what caused it and how we found it.
Every z-index war starts the same way: someone writes z-index: 9999 to fix a modal, and six months later your tooltip renders behind the cookie banner. Here's how to fix it with tokens.
Most teams pick one model and call it a day. That's how you end up paying $15 per million tokens to classify a support ticket. Here's how to route requests between Claude, GPT, and Gemini without turning your stack into a science project.
Interview loops lose to salary. A paid two-week trial lets agencies compete on work, autonomy, and team quality — the things engineers actually stay for. Here's how we run ours.
GSC's Crawl Stats report is a toy. If you run a programmatic site above 100k URLs, you need raw log analysis. Here's the pipeline we use and the patterns that keep showing up.
Metaobjects quietly replaced half the apps we used to install. Here's how we model a product configurator on Shopify without a custom backend — and where the pattern starts to break.
We moved auth and A/B logic into Vercel Edge Middleware expecting a win. Instead, p75 TTFB got worse. Here's what we measured, why it happened, and the rules we now follow before putting anything on the edge.
`useFormStatus` looks like the obvious way to wire pending states into forms with Server Actions. It is — until you nest it, memoize it, or try to read it from the component that owns the form.
Universal Links on iOS and App Links on Android look simple until you ship. Here's what actually breaks in a React Native + Expo Router app in 2026, and how we debug it without burning a release.
Toasts feel like the default confirmation pattern, but they fail silently for the users who need them most. Here's when to use them, when to kill them, and what to reach for instead.
Everyone's chasing fancy chunking strategies, but most production RAG systems win or lose on boring decisions: boundaries, overlap, and metadata. Here's what we've seen hold up.
We killed our four-stage technical interview and replaced it with a paid trial week. Here's exactly how it works, what it costs, and why our offer-acceptance rate nearly doubled.
Rule-based internal linking on programmatic sites looks tidy in code review and dies in production. Here's how we rebuilt ours as a graph problem — and what it did to crawl depth and rankings.
A war story about a Shopify storefront that quietly dropped line items under load, why the Cart Ajax API was the villain, and the debounce pattern we now ship by default.
Next.js 15 streams metadata by default so pages render faster, but social scrapers don't wait around. Here's how we tracked down stale Twitter cards and the pattern we settled on in production.
Hermes is the default React Native engine in 2026, and for most apps that's the right call. But we still ship a few projects on JavaScriptCore — here's exactly when and why.
Validation on every keystroke is hostile. Validation only on submit is lazy. Here's a timing model for form errors that respects users and still catches mistakes before they hurt.
Million-token context windows look like they kill RAG. They don't. Here's what actually happens to accuracy, latency, and your bill when you stop retrieving and start stuffing.
Discounted pilots feel like smart business development. Most of them aren't. Here's how to structure a first engagement that actually leads to a profitable second one — or kill the deal early.
INP replaced FID in 2024 and by 2026 it's the Core Web Vital most programmatic sites still fail. Here's the template-level engineering that fixed it for us.
Most Shopify stores we inherit are running 15+ apps, half of which inject scripts into every page load. Here's the audit framework we use to decide what stays, what gets replaced, and what gets ripped out.
We spent a quarter chasing Cloud Run cold starts for a Node + Python API. Min instances helped, but the real win came from four less obvious changes. Here's the ranked list of what moved p99.
React 19's `use` hook lets you unwrap promises inside client components. It's elegant until a parent re-renders and your tab goes blank. Here's what's actually happening and how to not get burned.
Background execution is where cross-platform promises go to die. Here's what Expo, iOS, and Android actually let you run in 2026 — and the patterns that survive both OS schedulers and app review.
Disabling a submit button feels polite and safe. It's usually neither. Here's why the greyed-out button pattern breaks accessibility, hides your real errors, and what to ship instead.
Pure vector search looks magical in demos and then fails on product SKUs, error codes, and names. Here's how we wire BM25 and embeddings together without regretting it six months in.