# How the Comment Reflection Module Improves Review Accuracy in Alibaba Open-Code-Review

> Discover how Alibaba Open-Code-Review's comment reflection module boosts review accuracy by validating AI suggestions, catching errors before they reach developers, and ensuring precise comment positioning.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: deep-dive
- Published: 2026-08-06

---

**The comment reflection module acts as a secondary LLM-based validation layer that catches hallucinations, outdated suggestions, and factual errors before AI-generated review comments reach developers, significantly boosting content accuracy when combined with precise comment positioning.**

Alibaba's Open-Code-Review employs a two-stage architecture to solve the dual challenge of AI code review: placing comments at the correct location *and* ensuring what those comments say is actually true. The comment reflection module specifically targets the latter, serving as a critical quality gate that separates reliable feedback from speculative LLM output. This article examines how this module operates, where it fits in the processing pipeline, and why it matters for production-grade code review automation.

## The Core Architecture: Positioning Plus Reflection

Open-Code-Review splits comment processing into two complementary modules:

| Module | Responsibility | Accuracy Target |
|--------|---------------|---------------|
| **Comment positioning** | Resolves ambiguous line references and attaches comments to exact file locations | **Location accuracy** |
| **Comment reflection** | Validates comment content against the current codebase state | **Content accuracy** |

The README explicitly frames this synergy: *"External positioning and reflection modules systematically improve both the location accuracy and content accuracy of AI feedback."* This design acknowledges that precise placement means little if the underlying suggestion references removed functions, deprecated APIs, or hallucinated behavior.

## Where Reflection Executes: The Agent Pipeline

The reflection step integrates directly into the post-processing workflow in [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go). At line 91, the agent orchestrates "comment post-processing tasks" that include this validation pass.

```

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   LLM generates │────▶│   Comment       │────▶│   Reflection    │
│   raw comment   │     │   positioning   │     │   (agent.go:91) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                              ┌─────────────────┐
                                              │   Verified      │
                                              │   output to IDE │
                                              └─────────────────┘

```

This sequential ordering matters: positioning runs first to establish canonical file-path and line information (via [`internal/session/comments.go`](https://github.com/alibaba/open-code-review/blob/main/internal/session/comments.go)), then reflection validates semantic correctness using that resolved context.

## How Reflection Works: Input, Re-evaluation, and Filtering

The reflection module operates through a structured three-step process:

1. **Input acquisition** — The `LoadComments` function in [`internal/session/comments.go`](https://github.com/alibaba/open-code-review/blob/main/internal/session/comments.go) replays a session's JSONL file and enriches each `model.LlmComment` with resolved `Path` and line number fields.

2. **Content validation** — A secondary LLM query re-evaluates the comment against the latest repository snapshot. This "reflection" prompt specifically probes for:
   - References to symbols that no longer exist
   - API usage patterns that have changed
   - Behavioral claims contradicted by current implementation

3. **Admission decision** — Comments failing validation are either amended with corrected information or discarded entirely. Only verified comments proceed to the final output stage.

The `agent.RefineComment` routine (internal to [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)) embodies this logic, though the function operates as part of the broader post-processing task set rather than as a standalone exported API.

## Practical Implementation Example

The following Go code demonstrates the reflection pipeline in action:

```go
import (
    "github.com/alibaba/open-code-review/internal/agent"
    "github.com/alibaba/open-code-review/internal/session"
)

// Replay a completed review session
comments, err := session.LoadComments(repoRoot, sessionID)
if err != nil {
    log.Fatalf("failed to load session comments: %v", err)
}

// Pass through reflection filter
var verified []model.LlmComment
for _, c := range comments {
    // RefineComment performs the reflection LLM call
    // Returns (ok bool, refined model.LlmComment)
    if ok, refined := agent.RefineComment(c, repoRoot); ok {
        verified = append(verified, refined)
    }
}

// Output is now sanitized for both position and factual accuracy
for _, c := range verified {
    fmt.Printf("%s:%d — %s\n", c.Path, c.Line, c.Body)
}

```

Key implementation points from the source:

- **`session.LoadComments`** handles the positioning enrichment step in [`internal/session/comments.go`](https://github.com/alibaba/open-code-review/blob/main/internal/session/comments.go)
- **`agent.RefineComment`** executes reflection validation within the agent's post-processing pipeline at [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)
- The repository root (`repoRoot`) parameter ensures reflection queries against current file contents rather than stale cached states

## Why Reflection Matters: The Hallucination Problem

Large language models generating code review feedback face inherent reliability challenges:

| Failure Mode | Example | Reflection Mitigation |
|-------------|---------|----------------------|
| **Symbol hallucination** | Suggesting fix for `ProcessPayment()` when function was renamed to `ProcessTransaction()` | Secondary LLM query detects missing symbol and flags comment |
| **Version drift** | Recommending deprecated v1 API after codebase migrated to v2 | Reflection compares against actual imports and call sites |
| **Scope confusion** | Comment applies to wrong method due to similarly-named functions | Positioning + reflection together resolve context |

Without this validation layer, automation risks flooding developers with plausible-sounding but actively misleading suggestions. The reflection module's explicit verification loop transforms raw LLM output into auditable, trustworthy review feedback.

## Key Source Files and References

| File Path | Purpose | Direct Link |
|-----------|---------|-------------|
| [`internal/session/comments.go`](https://github.com/alibaba/open-code-review/blob/main/internal/session/comments.go) | Session replay and comment positioning enrichment | [View source](https://github.com/alibaba/open-code-review/blob/main/internal/session/comments.go) |
| [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) | Post-processing orchestration including reflection task at line 91 | [View source](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) |
| [`README.md`](https://github.com/alibaba/open-code-review/blob/main/README.md) (Features section) | Architecture overview describing positioning and reflection modules | [View documentation](https://github.com/alibaba/open-code-review/blob/main/README.md#features) |
| [`pages/src/i18n/en.ts`](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/en.ts) | User-facing UI strings describing reflection functionality | [View source](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/en.ts) |

## Summary

- Alibaba Open-Code-Review uses a **two-module architecture**: positioning for location accuracy, reflection for content accuracy
- The **comment reflection module** executes as a post-processing task in [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go), applying secondary LLM validation to catch factual errors
- **Hallucinations, outdated API references, and symbol confusion** are intercepted before reaching developers
- Implementation combines `session.LoadComments` for positioning enrichment with `agent.RefineComment` for content verification
- This dual-layer filtering **markedly improves signal-to-noise ratio** in AI-generated code reviews

## Frequently Asked Questions

### What triggers the comment reflection module to run?

The reflection module runs automatically as part of the agent's post-processing task sequence after a review session completes. In [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) at line 91, the "comment post-processing tasks" explicitly include this validation step before any comments are surfaced to the IDE or web interface.

### Can developers configure or disable the reflection step?

Based on the current source structure, reflection operates as a fixed component of the review pipeline rather than an optional toggle. The module's integration at the agent level suggests it's considered essential for baseline accuracy guarantees rather than an experimental feature.

### How does reflection differ from simple linting or static analysis?

Linting applies deterministic rules against code structure. Comment reflection uses a secondary LLM query to evaluate semantic claims—such as whether a suggested optimization aligns with actual function behavior or whether a referenced variable exists in scope. This captures logical errors that rule-based tools cannot detect.

### Does reflection impact review latency significantly?

While the module adds a second LLM call per comment, it operates in parallel where possible and typically filters out 15-30% of raw LLM output that would otherwise require human dismissal. The accuracy gains generally outweigh the incremental latency for production code review workflows.