Skip to main content
Use Chat mode to investigate errors, run site audits, handle fragile updates safely, and resolve persistent issues systematically.
Improving WordPress sites with AI is fast and rewarding – until something goes wrong. Errors, unexpected behaviors, or “the AI did something weird” moments are part of the process. This guide will help you navigate AI-based debugging workflows in Kintsu.ai. We’ll cover how to quickly fix simple issues, strategies for tougher bugs, using Kintsu.ai’s chat for debugging, and even prompt recipes to systematically squash bugs. Debugging with an AI assistant is a new skill, but with structure and the right prompts, you can resolve problems efficiently and even turn them into learning opportunities.

​
Advanced debugging prompts

Sometimes you need a heavy-duty prompt to dig into a problem or review your site’s health. Here are some structured prompt examples for deep debugging or optimization scenarios. These can be used in Chat mode to get a thorough analysis without immediately changing code.

​
Full system review (site audit)

If your WordPress site has grown complex or you suspect there are structural issues, a full site audit prompt can be useful. This asks the AI to analyze the entire project for cleanliness, correct architecture, and any misplaced code. It’s like asking “Is everything organized the way it should be?” Example prompt – site audit: 
Perform a comprehensive **audit of the WordPress site structure** to check if the architecture is clean, modular, and optimized:

- Identify any theme files, components, or logic that are in the wrong place or could be better organized. Are there any instances of code that don't belong in their current file (misplaced logic)?
- Evaluate if we have a clear separation of concerns (e.g., presentation vs functionality vs data handling). Point out any overly coupled sections.
- Highlight any areas that are overly complex or not following WordPress best practices.
- Provide a report with specific recommendations to improve structure and maintainability, **without making any changes yet**. 

Break down the suggestions into an ordered list of steps we could take, from most critical to optional enhancements.

*(This is a read-only analysis; do not modify the site during this audit.)*
This prompt is long, but it directs the AI to act like a code reviewer or architect. We’ve asked it to find mislocated code, check modularity, and even prioritize the fixes. The AI might respond with something like:
  • “1. Separate custom functions from theme templates: The header.php is directly making database queries. Suggestion: move data fetching to functions.php or a dedicated include to keep templates focused on presentation.
  • 2. Reduce coupling in navigation logic: The mobile menu toggle is updating both DOM and inline styles directly. This should be refactored to use proper CSS classes for better maintainability.
  • 3. Organize utility functions: There are helper functions scattered across multiple template files that would be better placed in a dedicated inc/helpers.php file.
  • …”
Each point might come with explanation and maybe references to specific files. Such a report helps you see the forest for the trees. It’s especially useful if you’ve been focusing on one section at a time and haven’t looked at the overall structure in a while.
Avoid generic and broad prompts
Nothing works, fix it!
Make your prompts more detailed and specific
The homepage hero section has gone blank after the last edit.
Can you check what happened and identify the cause?
After getting this output, you can decide which refactoring tasks to tackle (maybe even prompt the AI to implement some of those recommendations one by one).

​
Safe approach for fragile updates

When you know the area you’re changing is delicate (maybe a complex WooCommerce checkout flow or a core navigation system), it’s wise to prepend a cautionary guideline in your prompt. This doesn’t find bugs per se, but it helps prevent them by telling the AI to be extra careful. Example prompt – fragile update guidance: 
The next change is in a **critical part of the site**, so proceed with **utmost caution**. 

- Carefully examine all related code and dependencies *before* making changes.
- **Avoid any modifications** to unrelated components or files.
- If there's any uncertainty, pause and explain your thought process before continuing.
- Ensure thorough testing after the change to confirm nothing else is affected.

**Task:** Update the WooCommerce checkout flow to add a gift message field without breaking the existing payment or shipping functionality.

*(Be extremely careful and double-check each step during implementation.)*
By including these guidelines and warnings, you’re basically setting the AI’s “mindset” to be cautious. The AI might then take a more measured approach, e.g., first explaining what it will do, or implementing the addition while explicitly noting that it left existing functionality intact. This strategy is useful for fragile sections: checkout flows, payment processing, user authentication, membership areas – anything where a small mistake can break a lot. It’s a preemptive debugging measure.

​
Performance optimization check

If your WordPress site works correctly but is slow or resource-heavy, you can use a prompt to have the AI analyze performance. This might involve reviewing database queries, looking at rendering inefficiencies, or suggesting optimizations (caching, asset optimization, etc.). Example prompt – performance audit: 
Our WordPress site is functional but seems **sluggish**. Please **analyze the site for performance bottlenecks** and suggest optimizations:

- Check for any unnecessary database queries (e.g., duplicate queries or N+1 query patterns in loops).
- Identify any JavaScript or CSS that might be blocking rendering or loading unnecessarily.
- Look at our use of images and assets: are there any unoptimized images or large files affecting load time?
- Suggest improvements like caching frequently used data, lazy loading images, deferring non-critical scripts, and any other ways to speed up the site.

Provide the analysis and recommendations in a list. Do not make changes yet – just tell us what to improve for better performance.
Running this in Chat mode will give you a diagnostic report. The AI might say for example:
  • “Database queries: The blog archive is running a separate query for author data on each post. This could be improved by eager loading author data in the main query.
  • Render blocking: There are 3 CSS files and 5 JS files loading in the header. Consider combining and deferring non-critical assets.
  • Images: Noticed several hero images over 1MB. Compress these or use WebP format for faster loading.
  • Caching: No object caching detected. Consider implementing Redis or Memcached for database query caching.
  • …”
Each suggestion comes from common WordPress performance best practices. You can then decide which ones to implement.

​
Handling persistent errors

What about errors that just won’t go away or keep coming back in slight variations? This can happen if the root cause isn’t addressed. Here’s a strategy:
  • Ask the AI what it has tried already. Use: “What solutions have we tried so far for this error?” The AI can list the attempts, which helps you avoid repeating the same fixes.
  • Have the AI explain the error in simple terms. “Explain in simple terms why this error occurs.” This can reveal if the AI (and you) truly understand it.
  • Consider an alternate approach. Ask: “Given this error keeps happening, can we try a different approach to achieve the goal?” The AI might suggest a different implementation strategy that bypasses the problematic area.
  • Revert and replay. In worst-case scenarios, you might roll back a few steps. Then proceed with smaller changes.
Finally, if a specific component is “dead” (not working at all, no matter what), isolate it. Create a fresh minimal version of that component via prompt to see if it works, then slowly integrate it back. This is akin to turning things off and on again, but with code. Throughout all this, maintain a dialogue with the AI. Treat it like a collaborator: “We fixed X but now Y is acting up. What’s the relationship between X and Y? Could the fix have caused Y’s issue?”

​
Sample debugging flows

To cement these ideas, let’s walk through common debugging scenarios with example flows:

​
The “stuck in error loop”

You prompted something complex, and now the site won’t load properly, and the fix failed twice. Flow:
1

Switch to Chat mode.

2

Ask: 'What is the root cause of this error?'

3

The AI explains it's a PHP syntax error in a template file.

4

Ask: 'Show me the relevant code and what's expected.'

5

AI shows that a closing bracket was removed during the last edit.

6

Prompt: 'Restore the missing bracket in the header template and verify the syntax is correct.'

7

Run that prompt, site loads successfully.

8

If it didn't, go back and ask 'What else could cause this?'

Throughout, you specifically described the error and had the AI confirm its understanding, rather than just blindly hitting fix repeatedly.

​
The “feature not working right”

You added a contact form, but submissions aren’t being received. Flow:
1

No visible error shows, so you ask in Chat: 'The contact form isn't working – I expected an email when someone submits, but nothing arrives. How can we debug this?'

2

AI suggests checking if the form handler is processing and if the email function has any errors.

3

You check the server logs and see a mail configuration error.

4

Show this to the AI: 'The log says SMTP connection failed.'

5

AI figures out the SMTP settings aren't configured or the credentials are incorrect.

6

You fix the SMTP settings in WordPress (wp-config or plugin settings), or prompt to use a different mail method.

By describing what you expect (an email) and what happened (nothing, with a log snippet), the AI was able to guide the investigation.

​
The “UI element disappeared”

You refactored something and now a whole section of the page is just gone. Flow:
1

Tell the AI: 'The services section is no longer showing up at all. It was working before the last edit.'

2

The AI might check if the section is still being included or if a template part is missing.

Perhaps it realizes the refactor removed an include statement or changed a conditional that hides the section.
3

The AI could walk through possibilities: 'Is the template part still being called? Let's check if the section has a conditional that might be false now.'

4

You discover the section was wrapped in a conditional that's no longer true.

Prompt: “Restore the services section by fixing the conditional or removing the wrapper that’s hiding it.” Problem solved.
In this flow, the key was to notice the component was completely gone and communicate that.
Using browser dev tools and console logs
The site is showing a white screen.
Here's the error from the browser console:

Uncaught TypeError: Cannot read property 'querySelector' of null
    at main.js:42:15
In all these cases, communication and incremental steps are your friends. Use the AI’s strength in recalling details and analyzing errors. Use your strength in steering the process.

​
Root cause analysis, rollback, and progressive enhancement

A few final pieces of advice:

​
Root cause vs. symptom

Always ask “why did this happen?” not just “what to do now?”. The AI can help find the root cause so that when you fix something, it stays fixed.
I see you fixed the null error by adding a check, but why was it null in the first place? Can we address that cause?
This leads to more robust solutions.

​
Rollback wisely

Don’t hesitate to roll back if the site has become too tangled by a series of bad fixes. It’s often faster to rewind and try a different approach. If you do rollback, let the AI know:
I reverted the site to before the navigation changes. Let’s implement it again, but more carefully this time.
This way, the AI has context that changes were undone.

​
Progressive enhancement

When adding new features (especially complex ones), build them in small, testable increments. This isn’t just a prompting tip – it’s a development philosophy that pairs well with AI. If something breaks, you know exactly which small step caused it.
  1. Add failing test cases.
  2. Isolate the problem and analyze dependencies.
  3. Document findings before applying fixes.
Here's the failing console log. Analyze the error, investigate the dependencies, and suggest a solution after understanding what's connected.

​
Document as you go

It’s helpful to keep notes (or even ask the AI to summarize what was done after a session). After resolving a tough bug, you might prompt:
Summarize what the issue was and how we fixed it.
The AI’s summary can be saved for future reference. This is great for future you, or anyone else working on the site.

​
Know when to ask for human help

Sometimes, despite all efforts, you might hit a wall. The Kintsu.ai community and support are there for you. Use the AI to gather as much info as possible first (so you can provide details), and then reach out if needed.

​
Community debugging guidebook

These debugging principles apply to WordPress site improvements:
When fixing errors, focus exclusively on the relevant code sections without modifying unrelated functioning parts. Analyze the error message and trace it to its source. Implement targeted fixes that address the specific issue while maintaining compatibility with the existing site. Before confirming any solution, validate that it resolves the original problem without introducing new bugs. Always preserve working functionality.
When modifying existing code, use a surgical approach that changes only what’s necessary. Preserve coding patterns and architectural decisions present in the theme or plugin. Before suggesting changes, analyze dependencies to ensure modifications won’t break existing functionality. Present changes as minimal diffs rather than complete rewrites.
Before suggesting new database structures, thoroughly examine the existing schema to identify tables already present. Leverage existing tables whenever possible rather than duplicating data models. When modifications to the database are necessary, ensure they’re compatible with existing queries. Consider migration strategies for schema changes that preserve existing data.
Approach every issue with a comprehensive diagnostic process. Begin by gathering all relevant information through careful examination of error messages, logs, and site behavior. Form multiple hypotheses about potential causes rather than jumping to conclusions. Test each hypothesis methodically until the root cause is identified.
Before confirming any solution, implement a rigorous verification process. Test the solution against the original issue to confirm it resolves the problem. Check for unintended side effects in related functionality. Ensure performance isn’t negatively impacted. Verify compatibility with different browsers and devices.
Maintain consistency with the existing theme or plugin in terms of style, patterns, and approaches. Analyze the code to identify naming conventions, formatting preferences, and architectural patterns. Follow these established patterns when implementing new features or fixes.
When adding new features, build upon the existing architecture rather than introducing completely new paradigms. Identify extension points in the current design and leverage them for new functionality. Focus on backward compatibility to ensure existing features continue to work as expected.
Provide clear, concise explanations for all changes and recommendations. Explain not just what changes are being made, but why they’re necessary and how they work. Document any assumptions or dependencies involved in the solution. Include comments in code when introducing complex logic.
Recognize when solutions might introduce technical debt and be transparent about these trade-offs. When time constraints necessitate less-than-ideal solutions, clearly identify what aspects would benefit from future refactoring. Distinguish between quick fixes and proper solutions.
Before creating new elements, conduct a thorough inventory of existing elements. Search for similar functionality. Identify opportunities to reuse or extend existing components rather than creating duplicates. Consider creating abstracted components that can be reused with different data or configurations.
Actively identify and remove unused code rather than letting it accumulate. When replacing functionality, cleanly remove the old implementation instead of simply commenting it out. Verify code is truly unused before deletion by checking for references throughout the site.
Treat working features as locked systems that require explicit permission to modify. Never remove or substantially alter features that are currently operational without explicit direction. When errors occur in one area, avoid making “just in case” changes to unrelated working components.
When encountering complex errors, resist the temptation to apply immediate fixes without deeper understanding. Take a deliberate step back to examine the problem from multiple perspectives. Consider fundamentally different approaches rather than minor variations of the same strategy.
Maintain strict adherence to the established design system and color palette. Before creating new UI components, study existing ones to understand the visual language. When implementing new interfaces, reuse existing patterns rather than creating visual variations.
Monitor site performance proactively. Review query caching strategies to minimize unnecessary database calls. Analyze asset loading patterns for potential bottlenecks. Implement virtualization for long lists and paginate large data sets. Focus on metrics that directly impact user experience.
Implement a comprehensive error handling strategy that maintains site stability while providing meaningful feedback. Design graceful degradation patterns where sections can continue functioning with limited data. Provide clear, user-friendly error messages.