Real-World Walkthroughs

The other guides explain concepts. This one shows them in motion — using the actual process of building the site you're reading right now.

These aren't cleaned-up success stories. They include the wrong turns. And you can verify every one of them: the glossary is in your nav, the homepage is behind you, the analytics are running.

Scenario 1: The Glossary

The task: Build a glossary page. Over 100 terms. Should be useful, not boring.

Round 1 — The Lazy Prompt

Build me a glossary page for the site.

Got back a flat alphabetical list. A-Z, term after term, scrolling forever. Technically correct. Also the most boring page imaginable — a wall of definitions nobody would browse voluntarily.

That's not the AI's fault. "Build me a glossary page" is a nothing prompt. No constraints, no vision, no structure. The AI fell back on the most common pattern in its training data: alphabetical list. Defaults are rarely what you want.

Round 2 — Actually Saying What I Mean

The exact prompt has been lost to a closed chat window, but this is close to what I landed on after those three minutes of thinking:

Build a glossary page for an AI learning site. 110+ terms 
stored in glossary.json. Two view modes: a visual bookshelf 
with colored category spines you can browse, and a compact 
searchable list.

Categories: Core Concepts, Tools, Workflows, Communication, 
Safety, Architecture — each gets a distinct color and icon.
Search bar at top with keyboard navigation. Dark theme. 
Astro page with a React island for the interactive bits.
Key terms (isKey: true in the data) get a badge.

Completely different output. Bookshelf layout, colored sections, toggle between views, search. Not because the AI got smarter between rounds — because I stopped making it guess.

Still had problems though:

• Cards were too tall, wasting space
• Search had no keyboard nav
• Clicking a term opened a whole new page instead of expanding inline

Round 3 — Targeted Fixes

Good structure. Three changes:
1. Cards are too tall — reduce padding, cap descriptions 
   at 2 lines with overflow hidden
2. Search needs keyboard nav: arrows to move, Enter to 
   select, Escape to clear
3. Don't navigate on click — expand the definition inline 
   with related terms as links

Not "make the cards smaller." Not "fix the search." Specific enough that the AI can't misinterpret it.

Three rounds. The glossary you see on this site is the result.

The lesson: The gap between Round 1 and Round 2 was three minutes of thinking. That's it. Three minutes of describing what I actually wanted, instead of hoping the AI would figure it out. The feedback in Round 3 followed the pattern from the feedback loop: what's right → what's wrong → what I want instead.

Scenario 2: The Homepage That Felt Like a Sales Page

The task: The site was built and live. Technically finished. But something was off — the whole thing felt like a paid bootcamp funnel, and that wasn't the intent at all.

This scenario is different from the glossary. That was building something new. This is looking at something you already built and realizing the vibe is wrong — and using AI to diagnose it and fix it.

Round 1 — Naming the Problem

I don't remember the exact phrasing, but the gist was something like: "This feels like I'm trying to sell shit. I'm not selling anything. Look at the whole thing and tell me what's making it feel that way."

That's not a refined prompt. It's a gut feeling thrown at the AI. But it worked — because sometimes the most useful thing you can say to AI is "something is wrong and I can't name it."

The site feels too much like a paid course. I'm not selling 
anything. I need you to look at the whole thing and tell me 
what's making it feel that way — and what to change.

This is an underrated use of AI: asking it to diagnose a feeling. I knew something was wrong. I didn't know exactly what. The AI came back with a breakdown that was, honestly, kind of annoyingly accurate:

Every single element was individually fine. Stacked together, they created a vibe I never intended.

Round 2 — The Fix

The AI proposed a plan: kill the level numbers, rename "Start Here" to "Reading Order," replace the 3-column card grid with a compact two-zone editorial layout, and soften all the CTA copy.

That table is spot on. Let's do it:
- Drop level badges, use category names instead 
  (Foundation, Communication, Strategy, Practice, Management)
- Kill the orange "Start Here" button — rename to "Reading Order"
- Replace the card grid with a compact guide index on the left 
  and featured dispatch on the right
- Rewrite the subtitle — drop "five levels" and replace with 
  "notes, guides, and hard-won strategies"

Round 3 — Fine-Tuning

The structural changes landed well. But the details needed one more pass:

Good. A few more:
- Remove the subtitles under section headers entirely — 
  they're adding words without adding meaning
- The older dispatch cards need a subtle border and 
  author-tinted background, not bare text links
- All dates, reading times, and arrows should be font-mono 
  for that field-manual feel

The lesson: Sometimes the most important prompt isn't "build X." It's "look at X and tell me what's wrong." The AI spotted a pattern across five different elements that I'd been staring at for days without seeing. The fix was structural, not cosmetic — no amount of "make it look less salesy" would have worked. You had to identify the specific patterns creating the feeling.

Scenario 3: The Bug Nobody Saw

The task: The site has a private analytics dashboard — page views, visitors, referral sources. After deployment, the dashboard showed zero. No errors. No warnings. The site loaded fine.

This is the scariest type of bug: a silent failure. Everything looks like it works. Nothing actually does.

The short version: the browser was quietly blocking the analytics script because of a security rule I'd set up. The rule said "only run scripts from these approved sources" — and I'd forgotten to add the analytics service to the list. No error message. No warning. The browser just... didn't load it.

Round 1 — Something's Wrong, But What?

Umami analytics dashboard is showing zero data. The tracking 
script is in the HTML. The site loads fine. No errors in the 
browser console. But the dashboard has nothing — no page views, 
no visitors, zero.

The site uses a Content Security Policy defined in 
middleware.ts. Could the CSP be blocking the script?

I had a hunch it was the CSP — but I didn't know exactly how. That's a perfectly valid place to be. You don't need to know the answer. You just need to give the AI enough context to find it.

Round 2 — Two Lines

The AI checked the middleware file and found it immediately. The script-src directive didn't include the analytics domain. The browser was quietly blocking the tracking script — no error, no warning, just... silence.

The fix was two lines. Add the analytics domain to script-src and connect-src. Done.

I'll be honest — I checked the analytics configuration first. Restarted it. Double-checked the tracking ID. Spent twenty minutes assuming the analytics platform was broken before it occurred to me that the browser itself might be blocking the request. The security-rule hunch came last, not first.

What Made This Dangerous

The site worked for days with this bug. Pages loaded. Users visited. Everything looked fine from the outside. The only way to catch it was to actually open the analytics dashboard and check.

Silent failures always follow the same pattern — something looks correct on the surface but the actual outcome never happened:

The lesson: "It works" means nothing until you verify the actual outcome. Not the absence of errors — the presence of results. Did the data appear? Did the email send? Did the analytics track? Open the thing. Check.

The Pattern Across All Three