Examples
Debugging prompt examples for build errors, runtime crashes, and failing tests
A useful debugging prompt is not a magic phrase. It is a compact evidence package: the failing operation, the first meaningful error, the observed state, the expected behavior, and a way to test the answer. The examples below show how a vague request becomes a falsifiable engineering task.
Copying the wording is less important than preserving the reasoning structure. A strong request prevents the assistant from silently changing requirements, hiding a failure, or treating a plausible guess as a proven root cause.
BUILD / MODULE RESOLUTION
A stylesheet import fails only during the production build
Weak request
My Next.js build is broken. How do I fix it?
Evidence to preserve
- Command: npm run build
- Environment: Next.js 16.2, Windows, Node.js 22
- Relevant file: src/app/layout.tsx
- Recent change: moved globals.css into src/styles
- First error: Module not found: Can't resolve './globals.css'
Stronger request
Explain the most likely cause using only the evidence below. Propose the smallest import-path fix first. If the move could also violate a Next.js global CSS rule, list the check that would distinguish those two causes. Do not suggest reinstalling dependencies unless the error supports it.
Why this is stronger
The request names the failing command, the exact change, and the first causal error. It also asks the assistant to separate two testable hypotheses instead of inventing a broad repair plan.
Verification contract
Run the same production build after changing only the import. Confirm that the original module-resolution error disappears before addressing any later error.
RUNTIME / DATA SHAPE
An API route crashes when an optional profile is missing
Weak request
Why is this undefined? Here is my entire server log.
Evidence to preserve
- Route: GET /api/users/:id
- Relevant expression: user.profile.displayName
- Observed input: profile is null for imported accounts
- Expected behavior: return the user with displayName set to null
- Error: TypeError: Cannot read properties of null (reading 'displayName')
Stronger request
Identify where the runtime assumption differs from the observed data. Compare an optional-chain fix with validating the database result at the boundary. Recommend one based on the expected API contract, and include a regression test for an imported account with profile: null.
Why this is stronger
The prompt includes the real value, the failing expression, and the intended contract. That gives the assistant enough information to discuss design rather than merely adding a defensive operator.
Verification contract
Add one fixture with a profile and one without it. Check the response schema and status code for both cases, then confirm that unrelated server errors are still surfaced.
TEST / STATE LEAKAGE
A test passes alone but fails after the full suite
Weak request
This test is flaky. Rewrite it so it passes.
Evidence to preserve
- Isolated command passes: npm test -- user.test.ts
- Full-suite command fails: npm test
- Failure: expected 200, received 500
- Shared dependency: process.env.DATABASE_URL
- Previous test replaces DATABASE_URL and does not restore it
Stronger request
Use the order-dependent evidence to identify the likely shared-state leak. Suggest the smallest cleanup that restores test isolation without weakening the assertion. Show where setup and teardown belong, and explain one command that can confirm the diagnosis.
Why this is stronger
The assistant is constrained to preserve the assertion and investigate state isolation. It cannot hide the failure by increasing timeouts, removing checks, or retrying the test.
Verification contract
Run the affected files in both orders, then run the suite repeatedly with random ordering if the runner supports it. The test should pass without retries.
Failure patterns
Four prompt habits that produce confident but weak answers
The solution-shaped request
"Tell me where to add optional chaining" assumes the fix before the cause is known. Ask the assistant to compare the assumption with the observed value first.
The context dump
A complete CI transcript can bury the first causal error under retries and summaries. Preserve the failing command, first meaningful error, source location, and a short window around it.
The passing-answer test
"Make the test pass" rewards deletion, weaker assertions, and retries. State the behavior that must remain true and define how the proposed fix will be checked.
The certainty trap
When evidence is incomplete, require assumptions and a discriminating check. A useful answer can say what it does not yet know.
The five-line debugging contract
- 01State the failed operation.
- 02Quote the first causal error.
- 03Describe observed versus expected behavior.
- 04Name relevant changes and constraints.
- 05Define the check that proves the fix.