> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blitzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fix Bugs

> Systematically diagnose and fix production issues, defects, and edge cases using AI-Native root cause analysis

Bugs compete with feature work for engineering time, and they usually lose. The result is a growing list of known defects that erode user trust and compound into larger failures. Blitzy shifts the economics: feed it an error message and reproduction steps and it traces the root cause, implements a fix that addresses the underlying problem rather than the symptom, and generates regression tests so the issue stays resolved.

<Card title="Ready to fix a bug?" icon="rocket" href="/templates/code-quality-maintenance/bug-fix">
  Use the **Bug Fix Template** to get started with a structured prompt
</Card>

<Note>
  **Jump to:** [When to Use](#when-to-use-this-approach) | [Prompt Structure](#prompt-structure) | [Key Considerations](#key-considerations) | [Common Patterns](#common-patterns) | [Troubleshooting](#troubleshooting)
</Note>

## When to Use This Approach

<Tabs>
  <Tab title="Production Defects">
    Fix issues with clear reproduction steps where expected and actual behavior diverge.
  </Tab>

  <Tab title="Logic and Data Errors">
    Correct flawed conditionals, calculations, or data transformations that produce wrong results.
  </Tab>

  <Tab title="Integration Failures">
    Resolve bugs at the boundaries between components, services, or external APIs.
  </Tab>

  <Tab title="Race Conditions and Edge Cases">
    Address timing-dependent failures, null handling gaps, and validation bypasses.
  </Tab>
</Tabs>

## Prompt Structure

Follow the [Golden Rules](/prompt-engineering/golden-rules) when writing your bug fix prompt. Focus especially on:

* **Reproduction Steps** - Provide exact sequence to trigger the bug consistently
* **Error Messages** - Include complete stack traces and error output
* **Behavioral Specification** - Define expected vs actual behavior precisely
* **Test Requirements** - Specify regression tests to prevent recurrence

## Key Considerations

<CardGroup cols={2}>
  <Card title="Reproduction Steps Are Essential" icon="list-ol">
    Document exact steps to trigger the failure consistently. Without reliable reproduction, fixes may address symptoms rather than root causes or introduce regressions.
  </Card>

  <Card title="Expected vs Actual Behavior Clarity" icon="code-compare">
    Clearly state what should happen versus what actually happens. Vague descriptions like "it's broken" lead to superficial fixes that don't address underlying issues.
  </Card>

  <Card title="Complete Error Context Matters" icon="terminal">
    Include full stack traces, error messages, and relevant log entries. Partial error information leads to misdiagnosis and ineffective fixes.
  </Card>

  <Card title="Regression Tests Prevent Recurrence" icon="shield-check">
    Every bug fix must include tests that fail before the fix and pass after. Without regression tests, the same bug returns during future changes.
  </Card>
</CardGroup>

## Common Patterns

**Null/undefined handling** - Add null checks for database lookups, API responses, and optional parameters. Define graceful defaults or appropriate error responses when values are missing.

**Error boundary failures** - Wrap risky operations in try/catch blocks, define specific error types for different failure modes, and ensure error messages provide debugging context without exposing sensitive data.

**Race condition fixes** - Add proper synchronization (locks, queues), implement idempotency for operations that may be retried, and add logging to track concurrent access patterns.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Fix doesn't resolve the bug">
    Root cause may be misidentified. Add more detailed logging to trace execution flow, use debugger to inspect state at failure point, and verify reproduction steps trigger the actual issue.
  </Accordion>

  <Accordion title="Tests pass but bug persists in production">
    Test environment may differ from production. Review the [Environment Configuration](/administration/environments) guide to align test and production environments, and add integration tests with production-like data.
  </Accordion>

  <Accordion title="Fix introduces new bugs">
    Scope may be too broad. Add comprehensive regression tests before implementing fix, use feature flags for gradual rollout, and test against full suite of existing functionality.
  </Accordion>

  <Accordion title="Bug is intermittent and unreproducible">
    Add detailed logging at suspected failure points, implement distributed tracing for multi-service bugs, and analyze patterns in production logs to identify triggering conditions.
  </Accordion>

  <Accordion title="Performance degrades after bug fix">
    Fix may be inefficient. Profile code before and after fix, add the [Analyze Performance Impact](/templates/rules/analyze-performance-impact) rule to your project on the platform, and consider alternative implementation approaches.
  </Accordion>
</AccordionGroup>