Debug Mode and Ask Mode

SuperBuilder includes two specialized execution modes that change how the AI agent works: Debug Mode for tracing and fixing hard bugs, and Ask Mode for read-only exploration of your codebase.

Debug Mode

Debug Mode is designed for bugs that resist straightforward fixing. Instead of jumping straight to a solution, the agent takes a hypothesis-driven approach: it adds targeted logging, runs the code, observes the behavior, then uses the output to confirm or refute its hypothesis before making any changes.

How Debug Mode Works

1. You describe the bug — what's happening vs what you expect
2. The agent reads the relevant code and forms a hypothesis about the cause
3. The agent adds targeted console.log, print, or language-appropriate logging statements to test the hypothesis
4. The agent runs the code (or instructs you how to trigger the bug path)
5. The agent reads the log output and either confirms its hypothesis or revises it
6. Once the cause is confirmed, the agent removes the debug logging and applies the real fix

This approach prevents agents from making changes based on guesswork. The logging creates a feedback loop — the agent sees real runtime behavior instead of reasoning from static code alone.

When to Use Debug Mode

Intermittent bugs — bugs that don't always reproduce from code reading alone. The agent adds logging to capture the state when it does happen.

Race conditions — timing-dependent bugs where the order of operations matters. Logging timestamps and thread states makes them visible.

Unexpected data — when the bug is caused by data you didn't expect (a null, an empty string, an out-of-range value). Logging the actual values at runtime surfaces the issue.

Complex state bugs — when many pieces of state interact and the bug only appears in a specific combination. Systematic logging narrows it down.

Third-party integrations — when the bug involves an external API or library, logging the raw request and response makes the actual behavior visible.

What Debug Mode Doesn't Do

Debug Mode doesn't try to reproduce the bug in isolation or write unit tests for it — that's a separate task. It focuses on tracing the live execution path to confirm the cause, then fixing it once confirmed.

Ask Mode

Ask Mode is a read-only exploration mode. The agent can read any file in your codebase, navigate the directory structure, search for patterns, and answer your questions — but it makes zero changes to any file.

When to Use Ask Mode

Onboarding — when you're new to a codebase and want to understand how it works. "How does authentication work in this project?" "Where does the pricing calculation happen?" "What happens when a user submits this form?"

Code review prep — before reviewing a PR, ask the agent to explain the changes and their impact. Get the context you need before you look at the diff.

Architecture understanding — "What are the main services in this repo and how do they communicate?" "What's the data flow from the API to the database?"

Debugging investigation — before changing anything, ask the agent to trace the likely cause. "Why might this be returning null?" "What could cause this race condition?" Get the analysis without risking any changes.

Refactor planning — "What would break if I renamed this function?" "How many places call this API?" "What's the blast radius of changing this interface?"

Ask Mode Safety

In Ask Mode, no file writes happen — ever. The agent literally cannot create, edit, or delete files when this mode is active. This makes it safe to point at any codebase:

• Production code where accidental changes would be serious
• Repositories you're reviewing but don't own
• Shared codebases where you want to understand but not touch
• Any situation where you want guaranteed zero side effects

Switching Between Modes

You can switch between Normal, Debug, and Ask Mode at any point in a conversation:

• Switch to Ask Mode to explore before committing to a direction
• Switch to Debug Mode when you've identified a hard bug to trace
• Switch back to Normal Mode to implement the fix

The agent carries the conversation context from mode to mode — you don't lose the analysis when you switch.

Combining Both Modes

A common workflow:

1. Ask Mode — "Explain how the checkout flow works and where the price calculation happens"
2. Ask Mode — "Given that understanding, where might the discounted price bug be coming from?"
3. Debug Mode — "Add logging to the price calculation path and trace the bug"
4. Normal Mode — "Fix the bug we just confirmed"

This structured approach — understand, hypothesize, verify, fix — produces better outcomes than jumping straight to a fix.

Frequently Asked Questions

Does Debug Mode add logging to production code?

No. Debug Mode logs are added to your local working copy and are removed before the final fix is committed. The agent cleans up all debug logging as part of the fix commit.

Can I configure what kind of logging Debug Mode uses?

You can tell the agent your preferences in the task description — "use structured logging with our logger utility" or "use console.error so it shows up in the error log." The agent follows your conventions.

Is Ask Mode slower than Normal Mode?

Ask Mode is typically faster because the agent isn't making changes — it's only reading and reasoning. For large codebases, you may notice the agent indexing files, but responses are generally quick.

Can Ask Mode run shell commands?

No. Ask Mode restricts all write operations, including command execution that could have side effects. The agent can read file contents and search within files, but cannot run shell commands.

How do I enable Debug or Ask Mode?

In the thread toolbar, there's a mode selector. You can also include the mode in your task description: "In ask mode, explain how X works" or "Debug the failing test in the auth module."