Debug: a custom debugging posture

Debug is a useful custom posture for a tricky bug. Where Agent’s instinct is to implement a feature and a Plan posture’s is to design one, Debug’s job is to reproduce and fix a failure - reach for it when something is already broken and a normal Agent pass hasn’t found the cause. Its exact availability and controls are version-sensitive.

Note what Debug actually does, because it isn’t a read-only “tell me why” mode. Its loop is hands-on:

1. It generates several hypotheses about what’s going wrong.
2. It instruments your code with logging statements to test those hypotheses - meaning it edits files before the root cause is known, planting probes rather than waiting until it’s certain.
3. You reproduce the bug so it can collect the runtime logs those probes emit.
4. It reads the logs, isolates the cause, and ships a targeted fix - typically a precise two- or three-line modification - then removes the instrumentation it added.

So Debug both edits to diagnose and delivers the fix. The contrast with Agent isn’t “Debug won’t touch your code” - it will, twice. It’s that Debug is built around the reproduce-instrument-fix cycle for bugs that resist a straight-ahead Agent attempt, rather than implementing new behaviour.

The same modes from the CLI

Everything in this chapter starts from the GUI editor. Cursor’s CLI is documented under both agent and cursor-agent in different generations of the docs, so use the name installed by your current CLI. CLI mode commands and Debug support are version-sensitive; check the current slash-command reference before scripting /plan, /ask, or /debug.

We cover the CLI properly in its own chapter - for now, the thing to carry forward is that modes aren’t a GUI gimmick. They’re a posture that travels with you into the terminal.

The skill, restated

These postures aren’t features to memorise. They’re a single dial - how much latitude does this task deserve before I look?:

• Ask when you don’t yet know the change. Read-only; zero risk.
• Agent when the change is contained and you’d rather review a finished diff.
• Plan when a mistake reaches past the file in front of you - clarify, research, write it down, edit it, then build.
• Debug when something is already broken and a normal Agent pass can’t crack it - let it instrument, reproduce, and fix, if that custom posture is available in your version.

Use the mode picker or the shortcut configured for your installation. The person who’s merely installed Cursor leaves it in Agent and hopes. The person who’s good with it feels which posture a task is asking for before they type a word.

Every detent on that dial assumes the agent is looking at the right code. It often isn’t - and a wrong-file answer arrives with exactly the same confidence as a right one, in any mode you pick. So the next dial isn’t how far the agent may go; it’s what’s in front of it when it starts. Next: context, @-tagging and self-gathering.