BMAD-METHOD/src/modules/bmm/workflows/4-implementation/code-review/steps/step-04-context-aware-review.md

name	description
step-04-context-aware-review	Story-aware validation: verify ACs, audit task completion, check git discrepancies

Step 4: Context-Aware Review

Goal: Perform story-aware validation - verify AC implementation, audit task completion, review code quality with full story context.

VALIDATE EVERY CLAIM - Check git reality vs story claims You KNOW the story requirements - use that knowledge to find gaps

---

AVAILABLE STATE

From previous steps:

• {story_path}, {story_key}
• {story_file_list}, {git_changed_files}, {git_discrepancies}
• {acceptance_criteria}, {tasks_with_status}
• {comprehensive_file_list}, {review_attack_plan}
• {asymmetric_findings} - From Phase 1 (adversarial review)

---

STATE VARIABLE (capture now)

• {context_aware_findings} - All findings from this phase

Initialize {context_aware_findings} as empty list.

---

EXECUTION SEQUENCE

0. Load Planning Context (JIT)

Load planning documents for AC validation against system design:

• Architecture: {planning_artifacts}/*architecture*.md (or sharded: {planning_artifacts}/*architecture*/*.md)
• UX Design: {planning_artifacts}/*ux*.md (if UI review relevant)
• Epic: {planning_artifacts}/*epic*/epic-{epic_num}.md (the epic containing this story)

These provide the design context needed to validate AC implementation against system requirements.

1. Git vs Story Discrepancies

Review {git_discrepancies} and create findings:

Discrepancy Type	Severity
Files changed but not in story File List	Medium
Story lists files but no git changes	High
Uncommitted changes not documented	Medium

For each discrepancy, add to {context_aware_findings} (no IDs yet - assigned after merge):

{
  source: "git-discrepancy",
  severity: "...",
  description: "...",
  evidence: "file: X, git says: Y, story says: Z"
}

2. Acceptance Criteria Validation

For EACH AC in {acceptance_criteria}:

1. Read the AC requirement
2. Search implementation files in {comprehensive_file_list} for evidence
3. Determine status: IMPLEMENTED, PARTIAL, or MISSING
4. If PARTIAL or MISSING → add High severity finding

Add to {context_aware_findings}:

{
  source: "ac-validation",
  severity: "High",
  description: "AC {id} not fully implemented: {details}",
  evidence: "Expected: {ac}, Found: {what_was_found}"
}

3. Task Completion Audit

For EACH task marked [x] in {tasks_with_status}:

1. Read the task description
2. Search files for evidence it was actually done
3. Critical: If marked but NOT DONE → Critical finding
4. Record specific proof (file:line) if done

Add to {context_aware_findings} if false:

{
  source: "task-audit",
  severity: "Critical",
  description: "Task marked complete but not implemented: {task}",
  evidence: "Searched: {files}, Found: no evidence of {expected}"
}

4. Code Quality Review (Context-Aware)

For EACH file in {comprehensive_file_list}:

Review with STORY CONTEXT (you know what was supposed to be built):

• Security: Missing validation for AC-specified inputs?
• Performance: Story mentioned scale requirements met?
• Error Handling: Edge cases from AC covered?
• Test Quality: Tests actually verify ACs or just placeholders?
• Architecture Compliance: Follows patterns in architecture doc?

Add findings to {context_aware_findings} with appropriate severity.

5. Minimum Finding Check

If total findings < 3, NOT LOOKING HARD ENOUGH

Re-examine for:

• Edge cases not covered by implementation
• Documentation gaps
• Integration issues with other components
• Dependency problems
• Comments missing for complex logic

---

PHASE 2 SUMMARY

Present context-aware findings:

**Phase 2: Context-Aware Review Complete**

**Findings:** {count}
- Critical: {count}
- High: {count}
- Medium: {count}
- Low: {count}

Proceeding to findings consolidation...

Store {context_aware_findings} for consolidation in step 5.

---

NEXT STEP DIRECTIVE

CRITICAL: When this step completes, explicitly state:

"NEXT: Loading step-05-consolidate-findings.md"

---

SUCCESS METRICS

• All git discrepancies reviewed and findings created
• Every AC checked for implementation evidence
• Every task verified with proof
• Code quality reviewed with story context
• Minimum 3 findings (push harder if not)
• {context_aware_findings} populated
• Phase summary presented
• Explicit NEXT directive provided

FAILURE MODES

• Accepting "looks good" with < 3 findings
• Not verifying tasks with actual evidence
• Missing AC validation
• Ignoring git discrepancies
• Not storing findings for consolidation
• No explicit NEXT directive at step completion