← Back to blog
AI Agents Automation Prompt Engineering

Cursor Plan Mode: GitHub issue to scoped fix plan in 10 minutes

· 6 min read

Most people open Cursor Agent and ask it to “just fix it.” That feels fast until you spend the afternoon untangling a sprawling diff that touched the wrong layer, skipped tests, and redefined “done.” Principals do the opposite: they get a plan they can trust before any code moves.

Cursor now has a first-class path for that — Plan Mode. Press Shift+Tab in the agent input to rotate into it. Agent researches the codebase, asks clarifying questions, writes an editable plan, and waits for you to hit Build. Agent speed is useless without a principal-engineer gate; Plan Mode is where that gate lives. Ten focused minutes of plan-plus-structure beats two hours of cleanup.

Gate first, code second. If the plan is wrong, the implementation will be wrong faster.

1. Start from a real issue with acceptance criteria

Paste the GitHub issue into the Agent chat — title, body, labels, and any linked comments that matter. Do not paraphrase away the acceptance criteria. If the issue is thin, write three crisp “done when” bullets yourself before you prompt. Vague issues produce vague plans; the agent cannot invent product judgment you refused to write down.

Include repo context the agent will need: which package or service owns the bug, whether this is frontend/backend/infra, and any known constraints (no schema change this sprint, must stay backward compatible, flaky test suite in module X). You are briefing a senior engineer, not typing a wish.

2. Switch to Plan Mode — then instruct the outline

This is the product workflow, not a prompt hack. Hit Shift+Tab (or pick Plan from the mode dropdown) so Agent researches, asks clarifying questions, and produces a reviewable plan before writing code. Cursor may also suggest Plan Mode when your prompt smells like a multi-file or ambiguous task — take the hint for issue-driven fixes.

Plan Mode alone gives you a plan. The principal-engineer upgrade is telling it what structure that plan must use. I pin the same outline every time so the artifact is reviewable in ten minutes:

Plan Mode for this GitHub issue. Research the repo, ask clarifying
questions if acceptance criteria or constraints are ambiguous, then
produce an editable plan. Do not build yet.

Issue:
<paste issue + acceptance criteria>

Structure the plan with every section filled or marked N/A with why:
## Repro
## Suspected root
## Files
## Tests
## Risks
## Out of scope
## First PR slice

Prefer evidence over guesses. Cite paths and symbols.

Answer the clarifying questions honestly — that is half the value of Plan Mode. When the plan markdown appears, edit it in chat or save it to the workspace so reviewers (and your next turn) share the same artifact.

Optional: if you only want a read-only investigate pass first, use Ask Mode (or say “do not write code”) to search and explain without edits. Then switch to Plan Mode once you know the question is worth planning.

3. What each section must earn

The outline is structure on top of Plan Mode — not a substitute for it, and not the only way Cursor can plan. Each section has a job:

  • Repro — steps, expected vs actual, environment notes. If the agent cannot repro or find a clear failing path, stop and tighten the issue.
  • Suspected root — one primary hypothesis plus evidence (file + symbol, stack frame, recent commit). Secondary theories stay short.
  • Files — likely touch list, not a tour of the codebase. Call out read-only context vs intended edits.
  • Tests — existing coverage to run, gaps to fill, and what “green” means for this fix.
  • Risks — regressions, migration, performance, security, flaky CI. Name blast radius.
  • Out of scope — refactors, adjacent bugs, dependency bumps. Explicit excludes protect the PR.
  • First PR slice — the smallest change that proves the root and lands safely. Everything else is a follow-up issue.

If a section is empty, the plan is not ready. “Unknown” is allowed; “skip” is not.

4. Human sanity-check before Build

Read the plan like a principal reviewing a design doc. Ask:

  • Does the root cause match the symptoms, or are we treating a downstream symptom?
  • Is the file list too wide? Wide lists become unsupervised refactors.
  • Are tests specific enough that a wrong fix would fail them?
  • Is “first PR slice” actually shippable alone, or is it secretly half the feature?

Edit the plan in place. Strike bad ideas. Add constraints the agent missed. This is the gate. Skipping it is how “AI coding” gets a bad reputation on your team. If Build goes sideways later, revert, refine the plan, and run it again — faster than patching a wandering agent mid-flight.

5. Publish the plan, then Build slice 1 only

Paste the approved plan into the GitHub issue (or a draft PR description), or keep the workspace-saved plan as shared memory. Only then click Build — and bind implementation to slice 1:

Build ONLY the First PR slice from the approved plan below.
Do not expand Out of scope. Run the listed tests. Stop when the slice
is done and summarize diffs + test results.

<paste approved plan>

If the agent drifts, interrupt and restate the slice boundary. You are not being pedantic — you are keeping the principal-engineer gate closed while the agent works inside it.

Fallback when Plan Mode is not available

Older Cursor builds, CLI-only sessions without Plan, or a teammate who has not found the mode picker yet: stay in Agent (or Ask), forbid implementation explicitly, and require the same outline. Same gate, less product help — you are simulating Plan Mode with prompts until you can rotate with Shift+Tab.

Caveats

This workflow assumes a real codebase the agent can search and a human who will actually read the plan. It will not save you from an issue with no acceptance criteria, or from approving a confident wrong root cause. Green unit tests are not a substitute for product judgment. And “10 minutes” is the planning budget — implementation still takes as long as the slice deserves.

Takeaways

  • Primary path: Plan Mode (Shift+Tab) — research, clarifying questions, editable plan, then Build.
  • Layer the Repro · Root · Files · Tests · Risks · Out of scope · First PR slice outline onto that plan so the PE gate is reviewable in ten minutes.
  • Sanity-check like a principal, publish the plan, authorize only slice 1; use Ask Mode / “do not write code” for read-only investigate, or the outline-as-prompt fallback if Plan Mode is missing.

Do that consistently and agent speed stops being a liability. It becomes leverage — with a human gate where it belongs.

← Back to blog