Optimize reviewing-changes skill (#6099)

Co-authored-by: Claude <[email protected]>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: 3 people

.claude/prompts/review-code.md

@@ -2,19 +2,10 @@ Use the `reviewing-changes` skill to review this pull request.
 
 The PR branch is already checked out in the current working directory.
 
-Provide a comprehensive review including:
+CRITICAL: Create inline comments on specific lines for each issue. Do NOT create one large review comment.
 
-- Summary of changes since last review
-- Critical issues found (be thorough)
-- Suggested improvements (be thorough)
-- Good practices observed (be concise - list only the most notable items without elaboration)
-- Action items for the author
-- Leverage collapsible <details> sections where appropriate for lengthy explanations or code snippets
-
-When reviewing subsequent commits:
-
-- Track status of previously identified issues (fixed/unfixed/reopened)
-- Identify NEW problems introduced since last review
-- Note if fixes introduced new issues
-
-IMPORTANT: Be comprehensive about issues and improvements. For good practices, be brief - just note what was done well without explaining why or praising excessively.
+Output Format:
+- Create separate inline comment for each specific issue/recommendation
+- Summary comment for overall assessment
+- Track status of previously identified issues if this is a subsequent review
+- Use collapsible <details> sections in inline comments for lengthy code examples

.claude/skills/reviewing-changes/SKILL.md

@@ -1,110 +1,169 @@
 ---
 name: reviewing-changes
-description: Performs comprehensive code reviews for Bitwarden Android projects, verifying architecture compliance, style guidelines, compilation safety, test coverage, and security requirements. Use when reviewing pull requests, checking commits, analyzing code changes, verifying Bitwarden coding standards, evaluating MVVM patterns, checking Hilt DI usage, reviewing security implementations, or assessing test coverage. Automatically invoked by CI pipeline or manually for interactive code reviews.
+version: 2.0.0
+description: Comprehensive code reviews for Bitwarden Android. Detects change type (dependency update, bug fix, feature, UI, refactoring, infrastructure) and applies appropriate review depth. Validates MVVM patterns, Hilt DI, security requirements, and test coverage per project standards. Use when reviewing pull requests, checking commits, analyzing code changes, or evaluating architectural compliance.
 ---
 
 # Reviewing Changes
 
 ## Instructions
 
-Follow this process to review code changes for Bitwarden Android:
-
-### Step 1: Understand Context
-
-Start with high-level assessment of the change's purpose and approach. Read PR/commit descriptions and understand what problem is being solved.
-
-### Step 2: Verify Compliance
-
-Systematically check each area against Bitwarden standards documented in `CLAUDE.md`:
-
-1. **Architecture**: Follow patterns in `docs/ARCHITECTURE.md`
-   - MVVM + UDF (ViewModels with `StateFlow`, Compose UI)
-   - Hilt DI (interface injection, `@HiltViewModel`)
-   - Repository pattern and proper data flow
-
-2. **Style**: Adhere to `docs/STYLE_AND_BEST_PRACTICES.md`
-   - Naming conventions, code organization, formatting
-   - Kotlin idioms (immutability, null safety, coroutines)
-
-3. **Compilation**: Analyze for potential build issues
-   - Import statements and dependencies
-   - Type safety and null safety
-   - API compatibility and deprecation warnings
-   - Resource references and manifest requirements
-
-4. **Testing**: Verify appropriate test coverage
-   - Unit tests for business logic and utility functions
-   - Integration tests for complex workflows
-   - UI tests for user-facing features when applicable
-   - Test coverage for edge cases and error scenarios
-
-5. **Security**: Given Bitwarden's security-focused nature
-   - Proper handling of sensitive data
-   - Secure storage practices (Android Keystore)
-   - Authentication and authorization patterns
-   - Data encryption and decryption flows
-   - Zero-knowledge architecture preservation
+**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
+
+<thinking>
+Analyze the changeset systematically:
+1. What files were modified? (code vs config vs docs)
+2. What is the PR/commit title indicating?
+3. Is there new functionality or just modifications?
+4. What's the risk level of these changes?
+</thinking>
+
+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
+
+<thinking>
+Before diving into details:
+1. What are the highest-risk areas of this change?
+2. Which architectural patterns need verification?
+3. What security implications exist?
+4. How should I prioritize my findings?
+5. What tone is appropriate for this feedback?
+</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
+
+<thinking>
+Before writing each comment:
+1. Is this issue Critical, Important, Suggested, or just Acknowledgment?
+2. Should I ask a question or provide direction?
+3. What's the rationale I need to explain?
+4. What code example would make this actionable?
+5. Is there a documentation reference to include?
+</thinking>
+
+**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]
 
-### Step 3: Document Findings
+<details>
+<summary>Details and fix</summary>
 
-Identify specific violations with `file:line_number` references. Be precise about locations.
+[Code example or specific fix]
 
-### Step 4: Provide Recommendations
+[Rationale explaining why]
 
-Give actionable recommendations for improvements. Explain why changes are needed and suggest specific solutions.
+Reference: [docs link if applicable]
+</details>
+```
 
-### Step 5: Flag Critical Issues
+**Example inline comment**:
+```
+**CRITICAL**: Exposes mutable state
 
-Highlight issues that must be addressed before merge. Distinguish between blockers and suggestions.
+<details>
+<summary>Details and fix</summary>
 
-### Step 6: Acknowledge Quality
+Change `MutableStateFlow<State>` to `StateFlow<State>`:
 
-Note well-implemented patterns (briefly, without elaboration). Keep positive feedback concise.
+\```kotlin
+private val _state = MutableStateFlow<State>()
+val state: StateFlow<State> = _state.asStateFlow()
+\```
 
-## Review Anti-Patterns (DO NOT)
+Exposing MutableStateFlow allows external mutation, violating MVVM unidirectional data flow.
 
-- Be nitpicky about linter-catchable style issues
-- Review without understanding context - ask for clarification first
-- Focus only on new code - check surrounding context for issues
-- Request changes outside the scope of this changeset
+Reference: docs/ARCHITECTURE.md#mvvm-pattern
+</details>
+```
 
-## Examples
+**Summary Comment Format** (Minimal - Avoid Duplication):
+```
+**Overall Assessment:** APPROVE / REQUEST CHANGES
 
-### Good Review Format
+**Critical Issues** (if any):
+- [One-line summary of each critical blocking issue]
 
-```markdown
-## Summary
-This PR adds biometric authentication to the login flow, implementing MVVM pattern with proper state management.
+See inline comments for all issue details.
+```
 
-## Critical Issues
-- `app/login/LoginViewModel.kt:45` - Mutable state exposed; use `StateFlow` instead of `MutableStateFlow`
-- `data/auth/BiometricRepository.kt:120` - Missing null safety check on `biometricPrompt` result
+**Output Format Notes**:
 
-## Suggested Improvements
-- Consider extracting biometric prompt logic to separate use case class
-- Add integration tests for biometric failure scenarios
-- `app/login/LoginScreen.kt:89` - Consider using existing `BitwardenButton` component
+**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)
 
-## Good Practices
-- Proper Hilt DI usage throughout
-- Comprehensive unit test coverage
-- Clear separation of concerns
+**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
 
-## Action Items
-1. Fix mutable state exposure in `LoginViewModel`
-2. Add null safety check in `BiometricRepository`
-3. Consider adding integration tests for error flows
-```
+**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
 
-### What to Focus On
+See `examples/review-outputs.md` for complete examples.
 
-**DO focus on:**
-- Architecture violations (incorrect patterns)
-- Security issues (data handling, encryption)
-- Missing tests for critical paths
-- Compilation risks (type safety, null safety)
+## Core Principles
 
-**DON'T focus on:**
-- Minor formatting (handled by linters)
-- Personal preferences without architectural basis
-- Issues outside the changeset scope
+- **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