> ## 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.

# Refine

> Request targeted modifications to improve AI-generated code

Use Refine PR to iteratively improve generated code through targeted feedback. The approach and architecture are correct, but specific implementations need modification.

<Note>
  **Post-Code-Generation Options:** [Merge](/pull-request-review/merge) | [Close](/pull-request-review/close) | [Refine PR](#refine-pr-prompt-format) (this page)

  **Choose Refine when:** The generated code is fundamentally sound but has specific gaps that need addressing.
</Note>

## Refine PR Prompt Format

Structure your feedback using critical directives:

```
CRITICAL Directive: Verify all requested changes remain within the original request scope

CRITICAL Directive: Fix missing error handling in src/services/payment-processor.ts lines 145-167 by adding try-catch blocks around API calls and returning structured error responses

CRITICAL Directive: Achieve 100% test passing rate - currently 3 tests failing in tests/unit/payment-processor.test.ts due to unhandled promise rejections

CRITICAL Directive: Maintain existing authentication middleware in src/middleware/auth.ts unchanged - only modify payment processing logic

CRITICAL Directive: Reference error handling pattern from src/services/user-service.ts lines 89-112 for consistency with codebase standards

CRITICAL Directive: If architectural changes are needed beyond error handling improvements, close PR and create new request with revised scope
```

## Decision Matrix

Apply this matrix to determine whether to refine or close:

| Criteria                 | Refine                                        | Close & Restart                            |
| ------------------------ | --------------------------------------------- | ------------------------------------------ |
| **Scope alignment**      | Changes are within original request scope     | Changes require scope expansion            |
| **Architecture**         | Approach and structure are sound              | Fundamental design flaws                   |
| **Gap severity**         | Specific, addressable implementation gaps     | Critical gaps or broken core functionality |
| **Iteration efficiency** | Fixes achievable through targeted refinements | Complete rework needed                     |

If changes fall outside the scope of your original request, they belong in a separate run. Do not expand scope during refinement.

## Refinement Workflow

<Steps>
  <Step title="Identify gaps">
    Review the generated code and document specific issues:

    * **File locations** - Exact paths and line numbers
    * **Current behavior** - What the code does now
    * **Required behavior** - What it should do
    * **Acceptance criteria** - How to verify the fix

    Focus on whether gaps are in scope (original request) or out of scope (new requirements).
  </Step>

  <Step title="Submit Refine PR request">
    Paste your structured feedback into Blitzy using the Refine PR prompt format above. Blitzy updates the PR with targeted changes.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Be specific">
    * Reference exact file paths and line numbers
    * Describe concrete changes, not vague improvements
    * Provide measurable success criteria
  </Accordion>

  <Accordion title="Maintain scope discipline">
    * Only request changes within original requirements
    * Flag scope creep as separate tasks
    * Use multiple refinements as needed to fill gaps
  </Accordion>

  <Accordion title="Reference patterns">
    * Point to existing code examples in your codebase
    * Specify architectural patterns to follow
    * Maintain consistency with current implementation
  </Accordion>
</AccordionGroup>

## Submodule PRs During Refinement

<Warning>
  Do not close or merge submodule PRs while refinement cycles are in progress. Refine PR reads from submodule branches - closing them causes build failures or incomplete refinements. Wait until all refinement rounds are complete and the main repository PR is merged before touching submodule PRs.
</Warning>

See [Merge - Projects with Submodules](/pull-request-review/merge#projects-with-submodules) for the correct merge order.

## When to Close Instead

Choose [Close](/pull-request-review/close) over Refine when:

* Architectural approach is fundamentally wrong
* Scope has expanded beyond original request
* Starting fresh would be faster than iterative fixes

<CardGroup cols={2}>
  <Card title="Merge Pull Request" icon="code-merge" href="/pull-request-review/merge">
    Criteria for accepting generated code
  </Card>

  <Card title="Close Pull Request" icon="circle-xmark" href="/pull-request-review/close">
    When to discard and restart
  </Card>
</CardGroup>