> ## 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. # Code Review > Structure an effective review process that scales with AI-generated code volume Blitzy generates code from a reviewed plan, not from a blank branch. By the time a PR opens, the important decisions - scope, file coverage, approach - have already been approved in the Agent Action Plan. Your review starts there, not in the diff. **Jump to:** [AAP as Source of Truth](#layer-1-the-aap-as-source-of-truth) | [Dynamic Validation](#layer-2-dynamic-validation) | [Code-Level Review](#layer-3-code-level-review) | [Post-Review Actions](#post-review-actions) ## The Core Principle - Review Intent, Not Just Implementation Traditional code review is reactive: a developer writes code, a reviewer reads the diff. At the scale Blitzy operates, that model breaks. The most important review work on a Blitzy project happens before a single line of code is generated. Blitzy produces reviewable artifacts *before* execution, and its review model is built on three layers - each catching different classes of issues at the lowest cost. ```mermaid theme={null} flowchart LR A([Ingest Codebase]) --> B([Generate AAP]) B --> C{AAP Review} C -->|Changes requested| B C -->|Approved| D([Execute Tasks]) D --> E([Commits & PRs]) E --> F{Dynamic Validation} F -->|Failures| D F -->|Pass| G{Code Review} G -->|Changes requested| D G -->|Approved| H([Merge]) style C fill:#7c3aed,color:#fff style F fill:#7c3aed,color:#fff style G fill:#7c3aed,color:#fff ``` ## Layer 1 - The AAP as Source of Truth The **Agent Action Plan (AAP)** is the authoritative specification Blitzy produces before code generation begins. It maps every task to specific files, functions, and change types in plain language a domain expert can evaluate. Blitzy does not improvise beyond the plan. A thoroughly reviewed AAP gives you confidence in the resulting code *before you read a single line of it*. Reviewing the AAP is, in practice, reviewing the code - at a fraction of the cost. The AAP review is your highest-leverage gate. Issues caught here cost minutes to fix. The same issues caught in a diff cost hours. ### Why the AAP Replaces Traditional Diff Review | | AAP Review | Diff Review | | ---------------------------------- | ----------------------- | ----------------------------- | | **When it happens** | Before code is written | After code is written | | **What you're reading** | Intent and approach | Implementation detail | | **Time to catch a wrong decision** | Minutes | Hours or days | | **Cost to fix** | Low - no code to change | High - code must be rewritten | | **Scales with output volume** | Yes | No | ### What to Look for in an AAP Review * **Correct system understanding** - Does the plan reflect an accurate read of the existing system? * **File coverage** - Are the right files being modified? Are any files conspicuously absent? * **Change sequence** - Does the sequence of changes make sense given system dependencies? * **Scope appropriateness** - Is the scope appropriate, or has the plan over- or under-reached? * **Business logic implications** - Are there business logic implications the plan does not account for? When your team invests in AAP review, code review becomes confirmation, not discovery. For detailed guidance, see [Agent Action Plan Review](/project-lifecycle/aap-review). ## Layer 2 - Dynamic Validation Once the AAP is approved and code is generated, the question is not "does this code look right?" but "does this code *work*?" Dynamic validation answers that through automated signals, not human reading. Test suites, performance benchmarks, and CI pipelines become your second review layer. A thorough AAP review plus passing dynamic validation gives high confidence without a line-by-line diff review. ### Validation Signals | Signal | What It Proves | When It Is Sufficient | | ------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | **Test suites** | Functional correctness against defined expectations | When test coverage is comprehensive and tests are well-written | | **Performance benchmarks** | No regressions in throughput, latency, or resource usage | When benchmarks cover critical paths and have established baselines | | **Build and compile** | Structural integrity, no broken imports or type errors | Always - this is the minimum bar | | **Linting and static analysis** | Adherence to coding standards and pattern consistency | When rules are configured to match your team's conventions | | **Integration and E2E tests** | Cross-service behavior and user-facing workflows | When integration coverage exists for the modified paths | | **Computer Use (Windows)** | Visual correctness, UI accessibility, and desktop application behavior through direct screen interaction | When generated code targets Windows desktop applications or requires visual validation beyond headless testing | | **CI/CD pipeline results** | End-to-end validation through your existing build, test, and deployment pipelines | When pipelines are configured to trigger during generation (see below) | ### CI/CD Pipeline Timing CI/CD pipelines validate generated code through your existing workflows. When the pipeline runs determines how Blitzy uses the results. The most reliable path is [Refine PR](/pull-request-review/refine). When your pipeline triggers on each commit push to the Blitzy branch, results feed back into the generation cycle. Blitzy reads the pipeline output, identifies failures, and attempts to self-correct before the job ends. **Configure this path when:** * Your pipeline runs on push events to any branch * You want Blitzy to attempt resolving CI failures automatically during generation * Build, test, or lint failures should block the PR until fixed Include passing CI checks as a success criterion in your AAP to ensure Blitzy treats pipeline failures as actionable feedback. Self-correction depends on pipeline visibility, execution speed, and SCM provider configuration. Results vary by environment. If Blitzy does not self-correct, use [Refine PR](/pull-request-review/refine) after the PR is created. When your pipeline triggers on PR creation, it runs after Blitzy has finished generating code. Blitzy agents do not have SCM access at this point - they cannot read pipeline results or push fixes. **To address CI failures:** Check the pipeline output on the PR to identify specific failures. Reference the specific failures in a [Refine PR](/pull-request-review/refine) prompt. Blitzy updates the PR, which triggers the pipeline again. This is the most reliable path across all SCM providers, regardless of pipeline configuration or permission models. Regardless of when your pipeline triggers, [Refine PR](/pull-request-review/refine) is always available as a fallback. Review the CI results on the PR, reference the failures in your Refine prompt, and Blitzy will iterate. **PAT-based SCM providers (Azure DevOps, GitLab, Bitbucket):** These platforms may not expose pipeline status through Blitzy's default permissions. If Blitzy cannot read pipeline results during generation, configure a PAT with pipeline read access in your [environment settings](/administration/environments), or use [Refine PR](/pull-request-review/refine) after the PR is created. ### When Dynamic Validation Is Enough Dynamic validation alone can be sufficient when: * AAP was thoroughly reviewed and approved * Test coverage is comprehensive for the modified paths * All tests, benchmarks, and CI checks pass * Changes are in well-tested modules with established patterns * Risk tier is **Light** (boilerplate, config, scaffolding, test generation) In these cases, a spot-check of the diff is appropriate, but a full line-by-line review is not necessary. Dynamic validation is not sufficient when: * Test coverage is thin or nonexistent for the modified paths * Changes touch business logic encoding regulatory or contractual rules * New external integrations or auth flows are introduced * Benchmarks do not cover the critical paths affected * Dynamic signals pass but the AAP flagged areas of uncertainty In these cases, proceed to Layer 3. Dynamic validation does not replace judgment - it replaces *reading*. When your automated signals are strong enough, the reviewer's job shifts from "verify correctness" to "verify that the right things are being tested." ## Layer 3 - Code-Level Review Code-level review is the final layer. It catches what the AAP and dynamic validation cannot: nuanced business logic, security-sensitive paths, and gaps in automated coverage. When a PR is AI-generated, you are not reviewing human-authored code where you can lean on commit history and author intent. You are reviewing a large generated codebase - a fundamentally different problem. Line-by-line reading of tens of thousands of lines is not the goal. Triage by risk tier and focus where it matters. ### Where to Focus Before reading individual files, validate the high-impact areas first: * **Architecture** - Does the directory layout, dependency graph, and component structure match the approved AAP? * **Boundaries and contracts** - API endpoints, database schemas, type definitions, and inter-module interfaces are where the most consequential decisions live. If the contracts are right, implementation bugs are fixable. If the contracts are wrong, everything built on top of them is wrong. * **Operational concerns** - Environment and config handling, dependency versions (current and vulnerability-free), database migrations, authentication and authorization flows, logging and observability. ### Risk Tiers | Tier | Examples | Review Approach | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | **Deep** | Business logic encoding regulatory or contractual rules, auth and session management, data persistence and migration, external system integrations | Full human review by domain owner | | **Standard** | New service scaffolding, API endpoint implementations against a defined spec, data transformation in well-tested modules | Standard peer review | | **Light** | Boilerplate from established patterns, test file generation, non-production config and infrastructure-as-code | Dynamic validation + spot-check | ### Domain-Assigned Reviewers Large pull requests become tractable when reviewed by the right people, not the most available. A module owner catches deviations immediately that a generalist might miss entirely. ```mermaid theme={null} flowchart LR AAP([AAP Tasks]) --> T1[Task: Payments] AAP --> T2[Task: Auth] AAP --> T3[Task: Reporting] T1 --> R1[Payments team reviewer] T2 --> R2[Security team reviewer] T3 --> R3[Data team reviewer] ``` Distribute review load by domain ownership, not by availability. ### AI-Assisted Review A separate AI model can help reviewers orient themselves in a large diff, freeing human attention for the sections that require genuine judgment. | Step | What Happens | | ------------- | ----------------------------------------------------------------------------------------- | | **Summarize** | AI model produces a plain-language summary of what the diff does | | **Flag** | Model identifies deviations from coding standards and unusual patterns | | **Triage** | Reviewer focuses attention on flagged sections, unflagged sections receive a lighter pass | | **Decide** | Human reviewer retains full accountability, sign-off belongs to the engineer | AI-assisted review is a triage and flagging tool, not an approval authority. Human reviewers retain full accountability for sign-off. #### AI-Assisted Review by Context | Context | Recommended Approach | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Highly regulated industry** (financial services, healthcare) | Use as a triage aid only, all flagged sections require a human decision, AI output does not constitute approval | | **Standard enterprise** | Use for Standard and Light risk tiers, reserve full human review for the Deep risk tier | | **High-velocity teams** | Use broadly with clear escalation criteria for flagged outputs | ### Be Transparent About Coverage With large generated PRs, the temptation is to approve because exhaustive review is impossible. That is the worst outcome. Instead, be explicit about what you reviewed and what you did not. Use a coverage statement in your PR approval. For example: "I validated the architecture, reviewed the API contracts and auth flow, spot-checked implementation in these areas, and ran the test suite. I have not reviewed X, Y, and Z in detail." Transparency about review coverage is more valuable than a false sense of thoroughness. ## Post-Review Actions After your review, choose one of four actions. Your choice determines whether the workflow advances or iterates. The generated code meets quality standards and is ready for integration. * Code is merged to your target branch * Blitzy's context updates to include the merged changes * You return to the generation prompt step to start your next task [Merge criteria and approval workflow](/pull-request-review/merge) The code is fundamentally sound but needs specific improvements. * Submit targeted feedback about what needs to change * Blitzy updates the same PR with modifications * Review again and choose to merge, refine further, or close [How to request refinements](/pull-request-review/refine) The target branch changed since generation, causing conflicts that block the merge. * Select **Fix Merge Conflicts** from the Blitzy PR dropdown menu * Blitzy rebases your branch and regenerates conflicting sections while preserving the original intent * Review the updated PR and proceed with merge, refine, or close [Merge conflicts and resolution](/pull-request-review/merge#merge-conflicts) The code has fundamental issues, or starting over would be faster than refining. * PR is closed without merging * You refine your prompt based on what you learned * A fresh PR is generated from the improved request [When to close and restart](/pull-request-review/close) ### Decision Framework | Scenario | Action | | ------------------------------------------------------ | --------------------------- | | Code meets requirements, passes tests | **Merge** | | Minor fixes needed, architecture is sound | **Refine PR** | | Target branch changed, conflicts block merge | **Resolve Merge Conflicts** | | Fundamental issues or scope misalignment | **Close** | | Full rework more efficient than incremental refinement | **Close** | ## Recommended Review Workflow ```mermaid theme={null} flowchart TD A([AAP Generated]) --> B[Review AAP
Challenge scope, approach,
and file coverage] B --> C{AAP Approved?} C -->|No| D[Refine AAP] D --> A C -->|Yes| E([Execute]) E --> F{Build, tests,
benchmarks pass?} F -->|No| G[Return to Blitzy
for remediation] G --> E F -->|Yes| H{Risk tier?} H -->|Deep| I[Full domain
owner review] H -->|Standard| J[Standard
peer review] H -->|Light| K[Spot-check
and merge] I --> L([Approve & Merge]) J --> L K --> L ``` ## Summary | Layer | What It Does | When It Happens | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | **AAP Review** | Validates intent and approach before any code is written, serves as the source of truth for what the implementation will do | Pre-execution | | **Dynamic Validation** | Proves the implementation works through tests, benchmarks, and CI signals | Post-execution, pre-review | | **Code-Level Review** | Catches what automated signals cannot: nuanced logic, security, and domain-specific concerns | Post-validation | ## Related Guides Review the Agent Action Plan before code generation begins Criteria for accepting generated code Request targeted modifications to improve generated code When to discard and restart with a new prompt