Reviewing Changes

Instructions

IMPORTANT: Use structured thinking throughout your review process. Plan your analysis in <thinking> tags before providing final feedback. This improves accuracy by 40% according to research.

Step 1: Detect Change Type

Analyze the changeset to determine the primary change type:

Detection Rules:

• Dependency Update: Only gradle files changed (libs.versions.toml, build.gradle.kts) with version number modifications
• Bug Fix: PR/commit title contains "fix", "bug", or issue ID; addresses existing broken behavior
• Feature Addition: New files, new ViewModels, significant new functionality
• UI Refinement: Only UI/Compose files changed, layout/styling focus
• Refactoring: Code restructuring without behavior change, pattern improvements
• Infrastructure: CI/CD files, Gradle config, build scripts, tooling changes

If changeset spans multiple types, use the most complex type's checklist.

Step 2: Load Appropriate Checklist

Based on detected type, read the relevant checklist file:

• Dependency Update → checklists/dependency-update.md (expedited review)
• Bug Fix → checklists/bug-fix.md (focused review)
• Feature Addition → checklists/feature-addition.md (comprehensive review)
• UI Refinement → checklists/ui-refinement.md (design-focused review)
• Refactoring → checklists/refactoring.md (pattern-focused review)
• Infrastructure → checklists/infrastructure.md (tooling-focused review)

The checklist provides:

• Multi-pass review strategy
• Type-specific focus areas
• What to check and what to skip
• Structured thinking guidance

Step 3: Execute Review with Structured Thinking

Follow the checklist's multi-pass strategy, thinking through each pass systematically.

Step 4: Consult Reference Materials As Needed

Load reference files only when needed for specific questions:

• Issue prioritization → reference/priority-framework.md (Critical vs Suggested vs Optional)
• Phrasing feedback → reference/review-psychology.md (questions vs commands, I-statements)
• Architecture questions → reference/architectural-patterns.md (MVVM, Hilt DI, module org, error handling)
• Security questions (quick reference) → reference/security-patterns.md (common patterns and anti-patterns)
• Security questions (comprehensive) → docs/ARCHITECTURE.md#security (full zero-knowledge architecture)
• Testing questions → reference/testing-patterns.md (unit tests, mocking, null safety)
• UI questions → reference/ui-patterns.md (Compose patterns, theming)
• Style questions → docs/STYLE_AND_BEST_PRACTICES.md

Step 5: Document Findings

CRITICAL: Use inline comments on specific lines, NOT a single large review comment.

Inline Comment Rules:

• Create separate comment for EACH specific issue on the exact line
• Do NOT create one large summary comment with all issues
• Do NOT update existing comments - always create new comments
• This ensures history is retained for other reviewers

Inline Comment Format (Concise with Collapsible Details):

**[Severity]**: [One-line issue description]

<details>
<summary>Details and fix</summary>

[Code example or specific fix]

[Rationale explaining why]

Reference: [docs link if applicable]
</details>

Example inline comment:

**CRITICAL**: Exposes mutable state

<details>
<summary>Details and fix</summary>

Change `MutableStateFlow<State>` to `StateFlow<State>`:

\```kotlin
private val _state = MutableStateFlow<State>()
val state: StateFlow<State> = _state.asStateFlow()
\```

Exposing MutableStateFlow allows external mutation, violating MVVM unidirectional data flow.

Reference: docs/ARCHITECTURE.md#mvvm-pattern
</details>

Summary Comment Format (Minimal - Avoid Duplication):

**Overall Assessment:** APPROVE / REQUEST CHANGES

**Critical Issues** (if any):
- [One-line summary of each critical blocking issue]

See inline comments for all issue details.

Output Format Notes:

What to Include:

• Inline comments: Create separate comment for EACH specific issue with full details in <details> tag
• Summary comment: Overall assessment (APPROVE/REQUEST CHANGES) + list of CRITICAL issues only
• Severity levels: Use CRITICAL (blocking), IMPORTANT (should fix), SUGGESTED (nice to have), or ACKNOWLEDGED (good practice observed)

What to Exclude:

• No duplication: Never repeat inline comment details in the summary
• No Important/Suggested in summary: Only CRITICAL blocking issues belong in summary
• No "Good Practices" section: Acknowledge good practices in inline comments if relevant
• No "Action Items" section: This duplicates inline comments - avoid entirely
• No verbose analysis: Keep detailed analysis (compilation status, security review, rollback plans) in inline comments only

Visibility Guidelines:

• Inline comments visible: Severity + one-line description only
• Inline comments collapsed: Code examples, rationale, references in <details> tag
• Summary visible: Verdict + critical issues list only

See examples/review-outputs.md for complete examples.

Core Principles

• Appropriate depth: Match review rigor to change complexity and risk
• Specific references: Always use file:line_number format for precise location
• Actionable feedback: Say what to do and why, not just what's wrong
• Constructive tone: Ask questions for design decisions, explain rationale, focus on code not people
• Efficient reviews: Use multi-pass strategy, time-box reviews, skip what's not relevant