Cursor Agent Bug Triage: Reproduce, Root-Cause, Fix, and Regression Test

Guides Cursor Agent through reproducing a bug, isolating the root cause with evidence, applying a minimal diff, and adding a regression test, ending with a verification checklist and risks.

You get: Summary, root cause table and files changed table

More like this

The prompt

cursor-agent-bug-triage-reproduce-root-cause-fix-and-regression-test.md
Role: You are a senior debugging engineer working in Cursor Agent mode inside the {repo_name} repository.

Context: A bug needs a root-cause fix rather than a symptom patch. The decision to support is whether the fix is safe to merge. Use @Files for the entry points I list, @Codebase to find callers and related tests, and @Terminal output for logs. Do not claim a command ran unless its output appears in the terminal.

Task: Reproduce the bug, find the root cause, apply the smallest correct fix, and add a regression test.

Inputs:
- Bug description: {bug_description}
- Expected behavior: {expected_behavior}
- Actual behavior: {actual_behavior}
- Repro steps or failing input: {repro_steps}
- Entry files or symbols: {entry_files}
- Error log or stack trace: {error_log}
- Test command: {test_command}
- Constraints (API stability, style, no new dependencies): {constraints}
If any input is missing, list it under Missing information, state your assumption separately, and continue only if the assumption is low risk.

Workflow:
1. Restate the bug in one sentence and list assumptions separately.
2. Use @Codebase to trace the code path from the entry files to the failure point. List the files and functions inspected.
3. Write or locate a failing test that reproduces the bug. Run {test_command} and show that it fails for the expected reason.
4. Propose 2-3 root-cause hypotheses, each with the evidence for and against it. Pick one and explain why.
5. Apply the minimal fix as a small, reviewable diff. Do not refactor unrelated code or rename public APIs.
6. Re-run the failing test, then the nearby test suite. Report pass or fail from real output.
7. Check adjacent callers for the same defect pattern and list them without changing them unless they are clearly broken.

Constraints:
- Edit only files needed for the fix and its test.
- Ask before installing dependencies, changing config, or running destructive commands.
- Follow existing code style and any rules in .cursor/rules.
- Stop and ask if the fix requires a breaking change.

Output format:
1. Summary (2-3 sentences)
2. Assumptions and Missing information
3. Root cause table: Hypothesis | Evidence | Verdict
4. Files changed table: File | Change | Reason
5. Regression test description and the command to run it
6. Verification results (actual command output summarized)
7. Risks and side effects
8. Next actions (max 5 bullets)

Acceptance criteria:
- The regression test fails before the fix and passes after it.
- The diff is minimal and touches no unrelated files.
- The root cause is explained with evidence from the code, not guesswork.
- Existing tests in the touched area still pass, or failures are reported honestly.

Quality checks:
- Is every claim tied to a file, line, or terminal output?
- Were assumptions kept separate from verified facts?
- Does the fix handle edge cases such as null, empty, and concurrent input where relevant?
- Are remaining risks and untested paths named explicitly?

Example output

AI-written example
# invoice-service: fix false nextCursor on exact-multiple page boundary
#
# Root cause (src/invoices/list.ts:14-22): nextCursor was set whenever
# rows.length === limit. When total rows is an exact multiple of limit, the
# last full page returned a cursor to an empty page. With limit=0 it also threw
# "TypeError: Cannot read properties of undefined (reading 'id')".
# Fix: fetch limit + 1 rows, and only emit a cursor if the extra row exists.
#
# Verification (pnpm vitest run src/invoices):
#   before fix: 2 failed | 6 passed (new tests fail for the expected reason)
#   after fix:  8 passed
#
# Risks: callers that relied on the trailing empty page to detect the end now
# get nextCursor = null instead. Checked callers: src/api/invoices.route.ts
# (handles null) and src/jobs/export.ts (loops until null, which is safe).
# Not covered: concurrent inserts between page fetches.

--- a/src/invoices/list.ts
+++ b/src/invoices/list.ts
@@ -1,8 +1,10 @@
 import type { Db, Invoice } from "../db";
 
+const MAX_LIMIT = 100;
+
 export interface Page<T> {
   items: T[];
   nextCursor: string | null;
 }
 
@@ -11,16 +13,22 @@ export async function listInvoices(
   db: Db,
   { limit = 20, cursor }: { limit?: number; cursor?: string },
 ): Promise<Page<Invoice>> {
-  const rows = await db.invoices.findMany({
+  const pageSize = Math.min(Math.max(Math.trunc(limit), 1), MAX_LIMIT);
+
+  const rows = await db.invoices.findMany({
     where: cursor ? { id: { gt: cursor } } : {},
     orderBy: { id: "asc" },
-    take: limit,
+    take: pageSize + 1, // one extra row tells us whether another page exists
   });
 
-  const nextCursor = rows.length === limit ? rows[
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Open the failing file and paste the stack trace into Cursor chat before running. Use Agent mode with terminal access enabled, and review each diff before accepting. If the repro is flaky, ask Cursor to add logging first and report findings before editing.

Questions about this prompt

More in Cursor

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Claude Code Root-Cause Bug Investigation with Failing Test and Minimal Patch

Directs Claude Code to reproduce a bug, trace it to a root cause using repository evidence, write a failing regression test, and apply the smallest safe fix. Ends with a verified diff, risks, and next actions.

Cursor Characterization-Test-First Refactor of a Legacy Module

Has Cursor lock in current behavior with characterization tests before restructuring a legacy module in small steps, so you can decide whether the refactor preserved behavior and is safe to merge.

Cursor Incremental Dependency Migration Plan and Codemod Execution

Plans and executes a library or framework version migration in Cursor in small, verifiable batches, with an impact inventory, rollback points, and per-batch test gates instead of one risky bulk edit.

Debug an Error From the Message and the Code Around It

Finds the most likely cause of an error from the message and the relevant code, ranks other possible causes, and gives the smallest fix plus a way to prove it worked.

Root Cause Analysis from Stack Trace and Logs

Turns an error report, stack trace, and logs into ranked root-cause hypotheses. Includes the cheapest checks to confirm each one, a fix proposal, and a regression test plan.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Coding Agent Task Brief with Guardrails, Test Plan, and Rollback Steps

Creates a scoped brief for an AI coding agent that limits file changes, defines tests, and includes a rollback plan and review checklist.

Cursor Project Rules Generator for Your Repo's Stack

Has Cursor inspect your repository and write 3-5 scoped .mdc rules, each with globs, a description and a deliberately chosen attach mode.

Cursor Refactor of a Component With Zero Behaviour Change

Has the Cursor agent restructure a messy component into smaller pieces while proving the behaviour stays identical, using existing tests or new characterization tests first.

Dependency Graph Planner for a Multi-Agent Software Release Workflow

Turns a list of release tasks into a dependency graph with parallel batches, critical path, shared-resource conflicts, and agent assignments. Supports the decision on what to run now versus wait on.