Debugging in Shakespeare

When building complex applications with Shakespeare, things don't always work as expected. This guide teaches you systematic debugging approaches that go beyond basic prompting, helping you identify issues, gather evidence, and communicate problems effectively to get your projects back on track.

1. Debugging in Shakespeare

Effective debugging with Shakespeare starts with understanding its capabilities and limitations. Shakespeare is a powerful AI assistant for development, but knowing what it can and cannot see is crucial for getting the help you need.

What Shakespeare Can and Cannot See

When Shakespeare cannot see something on it's own, it's up to you to provide that information to the AI so it can use it to help you solve the bug.

How to Talk to Shakespeare About Debugging

Use the "Expectation vs. Reality" format:

• What you expect to happen: "When I click the submit button, the form should create a nostr event and submit it to the relays, then show a success message"
• What actually happens: "The button click does nothing, I dont see any nostr event coming through, nor a success message"

Choosing the Right AI Model for Debugging

Shakespeare gives you the freedom to choose your model, but what you pay for is what you get! If you choose a cheap model, you can expect cheap results. Model selection significantly impacts debugging effectiveness, especially for complex applications. We highly recommend using advanced models for debugging and complex applications.

2. The Debug Hierarchy

Effective debugging follows a systematic approach. Instead of randomly trying different solutions, follow this hierarchy to identify and resolve issues efficiently.

The Four-Step Debug Process:

1. Gather Evidence - Collect error messages, console logs, and network requests
2. Isolate the Problem - Identify the specific component, function, or interaction causing issues
3. Provide Context - Document the environment, data state, and user actions that trigger the problem
4. Test Systematically - Make incremental changes with rollback capability

This structured approach ensures you don't waste time on symptoms while missing the root cause. Start with evidence, not assumptions.

3. Checking for errors in Shakespeare

Shakespeare now has the ability to see console errors directly! When you're experiencing issues with your project, the first step is to check for errors using Shakespeare's built-in debugging tools. This saves you time and provides immediate insight into what's going wrong.

How to check for errors in Shakespeare:

1. Look for the bug icon: In the top right of the preview pane, you'll see a bug icon. Click it to view console errors.
2. Review the errors: Any JavaScript errors, warnings, or console messages will be displayed
3. Copy and paste: You can copy these errors and paste them directly into the chat with Shakespeare

The bug icon in the top right of the preview pane gives you instant access to console errors.

Meet Quilly, the Shakespeare mascot! From time to time, you may see Quilly pop up with useful information about various errors. We're still working to improve this feature, but it's a great way to get quick tips and context when Shakespeare detects common issues.

Quilly provides helpful tips and error messages.

4. Opening Developer Tools

Developer tools are your debugging microscope. Every modern browser includes powerful debugging capabilities that reveal what's happening behind the scenes in your Shakespeare application.

Quick Access Methods (Desktop Only):

• Chrome/Edge: Press F12 or Ctrl+Shift+I (Windows/Linux) / Cmd+Option+I (Mac)
• Firefox: Press F12 or Ctrl+Shift+I (Windows/Linux) / Cmd+Option+I (Mac)
• Safari: Press Cmd+Option+I (Mac) - Enable Developer menu first in Preferences
• Alternative: Right-click on page → "Inspect" or "Inspect Element"

Essential DevTools Tabs:

• Console: Error messages, warnings, and custom log output
• Network: API requests, response codes, and loading times
• Elements: HTML structure and CSS styling inspection
• Sources: JavaScript debugging with breakpoints
• Performance: Load times, memory usage, and rendering analysis

5. Gathering Essential Evidence

Good debugging starts with thorough evidence collection. The more specific information you provide to Shakespeare, the more targeted and effective the solutions will be.

Critical Information to Collect:

• Console Output: Copy exact error messages, warnings, and stack traces
• Browser DevTools: Network tab failures, React DevTools component state
• User Journey: Step-by-step actions that trigger the issue
• Environment Details: Browser version, screen size, data conditions
• Expected vs. Actual: What should happen vs. what actually happens

Document the reproduction steps clearly. If you can't reliably reproduce the issue, Shakespeare can't reliably fix it.

6. Console Error Debugging

Console errors are your first clue. Most JavaScript issues surface in the browser console with specific error messages that point directly to the problem. When reporting console errors to Shakespeare, copy/paste the entire console output to Shakespeare.

7. Debugging Nostr Events

Nostr applications require specialized debugging techniques. When building decentralized applications with Shakespeare, you need to understand what events are being created, signed, and broadcast to the network.

Essential Nostr Debugging Tools:

• Alby Extension (Paranoid Mode): Review every event before signing and broadcasting
• Nostr DevTools: Browser extensions that show real-time event streams
• Relay Logs: Monitor which relays accept or reject your events
• Event Validation: Verify event structure, signatures, and required fields
• Network Inspection: Track WebSocket connections to Nostr relays

Use Alby's paranoid mode during development to see exactly what events your application creates before they're sent to relays. This prevents broadcasting malformed or test events to the live network.

Common Nostr Event Issues:

• Invalid Event Structure: Missing required fields (id, pubkey, created_at, kind, tags, content, sig)
• Incorrect Event Kind: Using wrong kind number for the intended functionality
• Malformed Tags: Invalid tag arrays or missing required tag elements
• Signature Problems: Events not properly signed or signature verification failures
• Relay Rejection: Events rejected by relays due to policy or validation issues

Advanced Nostr Debugging Techniques:

• Event Validation: Use nostr-tools library to validate event structure before signing
• Relay Testing: Test events against multiple relays to identify relay-specific issues
• Event History: Track event creation, signing, and broadcast timeline
• Tag Analysis: Verify tag arrays contain correct references (e tags, p tags, etc.)
• Content Inspection: Ensure event content is properly formatted JSON when required

8. Advanced: Meta-Debugging

Meta-debugging is debugging your debugging process. When regular debugging techniques aren't working, or when you've spent too many credits without progress, it's time to step back and analyze your approach itself.

Meta-debugging involves asking Shakespeare to examine your debugging strategy, identify patterns in failed attempts, and suggest more efficient approaches. This is particularly powerful because Shakespeare can review your entire chat history and spot inefficiencies you might miss.

Forward Meta-Debugging: When You're Stuck

Use this when a bug persists despite multiple fix attempts. Instead of trying yet another random solution, ask Shakespeare to analyze what you've already tried and create a systematic plan.

Key phrases for forward meta-debugging:

• "Analyze what we've already tried and create a new plan"
• "What patterns do you see in our failed attempts?"
• "What fundamental assumption might we be missing?"
• "Create a systematic debugging plan based on our chat history"

Reverse Meta-Debugging: Learning from Inefficiency

Use this after solving a particularly bug to improve your future debugging skills. Ask Shakespeare to review your debugging session and identify how you could have been more efficient.

Key phrases for reverse meta-debugging:

• "Analyze our chat and tell me how I can be more efficient next time"
• "What should I have provided earlier to solve this faster?"
• "Which steps in our debugging process were unnecessary?"
• "What debugging pattern should I follow for similar issues?"

Debugging is a skill that improves with practice. The more systematically you approach problems, the faster you'll identify solutions. Remember: Shakespeare can only help you as effectively as you can describe the problem. Master these debugging techniques, and you'll transform from someone who gets stuck on issues to someone who solves them quickly and confidently.