❌ BAD: Quick scan → "Looks good" → Merge → Issues discovered in develop
Risk: High (quality issues reach main branch)
Confidence: Low (unsure what was checked)
Consistency: Low (different things checked each time)

✅ GOOD: CP1 (git) → CP2 (roadmap) → CP3 (criteria) → ... → Merge with confidence
Risk: Low (systematic verification)
Confidence: High (everything checked)
Consistency: High (same checks every time)

Start Review
    ↓
CP1: Git Status ───→ [Issues?] ──Yes──→ Remediate ──→ Retry CP1
    ↓ No                                                    ↓
CP2: Roadmap ──────→ [Issues?] ──Yes──→ Remediate ──→ Retry CP2
    ↓ No                                                    ↓
CP3: Acceptance ───→ [Issues?] ──Yes──→ Remediate ──→ Retry CP3
    ↓ No                                                    ↓
CP4: Technical ────→ [Issues?] ──Yes──→ Remediate ──→ Retry CP4
    ↓ No                                                    ↓
CP5: Code Quality ─→ [Issues?] ──Yes──→ Remediate ──→ Retry CP5
    ↓ No                                                    ↓
CP6: Localization ─→ [Issues?] ──Yes──→ Remediate ──→ Retry CP6
    ↓ No                                                    ↓
CP7: Merge Ready ──→ Generate merge instructions
    ↓
Approved (with notes)

1. Current branch: feature/XXX-description
2. Extract issue number: XXX
3. Fetch issue from GitHub: gh issue view XXX
4. Load roadmap: docs/planning/0.1.X/ISSUE-XXX-ROADMAP.md
5. Check git status: uncommitted changes, branch sync
6. Identify changed files: git diff develop...HEAD
7. Determine review focus: UI changes, DB changes, logic changes

Code Review for Issue #XXX

Preparing systematic review...

Context:
- Branch: feature/XXX-description
- Issue: #XXX - [Title from GitHub]
- Roadmap: docs/planning/0.1.X/ISSUE-XXX-ROADMAP.md
- Base branch: develop
- Changed files: X files, +Y/-Z lines

Focus areas detected:
[✓ UI Changes / ✓ Database Migration / ✓ Service Logic / ✓ Testing]

Review will proceed through 7 systematic checkpoints:
1. Git Status & Branch Verification
2. Roadmap Completion
3. Acceptance Criteria Validation
4. Technical Standards (analyze, tests)
5. Code Quality Checks
6. Localization Verification [if UI changes]
7. Merge Readiness Assessment

Ready to begin systematic review? (y/n)

1.1 - Working Directory Status:
Command: git status
Expected: "nothing to commit, working tree clean"
Status: [✓ Clean / ⚠ Uncommitted changes / ✗ Untracked files]

1.2 - Current Branch:
Command: git branch --show-current
Expected: feature/XXX-description
Status: [✓ Correct / ✗ Wrong branch]

1.3 - Branch Sync with Remote:
Command: git fetch origin && git status
Expected: "Your branch is up to date with 'origin/feature/XXX-description'"
Status: [✓ Up to date / ⚠ Behind / ⚠ Ahead / ✗ Diverged]

1.4 - Sync with Develop:
Command: git fetch origin develop && git merge-base --is-ancestor origin/develop HEAD
Expected: develop is ancestor (no missing commits)
Status: [✓ Up to date / ⚠ Behind develop]

1.5 - Merge Conflicts Check:
Command: git merge-tree $(git merge-base origin/develop HEAD) origin/develop HEAD
Expected: No conflicts
Status: [✓ No conflicts / ✗ Conflicts detected]

Fix:
1. Review uncommitted changes: git status
2. Either:
   a) Commit them: git add . && git commit -m "message"
   b) Stash them: git stash
   c) Discard them: git restore .

After fixing, re-run checkpoint 1.

Fix:
1. Update develop: git fetch origin develop
2. Rebase on develop: git rebase origin/develop
3. Resolve conflicts if any
4. Force push: git push --force-with-lease origin feature/XXX-description

After fixing, re-run checkpoint 1.

Warning: Merging to develop will cause conflicts.

Preview conflicts:
[Show conflict areas]

Options:
1. Fix now: Rebase on develop and resolve conflicts
2. Proceed with warning: Resolve during merge
3. Abort review: Fix issues first

Choice? (1/2/3)

Reading roadmap: docs/planning/0.1.X/ISSUE-XXX-ROADMAP.md

Analyzing phases...

Phase 1: Analysis & Understanding
- [✓] Task 1 description
- [✓] Task 2 description
- [✓] Task 3 description
Status: ✓ COMPLETE (3/3 tasks)

Phase 2: Implementation
- [✓] Subtask 1
- [✓] Subtask 2
- [⚠] Subtask 3 (checkbox not marked)
Status: ⚠ INCOMPLETE (2/3 tasks)

Phase 3: Testing
- [✓] All tests implemented
- [✓] Tests passing
Status: ✓ COMPLETE (2/2 tasks)

Phase 4: Documentation & Cleanup
- [✓] Code comments added
- [✗] README not updated
Status: ✗ INCOMPLETE (1/2 tasks)

Overall Roadmap Status: ⚠ MOSTLY COMPLETE

Complete Phases: 2/4
- ✓ Phase 1: Analysis & Understanding
- ⚠ Phase 2: Implementation (1 task unmarked)
- ✓ Phase 3: Testing
- ✗ Phase 4: Documentation (README missing)

Issues Found:
1. Phase 2, Task 3: Checkbox not marked (possible oversight?)
2. Phase 4: README update missing

Is Phase 2, Task 3 actually complete? (y/n)
[If yes: Update roadmap checkbox]
[If no: Task needs completion]

Remediation Required:

Issue: Phase 4 - README update missing

Steps to fix:
1. Open README.md
2. Add section documenting new feature
3. Include usage examples if applicable
4. Commit changes: git add README.md && git commit -m "docs: update README for #XXX"
5. Update roadmap: Mark Phase 4 task complete

After fixing:
- Update roadmap file
- Commit roadmap update
- Continue review from checkpoint 2

Fix now? (y/n)

Loading acceptance criteria from issue #XXX...

From issue description:

Acceptance Criteria:

1. [Criterion 1 from issue]
   Type: [Automated / Manual verification]
   [If automated: ✓ Verified via test_name_test.dart]
   [If manual: User confirmation needed]
   Status: [Pending user confirmation]

2. [Criterion 2 from issue]
   Type: Manual verification
   Verification needed: [Is this requirement met? y/n]
   Status: [Pending]

3. [Criterion 3 from issue]
   Type: Automated
   ✓ Verified: test passes, feature works as expected
   Status: ✓ CONFIRMED

[Iterate through all criteria]

Criterion 1: "Users can add notes to recipes"

This requires manual verification.

Questions:
1. Can you navigate to a recipe? (y/n)
2. Is there a notes field/button? (y/n)
3. Can you add text to notes? (y/n)
4. Does the note save and persist? (y/n)

[Collect user responses]

Result: [✓ ALL YES - PASS / ⚠ SOME NO - PARTIAL / ✗ MOSTLY NO - FAIL]

Acceptance Criteria Summary:

Total Criteria: 5
✓ Confirmed: 4
⚠ Partial: 1
✗ Failed: 0

Details:
✓ Criterion 1: Users can add notes to recipes
✓ Criterion 2: Notes persist across app restarts
✓ Criterion 3: Notes support multi-line text
⚠ Criterion 4: Notes have 500 char limit (not enforced in UI)
✓ Criterion 5: Empty notes are allowed

Overall Status: ⚠ MOSTLY MET (non-critical gap)

Issue: Criterion 4 - Character limit not shown in UI

Severity: ⚠ Minor (backend enforces limit, but UX could be better)

Options:
1. Fix now: Add character counter to UI
2. Create follow-up issue: Track as enhancement
3. Accept as-is: Note in merge decision

Choice? (1/2/3)

Creating follow-up issue for minor gap...

Created issue #XXY: "Add character counter to recipe notes field"
- Labeled as: enhancement
- Linked to: #XXX
- Assigned to: backlog

Criterion 4 marked as: ✓ PASS WITH FOLLOW-UP

Proceed to checkpoint 4? (y/n)

Running: flutter analyze

Output:
Analyzing gastrobrain...
[Analysis progress...]

Result:
- 0 errors
- 0 warnings
- 0 hints

Status: ✓ PASS - No issues found

Result:
- 2 errors
- 5 warnings
- 3 hints

Issues:
ERROR: lib/widgets/recipe_dialog.dart:45
  - Undefined name 'recipeName'

ERROR: lib/core/services/recommendation_service.dart:120
  - Missing return statement

WARNING: lib/screens/meal_planning_screen.dart:89
  - Unused import 'package:flutter/material.dart'

[... more issues ...]

Status: ✗ FAIL - Must fix before merge

Remediation:
1. Fix all errors (blocking)
2. Fix all warnings (required)
3. Fix hints (recommended)

Commands to fix:
- View specific file: [command]
- Run analyze again: flutter analyze

Fix now? (y/n)

Running: flutter test

Output:
00:00 +0: loading test/...
[Test progress...]
00:05 +615: All tests passed!

Result:
- Total tests: 615
- Passed: 615
- Failed: 0
- Skipped: 0

Status: ✓ PASS - All tests passing

Result:
- Total tests: 618
- Passed: 615
- Failed: 3
- Skipped: 0

Failed Tests:

1. test/widgets/recipe_notes_dialog_test.dart
   - "saves note with 500 characters"
   - Expected: true, Actual: false
   - Error: Character limit not enforced

2. test/core/services/recipe_service_test.dart
   - "validates note length"
   - Expected: ValidationException, Actual: no exception

3. test/integration/recipe_workflow_test.dart
   - "complete recipe creation with notes"
   - Timeout after 30s

Status: ✗ FAIL - Must fix failing tests

Remediation:
1. Fix failing tests (blocking)
2. Investigate test 3 timeout (may indicate real issue)

Commands:
- Run specific test: flutter test test/widgets/recipe_notes_dialog_test.dart
- Run with verbose: flutter test --verbose
- Debug test: [instructions]

Fix now? (y/n)

Running: flutter test --coverage

Coverage Report:
- Overall: 87.3%
- Changed files: 89.1%

By Category:
- Widgets: 85.2%
- Services: 92.4%
- Models: 95.1%
- Utils: 78.9%

Status: ✓ PASS - Coverage maintained

[If coverage decreased significantly:]
Status: ⚠ WARNING - Coverage decreased from 89% to 87%

Recommendation: Consider adding tests for uncovered code
- lib/widgets/recipe_notes_field.dart: 62% coverage
- lib/core/services/note_validator.dart: 71% coverage

Proceed anyway? (y/n)

Checkpoint 4 Summary:

4.1 - Flutter Analyze: ✓ PASS
4.2 - Flutter Test:    ✓ PASS (615 tests)
4.3 - Test Coverage:   ✓ PASS (87.3%)

Overall Status: ✓ PASS - All technical standards met

Proceed to checkpoint 5? (y/n)

Checking for debug code...

Searching for print() statements:
Command: grep -r "print(" lib/ --include="*.dart" | grep -v "// print"

Result: [✓ None found / ⚠ X instances found]

If found:
Files with print():
- lib/screens/debug_screen.dart:45 (OK - debug screen)
- lib/widgets/recipe_card.dart:89 (REMOVE - debug leftover)

Searching for debugPrint():
Result: [✓ None found / ⚠ X instances found]

Searching for debug flags:
Pattern: kDebugMode
Result: [✓ Properly used / ⚠ Improper usage]

Status: [✓ CLEAN / ⚠ MINOR ISSUES / ✗ DEBUG CODE PRESENT]

Checking for TODO comments...

Command: grep -r "TODO" lib/ --include="*.dart"

Result: [✓ None found / ⚠ X found]

If found:
TODOs in production code:
1. lib/services/recipe_service.dart:120
   - "TODO: Add caching"
   - Severity: ⚠ Minor (performance optimization)

2. lib/widgets/meal_plan_widget.dart:67
   - "TODO: Fix bug with dates"
   - Severity: ✗ Critical (bug noted but not fixed)

Status: [✓ CLEAN / ⚠ MINOR TODOs / ✗ CRITICAL TODOs]

Remediation for critical TODOs:
- Either fix the issue now
- Or create GitHub issue and remove TODO

Proceed? (y/n)

Manual verification needed: Error Handling

Review these aspects:

1. Are all async operations wrapped in try-catch?
   User confirmation: (y/n)

2. Do all error paths show user-friendly messages?
   User confirmation: (y/n)

3. Are errors logged appropriately (not just printed)?
   User confirmation: (y/n)

4. Do errors in critical paths prevent data corruption?
   User confirmation: (y/n)

[Collect responses]

Status: [✓ PASS / ⚠ SOME GAPS / ✗ INADEQUATE]

Manual verification needed: Code Documentation

Review these aspects:

1. Is complex business logic documented with comments?
   User confirmation: (y/n)

2. Are public APIs documented (methods, classes)?
   User confirmation: (y/n)

3. Do comments explain "why" not just "what"?
   User confirmation: (y/n)

4. Are any confusing patterns explained?
   User confirmation: (y/n)

Status: [✓ WELL DOCUMENTED / ⚠ MINIMAL DOCS / ✗ UNDOCUMENTED]

Checkpoint 5 Summary:

5.1 - Debug Code:      ✓ CLEAN
5.2 - TODO Comments:   ⚠ MINOR (1 non-critical TODO)
5.3 - Error Handling:  ✓ ADEQUATE
5.4 - Documentation:   ✓ WELL DOCUMENTED

Overall Status: ✓ PASS WITH MINOR NOTES

Proceed to checkpoint 6? (y/n)

Analyzing changed files for UI components...

Changed Files Analysis:
- lib/screens/: 2 files
- lib/widgets/: 3 files
- lib/dialogs/: 1 file

UI Changes Detected: ✓ YES

Proceeding with localization checks...

[If no UI changes:]
No UI changes detected.
Skipping localization verification.
Proceed to checkpoint 7? (y/n)

Searching for new UI strings...

Method 1: Check ARB file changes
Command: git diff develop...HEAD -- lib/l10n/app_en.arb

New strings in app_en.arb:
1. "recipeNotesLabel": "Notes"
2. "recipeNotesHint": "Add your cooking notes here"
3. "recipeNotesCharLimit": "{current} / {max} characters"

Found: 3 new strings

Method 2: Check for hardcoded strings (should be none)
Command: grep -r "Text(" lib/widgets/ lib/screens/ | grep -v "AppLocalizations"

Result: [✓ None found / ⚠ X hardcoded strings found]

Verifying ARB file completeness...

Check 1: English ARB (app_en.arb)
- "recipeNotesLabel": ✓ Present
- "recipeNotesHint": ✓ Present
- "recipeNotesCharLimit": ✓ Present
Status: ✓ COMPLETE

Check 2: Portuguese ARB (app_pt.arb)
- "recipeNotesLabel": ✓ Present ("Notas")
- "recipeNotesHint": ✓ Present ("Adicione suas notas de cozinha aqui")
- "recipeNotesCharLimit": ✓ Present ("{current} / {max} caracteres")
Status: ✓ COMPLETE

Both ARB files updated: ✓ YES

Check 2: Portuguese ARB (app_pt.arb)
- "recipeNotesLabel": ✗ MISSING
- "recipeNotesHint": ✗ MISSING
- "recipeNotesCharLimit": ✓ Present

Status: ✗ INCOMPLETE

Remediation:
1. Open lib/l10n/app_pt.arb
2. Add missing translations:
   ```json
   "recipeNotesLabel": "Notas",
   "recipeNotesHint": "Adicione suas notas de cozinha aqui"

### 6.4 - AppLocalizations Usage

### 6.5 - Date/Time Formatting

### Overall Localization Status

## Checkpoint 7: Merge Readiness Assessment

**Goal**: Final review summary and merge decision

### Review Summary

### Merge Decision Matrix

**Automatic Approval** (if all true):
- ✓ All checkpoints pass
- ✓ No blocking issues
- ✓ Warnings acceptable (< 3 minor)
- ✓ All acceptance criteria met

**Conditional Approval** (if some true):
- ⚠ Some warnings present (3-5)
- ⚠ Minor gaps with follow-ups created
- ⚠ Some manual checks uncertain
→ Proceed with caution, note issues

**Rejection** (if any true):
- ✗ Any checkpoint fails
- ✗ Critical acceptance criteria unmet
- ✗ Tests failing
- ✗ Flutter analyze errors
- ✗ Blocking bugs present
→ DO NOT MERGE, fix issues first

## Merge Instructions Generation

When approved:

## Failure Remediation Guide

### General Remediation Pattern

### Common Failures and Remediation

**Flutter Analyze Errors:**

**Test Failures:**

**Acceptance Criteria Not Met:**

**Localization Issues:**

## Quality Standards Reference

### Must-Have Standards (Blocking)

**These MUST pass for merge approval:**

- ✗ Flutter analyze: ZERO errors
- ✗ Flutter test: 100% passing rate
- ✗ Critical acceptance criteria: ALL met
- ✗ Backward compatibility: NO breaking changes
- ✗ Data integrity: NO data loss scenarios
- ✗ Security: NO vulnerabilities introduced

### Should-Have Standards (Warning)

**These should pass but can proceed with justification:**

- ⚠ Flutter analyze: Zero warnings (minor warnings acceptable with reason)
- ⚠ Test coverage: Maintained or improved (small decrease acceptable)
- ⚠ Documentation: README updated (can do in follow-up)
- ⚠ Code comments: Complex logic documented (can improve in follow-up)
- ⚠ TODOs: Removed or tracked (non-critical TODOs acceptable)

### Nice-to-Have Standards (Note)

**These improve quality but don't block merge:**

- ℹ Code style: Consistent formatting (automated by formatter)
- ℹ Performance: Optimizations possible (track for future)
- ℹ Additional tests: Edge cases could be added (track for future)
- ℹ Documentation expansion: More examples could help (track for future)

## Success Criteria

The code review succeeds when:

1. ✓ All 7 checkpoints completed systematically
2. ✓ No blocking issues found (or all remediated)
3. ✓ All acceptance criteria explicitly verified
4. ✓ Technical standards met (analyze, tests)
5. ✓ Clear merge decision made (approve/conditional/reject)
6. ✓ Merge instructions provided if approved
7. ✓ User has high confidence in merge safety

## References

- **Issue Workflow**: `docs/workflows/ISSUE_WORKFLOW.md`
- **Testing Guide**: `docs/testing/DIALOG_TESTING_GUIDE.md`
- **Localization Protocol**: `docs/workflows/L10N_PROTOCOL.md`
- **Edge Case Standards**: Issue #39, `docs/testing/EDGE_CASE_TESTING_GUIDE.md`
- **CLAUDE.md**: General development workflow

---

**Remember**: Code review is about quality assurance, not speed. Each checkpoint verification prevents issues from reaching develop branch. Never rush through checkpoints.