Why this category matters Link to heading

Debugging prompts are most useful when they include concrete failure context: error text, logs, and relevant files.

The Debug errors category demonstrates this pattern with three practical examples.

Use cases Link to heading

  • Developers debugging production-like failures under time pressure
  • QA and CI owners diagnosing flaky test behavior
  • Developers learning to write high-signal debugging prompts

The 3 examples in this category Link to heading

  1. Debugging invalid JSON
  2. Handling API rate limits
  3. Diagnosing test failures

Diagram: Debug prompt-to-fix loop Link to heading

C - - - P - - V - - - a r a p e l r o a a l r r c t r o e m s s i e e h u r g l p k k d r p e r o s e t a u r c e r v r t t n o k a C o a e d f m n o o r t u r a e t p t g f e c e i s i e i s e g l s c l c t x t r u a o o a e s s e r g d t u d c s e e e s e s / C e f n i e f h i a o v i a x r n i l t i s d e o e s n c e

1) Debugging invalid JSON Link to heading

Scenario from the cookbook:

  • A JSON parse error occurs due to malformed JSON.
  • Prompt asks why JSON is invalid and how to fix it.

Prompt pattern:

Why is my JSON object invalid and how can I fix it?

Expected response style:

  • Pinpoint exact syntax issue.
  • Return corrected JSON.

Validation checklist:

  • Parse with a JSON parser.
  • Confirm no trailing commas or quote mismatches.
  • Ensure original semantics remain unchanged.

2) Handling API rate limits Link to heading

Scenario from the cookbook:

  • API calls can fail due to limits; app needs resilient retry behavior.

Prompt pattern:

How can I handle API rate limits within get_weather().

Typical improvement pattern in response:

  • Retry session
  • Backoff strategy
  • Error handling around request failures

Validation checklist:

  • Confirm backoff and retry limits match service policy.
  • Handle HTTP status families intentionally.
  • Ensure failures return predictable API responses.

3) Diagnosing test failures Link to heading

Cookbook showcases two high-value scenarios:

  • Passes locally, fails in CI (timezone/time-boundary mismatch).
  • Intermittent failures (race condition in async/background workflow).

Prompt pattern with strong context:

Please take a look at this CI failure message.
The test passes locally, but intermittently fails in CI.
Can you help me figure out if this looks like a code bug,
environment issue, or a flaky test?

<failure excerpt>
#file:order.py
#file:test_order_service.py

Why this works:

  • Includes failure output.
  • Includes relevant files.
  • Asks for classification and root-cause reasoning.

Validation checklist:

  • Reproduce with deterministic clocks/timezones where relevant.
  • Add synchronization/waiting for async state transitions.
  • Rerun tests multiple times in CI-like conditions.

Debug prompting patterns that consistently help Link to heading

  • Ask for root-cause categories, not only fixes.
  • Include before/after logs for flaky behavior.
  • Ask for minimal patch plus explanation.
  • Ask for follow-up tests that prevent recurrence.

Worked example Link to heading

Scenario Link to heading

A test passes locally but fails intermittently in CI around date boundaries.

Code under test Link to heading 

# order.py
from datetime import date, timedelta

def expected_delivery_date(order_date: date) -> date:
    """Returns next business day. Skips Friday-into-weekend."""
    if order_date.weekday() >= 4:  # Friday=4, Saturday=5, Sunday=6
        days_ahead = 7 - order_date.weekday()
    else:
        days_ahead = 1
    return order_date + timedelta(days=days_ahead)

# test_order_service.py
from datetime import date
from order import expected_delivery_date

def test_weekday_delivery():
    today = date.today()          # Bug: binds test to system clock
    result = expected_delivery_date(today)
    assert result > today         # Passes Monday–Thursday, fails Friday in some timezones

The test uses date.today(), which means its assertions change depending on when and where it runs. In CI, the server timezone or date boundary can push the evaluation to Friday, causing the test to fail.

Evidence bundle to include Link to heading

  • Failure excerpt
  • Runtime timezone details
  • Relevant implementation and test files

Prompt Link to heading 

Classify this failure as code bug, environment issue, or flaky test.
Then provide:
1) likely root cause,
2) minimal patch,
3) regression test additions,
4) rerun strategy.

Failure log:
<paste CI failure>

Files:
#file:order.py
#file:test_order_service.py

Expected good response characteristics Link to heading

  • Explains why timezone assumptions cause divergence.
  • Proposes deterministic clock/timezone handling.
  • Adds regression coverage for edge boundaries.

Validation steps Link to heading

  1. Re-run failing tests multiple times with controlled timezone.
  2. Re-run entire suite in CI.
  3. Confirm no unrelated behavior changed.

Key takeaways Link to heading

  • Best debugging prompts include concrete evidence, not vague symptoms.
  • Root-cause classification is often more valuable than immediate patching.
  • Flaky test diagnosis benefits heavily from logs and file references.
  • Every suggested fix must be validated with reruns and regression checks.

References Link to heading