Project Guide

Overview

After code generation, Blitzy delivers a Project Guide with every pull request - a summary of what was built, which requirements were targeted, and what work remains. Your job is to review it alongside the PR diff and recommend a merge decision.

Project Guide review happens after code generation and before the merge decision. Review the guide alongside the PR diff, not in isolation.

What to Review

Requirement Coverage

Every requirement from the generation prompt appears in the Project Guide
No requirements were silently dropped or reinterpreted
Scope boundaries match what was requested (nothing added, nothing omitted)
Out-of-scope items are explicitly documented

Implementation Accuracy

Generated code matches what the Project Guide describes
File paths, function names, and module structures align with the guide
Business logic behaves as specified, not just structurally present
Edge cases and error handling match documented behavior

Standards Compliance

Implementation follows patterns defined in your development guide
Naming conventions, architecture layers, and coding standards are respected
No unapproved dependencies or architectural deviations introduced

Documentation and Tests

Unit and integration tests cover the implemented requirements
Test cases include both happy paths and edge cases
API documentation, inline comments, or README updates are present where needed
Any new configuration or environment variables are documented

Review Workflow

Open the Project Guide and PR together

Pull up the Project Guide and the PR diff in adjacent views. The Project Guide is your map for the review, the PR diff is the territory.

Run and test changes using the Project Guide

Follow the Project Guide’s setup and run instructions to build and test the changes locally. Verify that the implementation behaves as described, not just that the code compiles.

Review source code guided by declared changes

Use the Project Guide’s list of declared changes and remaining work to focus your code review. Check that completed items are fully implemented and that remaining work items are accurately scoped.

Post your findings as a PR review

Summarize what was completed, list gaps with specific details, and state your merge recommendation using the decision framework below.

Decision Framework

Completion	Gaps	Decision	Action
All or nearly all items done	None or minor	Merge	Approve. Document minor items for follow-up.
Most items done	No critical gaps	Merge with follow-ups	Approve with tickets for remaining items.
Several items incomplete	Major gaps	Refine	Request changes. List specific items to address.
Large portion incomplete	Substantial	Discard	Close PR. Revisit prompt or AAP before regenerating.

Critical gaps override completion. Security vulnerabilities, data integrity issues, or broken core functionality mean Discard regardless of how much else was completed.

Documenting Gaps

Be specific when documenting gaps. “Authentication needs work” is not actionable. “Token refresh endpoint returns 500 on expired tokens, need refresh logic with exponential backoff” is.

Template
Example

Requirement: [Project Guide reference]
Status: [Not Started | Partial - X%]
What's Missing:
  - [Specific functionality or behavior not implemented]
  - [Edge cases not handled]
  - [Tests not written]
Impact: [HIGH | MEDIUM | LOW] - [Brief business or technical impact]
Effort: [Estimated hours to complete]

Requirement: REQ-015 User Profile Update
Status: Partial - 60%
What's Missing:
  - No email format validation on update endpoint
  - No handling for concurrent updates (last-write-wins, should return 409)
  - Profile photo upload not implemented (text fields only)
  - No rate limiting on update endpoint
Impact: MEDIUM - Core functionality works but edge cases cause data issues
Effort: 8 hours

Common gap categories:

Missing functionality - Features specified but not present in the PR
Incomplete implementation - Features partially built, missing edge cases or validation
Missing tests - Code works but lacks adequate test coverage
Missing documentation - No API docs, inline comments, or config documentation
Security gaps - Authentication, authorization, or input validation missing
Performance issues - Requirements with response time or throughput targets not met

When to Escalate

Escalate to	When	What to include
Engineering Lead	Significant incomplete work, 3+ standards deviations, uncertain gap severity	Gap summary, deviation list, your recommendation
Product Owner	Requirements conflict with each other, scope changed during generation, ambiguous acceptance criteria	Conflict details, what was implemented vs. expected, proposed resolution
Architecture Reviewer	Unapproved architectural changes, new external dependencies, pattern violations	Code locations, relevant development guide sections, concern summary

Agent Action Plan Review

Review and refine the AAP before code generation begins.

Tech Spec Review

Verify Blitzy’s understanding of your codebase after ingestion.

Project Setup

Configure your repository, environment, and project on the platform.

PR Merge Decision

Final merge criteria and approval workflow for generated PRs.

PR Refinement

Request targeted changes when a PR needs adjustments before merge.

Golden Rules

Best practices for writing precise generation prompts.

Getting Started

Platform

Project Lifecycle

Overview

What to Review

Review Workflow

Decision Framework

Documenting Gaps

When to Escalate

Agent Action Plan Review

Tech Spec Review

Project Setup

PR Merge Decision

PR Refinement

Golden Rules

​Overview

​What to Review

​Review Workflow

​Decision Framework

​Documenting Gaps

​When to Escalate

​Related Guides

Agent Action Plan Review

Tech Spec Review

Project Setup

PR Merge Decision

PR Refinement

Golden Rules

Overview

What to Review

Review Workflow

Decision Framework

Documenting Gaps

When to Escalate

Related Guides