Section 5: Debugging and Optimization – When Things Go Wrong

The path to building with AI isn’t always smooth. Things may go wrong, but don’t panic. Using the methodology we’ll discuss here, you’ll have a clear process to discover and fix every problem. These principles will help you find the source of the problem and communicate a precise solution to the AI. After all, the difference between frustration and flow is knowing how to fix problems quickly.

This section will turn you into a troubleshooting expert by teaching you not just what to do, but how to think when challenges arise.

Using the AI Assistant for Targeted Help

Before you dive into fixing problems, here’s the most powerful debugging strategy: let the AI Assistant teach you the technical language you need. Most troubleshooting frustration comes from knowing what you want but not knowing how to ask for it. The Assistant bridges that gap.

Why This Approach Works

Websites are built with CSS (the styling language) and HTML (the structure). When you want to change spacing, colors, or layouts, the most reliable way is referencing specific CSS properties like margin, padding, or max-width. But you don’t need to know these – the Assistant translates your plain English into technical terms the Agent understands.

The Assistant’s Role: to analyze your code, identify the issue, and give you the exact prompt to use with the Agent. Think of it as having a senior developer reviewing your work and writing the fix for you to execute.

How to Use This Strategy

When you’re stuck, describe the problem to the Assistant in plain language:

“Hey Assistant, the testimonial section on my homepage doesn’t display properly on iPad. What should I tell the Agent to fix this?”

Example Assistant Response:

“The testimonial section is likely breaking on iPad because the CSS grid isn’t responsive at that breakpoint. Tell the Agent:

‘Fix the testimonial section for tablet screens (768px – 1024px). Change the grid to display 2 columns instead of 3, and ensure proper spacing between cards. Add these CSS properties to the testimonial container: grid-template-columns: repeat(2, 1fr) and gap: 20px for screens between 768px and 1024px.’

This will make the section responsive on iPad while maintaining the 3-column layout on desktop.”

What You’re Learning

Notice how the Assistant taught you:

• The problem (CSS grid not responsive at iPad breakpoint)
• The solution (change to 2 columns at that screen size)
• The technical terms (grid-template-columns, repeat(), breakpoints)
• The exact CSS properties to use

Do this a few times, and you’ll start recognizing patterns. You’ll learn that spacing issues involve margins and padding. Layout problems often involve width, max-width, or grid. Color inconsistencies trace back to CSS variables. Eventually, you might not need the Assistant anymore – you’ll speak the language fluently enough to prompt the Agent directly.

This two-step process – understand the problem with the Assistant, then execute the fix with the Agent – is how professionals troubleshoot efficiently.

Remember the Agent builds, but the Assistant guides.

Navigating the Conversation: Agent vs. Assistant

The Agent and Assistant have different strengths, and knowing when to pivot between them will save you hours.

Ask the Agent when:

• You know exactly what you want have the technical language ready (thanks to the Assistant’s guidance)
• You’re making progress, even slowly, and the AI understands the context
• You know exactly what you want it to do (e.g., “Add a new section,” “Make this button bigger”).

Pivot to the Assistant when…

• The Agent seems confused, and every fix creates new problems.
• You’ve made a few attempts at a fix, but nothing is working.
• You need a new strategy or don’t know the technical language for what you want.
• You want to learn the “right way” to approach a problem

5 Principles of Professional Troubleshooting

Let me save you hours by teaching you the core principles that solve 80% of problems. Each principle includes real examples so you can see exactly how to apply it.

Principle 1: Think Responsively

The core idea: Websites exist on hundreds of different screen sizes. A fix that works on your laptop might break on phones, tablets, or ultra-wide monitors. Professional troubleshooting accounts for this from the start.

Common problem: Your navigation menu looks perfect on desktop but is a disaster on mobile – the hamburger icon doesn’t work, or menu items overflow the screen.
Why it happens: The code isn’t adapting to different screen widths (called “breakpoints” in web design).

Why this works: You specified the breakpoint (768px), described the desired behavior at each screen size, and gave complete requirements. The Agent knows exactly what responsive behavior you need.

Principle 2: Address the Root

The core idea: Many styling problems stem from global settings that control the entire site. Trying to fix individual instances won’t work if the issue lives at the root level.

Common problem: You change a color or font on one element, but it doesn’t stick, or the change only happens on one page instead of site-wide.

Why it happens: The styling is defined in root-level CSS variables – global settings that override individual element styles.

Why this works: You identified that individual fixes aren’t working, then directed the Agent to the source – the root-level styles that control everything.

Principle 3: Hone Visual Precision

The core idea: “Make it look better” is subjective. Professionals use specific measurements to create consistent, intentional spacing.

Common problem: Sections have inconsistent spacing, making your site look amateur, or mysterious white space appears on mobile, causing horizontal scrolling.

Why it happens: Elements use different spacing values, or an element is wider than the screen.

Why this works: Specific pixel values create consistency. The debugging technique helps you find problems visually before fixing them precisely.

Principle 4: Maintain Consistency

The core idea: Your site should feel like one cohesive experience. When new pages or sections look different, it breaks that professional polish.

Common problem: You add a new page, but it looks completely different from the rest of your site. The header is missing, fonts are wrong, or spacing doesn’t match.

Why it happens: The Agent treated the new page as a blank canvas instead of inheriting your site’s existing design system.

Why this works: You explicitly told the Agent to reuse existing components and styles rather than creating new ones.

Principle 5: Target with Precision

The core idea: Describing elements (“the green button in the second section”) is ambiguous. The Selector Tool lets you point directly at what needs fixing.

Common problem: You’ve tried several prompts, but a specific button, image, or text block won’t behave.

Why it happens: The Agent is guessing which element you mean. With multiple similar elements, it might fix the wrong one.

The Power User Technique:

1. Click the Selector Tool.
2. Hover over the element to see its boundaries.
3. Click the element to select it.
4. Now, tell the AI Agent something relevant to your desired outcome. For instance: “The selected element is too far from the text above it. Please reduce the <code> to 10px.”

Why this works: No ambiguity. You’re pointing directly at the element, and the Agent sees exactly what you’re targeting.

The Complexity Roadmap

Sometimes, despite all troubleshooting, something won’t work. The AI may have introduced a small change in the code that’s causing a cascade of problems. Here’s your roadmap for when things get truly complex:

1. Revert to the last working version. If a series of prompts aren’t working, don’t continue digging. Go back to your last successful working version of the site using Replit’s Checkpoint feature. This isolates the problem to the current conversation and saves you from a tangled mess of code.
2. Explore deeper. If you’re still stuck, it’s time to become a detective. Websites are built in layers (pages, sections, blocks, and more). Begin looking for what other layers of the website may be causing the issue.
3. Escalate to Replit support. If you’re stuck after trying these troubleshooting steps, you can visit replit.com/help to access community forums (fastest for coding issues), Discord for real-time help, or submit a support ticket for account or billing problems. Include your project link, a clear problem description, and what you’ve already tried.

Quality Check Protocols

Each change you make builds on the previous one so quality check your work as you go – otherwise you could be building on a broken foundation and end up with a site full of compounding problems.

Here are the professional protocols:

The single change rule (recommended):

1. Make one modification.
2. Check desktop view.
3. Check mobile view.
4. Verify the change worked.
5. Note any side effects.
6. Only then make the next change.

The batch update approach: If you have multiple similar changes, it’s time-efficient to do them in a batch. Here’s an example prompt that helps the AI maintain focus and avoids cascading errors:

Please make these styling updates one at a time, confirming each works before moving to the next:

1. [First change]
2. [Second change]
3. [Third change]

Just note that this may lead to either issues in the code or the Agent only doing a few of the requested changes rather than all of them. Be extra cautious if you choose this route.

The Professional Launch Checklist

Before declaring your site ready, run through this expanded checklist. It’s a quick way to catch the little issues that make a site look amateur.

• Visual consistency:
  • Logo consistent size across all pages
  • Colors match brand guidelines exactly
  • Typography hierarchy is clear (H1 > H2 > H3 > Body)
  • All images are appropriate quality and size
• Functionality testing:
  • Every link works
  • Forms submit successfully
  • All buttons work
• Mobile optimization:
  • Tested on your device
  • Text is readable without zooming in
  • No horizontal scrolling

Accessing and Editing Files Directly

Sometimes, you may wish to see under the hood. Here’s how:

Viewing your files: In Replit, click the files icon ( ) (right sidebar). You’ll see your entire project structure:

• index.html – Your homepage
• styles.css – Your styling
• script.js – Your interactions
• Other pages and components

When to look at code:

• To understand the structure
• To copy specific sections for reuse
• To learn how things work

Avoid editing code directly unless you know what you’re doing! If you don’t know HTML, CSS, or JavaScript, always make changes through the AI Agent. Direct code edits can break things in unexpected ways.

You’re Nearly There – Let’s Get Your Site Live

And there we have it! Congrats! Your site is now optimized and looks professional. Now it’s time for the exciting part – making it live on the real internet with your very own domain.

In the next section we’ll talk through everything from Search Engine Optimization to hosting. It’s time to get technical.