@aaronshaf/ger 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronshaf/ger",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "module": "index.ts",
   "type": "module",
   "bin": {

package/src/cli/commands/review.ts

@@ -1,4 +1,4 @@
-import { Effect, pipe, Schema } from 'effect'
+import { Effect, pipe, Schema, Layer } from 'effect'
 import { AiService } from '@/services/ai'
 import { commentCommandWithInput } from './comment'
 import { Console } from 'effect'
@@ -7,6 +7,13 @@ import type { CommentInfo } from '@/schemas/gerrit'
 import { sanitizeCDATA, escapeXML } from '@/utils/shell-safety'
 import { formatDiffPretty } from '@/utils/diff-formatters'
 import { formatDate } from '@/utils/formatters'
+import {
+  formatChangeAsXML,
+  formatCommentsAsXML,
+  formatMessagesAsXML,
+  flattenComments,
+} from '@/utils/review-formatters'
+import { buildEnhancedPrompt } from '@/utils/review-prompt-builder'
 import * as fs from 'node:fs/promises'
 import * as fsSync from 'node:fs'
 import * as os from 'node:os'
@@ -14,6 +21,7 @@ import * as path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { dirname } from 'node:path'
 import * as readline from 'node:readline'
+import { GitWorktreeService, GitWorktreeServiceLive } from '@/services/git-worktree'
 
 // Get the directory of this module
 const __filename = fileURLToPath(import.meta.url)
@@ -178,7 +186,7 @@ const validateAndFixInlineComments = (
     return validComments
   })
 
-// Helper to get change data and format as XML string
+// Legacy helper for backward compatibility (will be removed)
 const getChangeDataAsXml = (changeId: string): Effect.Effect<string, ApiError, GerritApiService> =>
   Effect.gen(function* () {
     const gerritApi = yield* GerritApiService
@@ -190,83 +198,17 @@ const getChangeDataAsXml = (changeId: string): Effect.Effect<string, ApiError, G
     const commentsMap = yield* gerritApi.getComments(changeId)
     const messages = yield* gerritApi.getMessages(changeId)
 
-    // Flatten comments from all files
-    const comments: CommentInfo[] = []
-    for (const [path, fileComments] of Object.entries(commentsMap)) {
-      for (const comment of fileComments) {
-        comments.push({ ...comment, path })
-      }
-    }
+    const comments = flattenComments(commentsMap)
 
-    // Build XML string
+    // Build XML string using helper functions
     const xmlLines: string[] = []
     xmlLines.push(`<?xml version="1.0" encoding="UTF-8"?>`)
     xmlLines.push(`<show_result>`)
     xmlLines.push(`  <status>success</status>`)
-    xmlLines.push(`  <change>`)
-    xmlLines.push(`    <id>${escapeXML(change.change_id)}</id>`)
-    xmlLines.push(`    <number>${change._number}</number>`)
-    xmlLines.push(`    <subject><![CDATA[${sanitizeCDATA(change.subject)}]]></subject>`)
-    xmlLines.push(`    <status>${escapeXML(change.status)}</status>`)
-    xmlLines.push(`    <project>${escapeXML(change.project)}</project>`)
-    xmlLines.push(`    <branch>${escapeXML(change.branch)}</branch>`)
-    xmlLines.push(`    <owner>`)
-    if (change.owner?.name) {
-      xmlLines.push(`      <name><![CDATA[${sanitizeCDATA(change.owner.name)}]]></name>`)
-    }
-    if (change.owner?.email) {
-      xmlLines.push(`      <email>${escapeXML(change.owner.email)}</email>`)
-    }
-    xmlLines.push(`    </owner>`)
-    xmlLines.push(`    <created>${escapeXML(change.created || '')}</created>`)
-    xmlLines.push(`    <updated>${escapeXML(change.updated || '')}</updated>`)
-    xmlLines.push(`  </change>`)
+    xmlLines.push(...formatChangeAsXML(change))
     xmlLines.push(`  <diff><![CDATA[${sanitizeCDATA(diff)}]]></diff>`)
-
-    // Comments section
-    xmlLines.push(`  <comments>`)
-    xmlLines.push(`    <count>${comments.length}</count>`)
-    for (const comment of comments) {
-      xmlLines.push(`    <comment>`)
-      if (comment.id) xmlLines.push(`      <id>${escapeXML(comment.id)}</id>`)
-      if (comment.path)
-        xmlLines.push(`      <path><![CDATA[${sanitizeCDATA(comment.path)}]]></path>`)
-      if (comment.line) xmlLines.push(`      <line>${comment.line}</line>`)
-      if (comment.author?.name) {
-        xmlLines.push(`      <author><![CDATA[${sanitizeCDATA(comment.author.name)}]]></author>`)
-      }
-      if (comment.updated) xmlLines.push(`      <updated>${escapeXML(comment.updated)}</updated>`)
-      if (comment.message) {
-        xmlLines.push(`      <message><![CDATA[${sanitizeCDATA(comment.message)}]]></message>`)
-      }
-      if (comment.unresolved) xmlLines.push(`      <unresolved>true</unresolved>`)
-      xmlLines.push(`    </comment>`)
-    }
-    xmlLines.push(`  </comments>`)
-
-    // Messages section
-    xmlLines.push(`  <messages>`)
-    xmlLines.push(`    <count>${messages.length}</count>`)
-    for (const message of messages) {
-      xmlLines.push(`    <message>`)
-      xmlLines.push(`      <id>${escapeXML(message.id)}</id>`)
-      if (message.author?.name) {
-        xmlLines.push(`      <author><![CDATA[${sanitizeCDATA(message.author.name)}]]></author>`)
-      }
-      if (message.author?._account_id) {
-        xmlLines.push(`      <author_id>${message.author._account_id}</author_id>`)
-      }
-      xmlLines.push(`      <date>${escapeXML(message.date)}</date>`)
-      if (message._revision_number) {
-        xmlLines.push(`      <revision>${message._revision_number}</revision>`)
-      }
-      if (message.tag) {
-        xmlLines.push(`      <tag>${escapeXML(message.tag)}</tag>`)
-      }
-      xmlLines.push(`      <message><![CDATA[${sanitizeCDATA(message.message)}]]></message>`)
-      xmlLines.push(`    </message>`)
-    }
-    xmlLines.push(`  </messages>`)
+    xmlLines.push(...formatCommentsAsXML(comments))
+    xmlLines.push(...formatMessagesAsXML(messages))
     xmlLines.push(`</show_result>`)
 
     return xmlLines.join('\n')
@@ -286,13 +228,7 @@ const getChangeDataAsPretty = (
     const commentsMap = yield* gerritApi.getComments(changeId)
     const messages = yield* gerritApi.getMessages(changeId)
 
-    // Flatten comments from all files
-    const comments: CommentInfo[] = []
-    for (const [path, fileComments] of Object.entries(commentsMap)) {
-      for (const comment of fileComments) {
-        comments.push({ ...comment, path })
-      }
-    }
+    const comments = flattenComments(commentsMap)
 
     // Build pretty string
     const lines: string[] = []
@@ -379,18 +315,22 @@ const promptUser = (message: string): Effect.Effect<boolean, never> =>
 export const reviewCommand = (changeId: string, options: ReviewOptions = {}) =>
   Effect.gen(function* () {
     const aiService = yield* AiService
+    const gitService = yield* GitWorktreeService
 
     // Load default prompts first
     const prompts = yield* loadDefaultPrompts
 
-    // Check for AI tool availability first
+    // Validate preconditions
+    yield* gitService.validatePreconditions()
+
+    // Check for AI tool availability
     yield* Console.log('→ Checking for AI tool availability...')
     const aiTool = yield* aiService
       .detectAiTool()
       .pipe(Effect.catchTag('NoAiToolFoundError', (error) => Effect.fail(new Error(error.message))))
     yield* Console.log(`✓ Found AI tool: ${aiTool}`)
 
-    // Load custom review prompt if provided via --prompt option
+    // Load custom review prompt if provided
     let userReviewPrompt = prompts.defaultReviewPrompt
 
     if (options.prompt) {
@@ -404,81 +344,175 @@ export const reviewCommand = (changeId: string, options: ReviewOptions = {}) =>
       }
     }
 
-    // Combine user prompt with system prompts for each stage
-    const inlinePrompt = `${userReviewPrompt}\n\n${prompts.inlineReviewSystemPrompt}`
-    const overallPrompt = `${userReviewPrompt}\n\n${prompts.overallReviewSystemPrompt}`
+    // Use Effect's resource management for worktree lifecycle
+    yield* Effect.acquireUseRelease(
+      // Acquire: Create worktree and setup
+      Effect.gen(function* () {
+        const worktreeInfo = yield* gitService.createWorktree(changeId)
+        yield* gitService.fetchAndCheckoutPatchset(worktreeInfo)
+        return worktreeInfo
+      }),
+
+      // Use: Run the enhanced review process
+      (worktreeInfo) =>
+        Effect.gen(function* () {
+          // Switch to worktree directory
+          const originalCwd = process.cwd()
+          process.chdir(worktreeInfo.path)
+
+          try {
+            // Get changed files from git
+            const changedFiles = yield* gitService.getChangedFiles()
+
+            yield* Console.log(`→ Found ${changedFiles.length} changed files`)
+            if (options.debug) {
+              yield* Console.log(`[DEBUG] Changed files: ${changedFiles.join(', ')}`)
+            }
+
+            // Stage 1: Generate inline comments
+            yield* Console.log(`→ Generating inline comments for change ${changeId}...`)
+
+            const inlinePrompt = yield* buildEnhancedPrompt(
+              userReviewPrompt,
+              prompts.inlineReviewSystemPrompt,
+              changeId,
+              changedFiles,
+            )
 
-    yield* Console.log(`→ Fetching change data for ${changeId}...`)
+            if (options.debug) {
+              yield* Console.log('[DEBUG] Running AI for inline comments...')
+              yield* Console.log(`[DEBUG] Working directory: ${worktreeInfo.path}`)
+            }
+
+            // Run inline review with worktree as working directory
+            const inlineResponse = yield* aiService
+              .runPrompt(inlinePrompt, '', { cwd: worktreeInfo.path })
+              .pipe(
+                Effect.catchTag('AiResponseParseError', (error) =>
+                  Effect.gen(function* () {
+                    yield* Console.error(`✗ Failed to parse AI response: ${error.message}`)
+                    yield* Console.error('Raw AI output:')
+                    yield* Console.error('-'.repeat(80))
+                    yield* Console.error(error.rawOutput || 'No output captured')
+                    yield* Console.error('-'.repeat(80))
+                    return yield* Effect.fail(error)
+                  }),
+                ),
+                Effect.catchTag('AiServiceError', (error) =>
+                  Effect.die(new Error(`AI service error: ${error.message}`)),
+                ),
+              )
+
+            if (options.debug) {
+              yield* Console.log(`[DEBUG] Inline response:\n${inlineResponse}`)
+            }
+
+            // Response is already extracted by runPrompt
+            const extractedInlineResponse = inlineResponse
+
+            // Parse JSON array from response
+            const inlineCommentsArray = yield* Effect.tryPromise({
+              try: () => Promise.resolve(JSON.parse(extractedInlineResponse)),
+              catch: (error) => new Error(`Invalid JSON response: ${error}`),
+            }).pipe(
+              Effect.catchAll((error) =>
+                Effect.gen(function* () {
+                  yield* Console.error(`✗ Failed to parse inline comments JSON: ${error}`)
+                  if (!options.debug) {
+                    yield* Console.error('Run with --debug to see raw AI output')
+                  }
+                  return yield* Effect.fail(error)
+                }),
+              ),
+            )
 
-    // Stage 1: Generate inline comments
-    yield* Console.log(`→ Generating inline comments for change ${changeId}...`)
+            // Validate that the response is an array
+            if (!Array.isArray(inlineCommentsArray)) {
+              yield* Console.error('✗ AI response is not an array of comments')
+              return yield* Effect.fail(new Error('Invalid inline comments format'))
+            }
+
+            // Validate and fix inline comments
+            const originalCount = inlineCommentsArray.length
+            const inlineComments = yield* validateAndFixInlineComments(
+              inlineCommentsArray,
+              changedFiles,
+            )
+            const validCount = inlineComments.length
 
-    // Get change data in XML format for inline review
-    const xmlData = yield* getChangeDataAsXml(changeId)
+            if (originalCount > validCount) {
+              yield* Console.log(
+                `→ Filtered ${originalCount - validCount} invalid comments, ${validCount} remain`,
+              )
+            }
 
-    if (options.debug) {
-      yield* Console.log('[DEBUG] Running AI for inline comments...')
-    }
+            // Handle inline comments output/posting
+            yield* handleInlineComments(inlineComments, changeId, options)
 
-    // Run inline review
-    const inlineResponse = yield* aiService.runPrompt(inlinePrompt, xmlData).pipe(
-      Effect.catchTag('AiResponseParseError', (error) =>
-        Effect.gen(function* () {
-          if (options.debug) {
-            yield* Console.error(`[DEBUG] AI output:\n${error.rawOutput}`)
-          }
-          return yield* Effect.fail(error)
-        }),
-      ),
-      Effect.catchTag('AiServiceError', (error) =>
-        Effect.die(new Error(`AI service error: ${error.message}`)),
-      ),
-    )
+            // Stage 2: Generate overall review comment
+            yield* Console.log(`→ Generating overall review comment for change ${changeId}...`)
 
-    if (options.debug) {
-      yield* Console.log(`[DEBUG] Inline response:\n${inlineResponse}`)
-    }
+            const overallPrompt = yield* buildEnhancedPrompt(
+              userReviewPrompt,
+              prompts.overallReviewSystemPrompt,
+              changeId,
+              changedFiles,
+            )
 
-    // Parse JSON array from response using Effect
-    const inlineCommentsArray = yield* Effect.tryPromise({
-      try: () => Promise.resolve(JSON.parse(inlineResponse)),
-      catch: (error) => new Error(`Invalid JSON response: ${error}`),
-    }).pipe(
-      Effect.catchAll((error) =>
-        Effect.gen(function* () {
-          yield* Console.error(`✗ Failed to parse inline comments JSON: ${error}`)
-          if (!options.debug) {
-            yield* Console.error('Run with --debug to see raw AI output')
+            if (options.debug) {
+              yield* Console.log('[DEBUG] Running AI for overall review...')
+            }
+
+            // Run overall review
+            const overallResponse = yield* aiService
+              .runPrompt(overallPrompt, '', { cwd: worktreeInfo.path })
+              .pipe(
+                Effect.catchTag('AiResponseParseError', (error) =>
+                  Effect.gen(function* () {
+                    yield* Console.error(`✗ Failed to parse AI response: ${error.message}`)
+                    yield* Console.error('Raw AI output:')
+                    yield* Console.error('-'.repeat(80))
+                    yield* Console.error(error.rawOutput || 'No output captured')
+                    yield* Console.error('-'.repeat(80))
+                    return yield* Effect.fail(error)
+                  }),
+                ),
+                Effect.catchTag('AiServiceError', (error) =>
+                  Effect.die(new Error(`AI service error: ${error.message}`)),
+                ),
+              )
+
+            if (options.debug) {
+              yield* Console.log(`[DEBUG] Overall response:\n${overallResponse}`)
+            }
+
+            // Response is already extracted by runPrompt
+            const extractedOverallResponse = overallResponse
+
+            // Handle overall review output/posting
+            yield* handleOverallReview(extractedOverallResponse, changeId, options)
+          } finally {
+            // Always restore original working directory
+            process.chdir(originalCwd)
           }
-          return yield* Effect.fail(error)
-        }),
-      ),
-    )
-
-    // Validate that the response is an array
-    if (!Array.isArray(inlineCommentsArray)) {
-      yield* Console.error('✗ AI response is not an array of comments')
-      return yield* Effect.fail(new Error('Invalid inline comments format'))
-    }
-
-    // Get available files for validation
-    const gerritApi = yield* GerritApiService
-    const files = yield* gerritApi.getFiles(changeId)
-    const availableFiles = Object.keys(files)
 
-    // Validate and fix inline comments
-    const originalCount = inlineCommentsArray.length
-    const inlineComments = yield* validateAndFixInlineComments(inlineCommentsArray, availableFiles)
-    const validCount = inlineComments.length
+          yield* Console.log(`✓ Review complete for ${changeId}`)
+        }),
 
-    if (originalCount > validCount) {
-      yield* Console.log(
-        `→ Filtered ${originalCount - validCount} invalid comments, ${validCount} remain`,
-      )
-    }
+      // Release: Always cleanup worktree
+      (worktreeInfo) => gitService.cleanup(worktreeInfo),
+    )
+  })
 
-    // If not in comment mode, just output the inline comments
+// Helper function to handle inline comments output/posting
+const handleInlineComments = (
+  inlineComments: InlineComment[],
+  changeId: string,
+  options: ReviewOptions,
+): Effect.Effect<void, Error, GerritApiService> =>
+  Effect.gen(function* () {
     if (!options.comment) {
+      // Display mode
       if (inlineComments.length > 0) {
         yield* Console.log('\n━━━━━━ INLINE COMMENTS ━━━━━━')
         for (const comment of inlineComments) {
@@ -489,7 +523,7 @@ export const reviewCommand = (changeId: string, options: ReviewOptions = {}) =>
         yield* Console.log('\n→ No inline comments')
       }
     } else {
-      // In comment mode, handle posting
+      // Comment posting mode
       if (inlineComments.length > 0) {
         yield* Console.log('\n━━━━━━ INLINE COMMENTS TO POST ━━━━━━')
         for (const comment of inlineComments) {
@@ -498,27 +532,20 @@ export const reviewCommand = (changeId: string, options: ReviewOptions = {}) =>
         }
         yield* Console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
 
-        // Ask for confirmation unless --yes is provided
-        const shouldPost = options.yes
-          ? true
-          : yield* promptUser('\nPost these inline comments to Gerrit?')
+        const shouldPost =
+          options.yes || (yield* promptUser('\nPost these inline comments to Gerrit?'))
 
         if (shouldPost) {
-          if (inlineComments.length === 0) {
-            yield* Console.log('→ No valid comments to post after validation')
-          } else {
-            // Post inline comments using the new direct input method
-            yield* pipe(
-              commentCommandWithInput(changeId, JSON.stringify(inlineComments), { batch: true }),
-              Effect.catchAll((error) =>
-                Effect.gen(function* () {
-                  yield* Console.error(`✗ Failed to post inline comments: ${error}`)
-                  return yield* Effect.fail(error)
-                }),
-              ),
-            )
-            yield* Console.log(`✓ Inline comments posted for ${changeId}`)
-          }
+          yield* pipe(
+            commentCommandWithInput(changeId, JSON.stringify(inlineComments), { batch: true }),
+            Effect.catchAll((error) =>
+              Effect.gen(function* () {
+                yield* Console.error(`✗ Failed to post inline comments: ${error}`)
+                return yield* Effect.fail(error)
+              }),
+            ),
+          )
+          yield* Console.log(`✓ Inline comments posted for ${changeId}`)
         } else {
           yield* Console.log('→ Inline comments not posted')
         }
@@ -526,54 +553,29 @@ export const reviewCommand = (changeId: string, options: ReviewOptions = {}) =>
         yield* Console.log('\n→ No valid inline comments to post')
       }
     }
+  })
 
-    // Stage 2: Generate overall review comment
-    yield* Console.log(`→ Generating overall review comment for change ${changeId}...`)
-
-    // Get change data in regular format for overall review
-    const prettyData = yield* getChangeDataAsPretty(changeId)
-
-    if (options.debug) {
-      yield* Console.log('[DEBUG] Running AI for overall review...')
-    }
-
-    // Run overall review
-    const overallResponse = yield* aiService.runPrompt(overallPrompt, prettyData).pipe(
-      Effect.catchTag('AiResponseParseError', (error) =>
-        Effect.gen(function* () {
-          if (options.debug) {
-            yield* Console.error(`[DEBUG] AI output:\n${error.rawOutput}`)
-          }
-          return yield* Effect.fail(error)
-        }),
-      ),
-      Effect.catchTag('AiServiceError', (error) =>
-        Effect.die(new Error(`AI service error: ${error.message}`)),
-      ),
-    )
-
-    if (options.debug) {
-      yield* Console.log(`[DEBUG] Overall response:\n${overallResponse}`)
-    }
-
-    // If not in comment mode, just output the review
+// Helper function to handle overall review output/posting
+const handleOverallReview = (
+  overallResponse: string,
+  changeId: string,
+  options: ReviewOptions,
+): Effect.Effect<void, Error, GerritApiService> =>
+  Effect.gen(function* () {
     if (!options.comment) {
+      // Display mode
       yield* Console.log('\n━━━━━━ OVERALL REVIEW ━━━━━━')
       yield* Console.log(overallResponse)
       yield* Console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
     } else {
-      // In comment mode, handle posting
+      // Comment posting mode
       yield* Console.log('\n━━━━━━ OVERALL REVIEW TO POST ━━━━━━')
       yield* Console.log(overallResponse)
       yield* Console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
 
-      // Ask for confirmation unless --yes is provided
-      const shouldPost = options.yes
-        ? true
-        : yield* promptUser('\nPost this overall review to Gerrit?')
+      const shouldPost = options.yes || (yield* promptUser('\nPost this overall review to Gerrit?'))
 
       if (shouldPost) {
-        // Post overall comment using the new direct input method
         yield* pipe(
           commentCommandWithInput(changeId, overallResponse, {}),
           Effect.catchAll((error) =>
@@ -588,6 +590,4 @@ export const reviewCommand = (changeId: string, options: ReviewOptions = {}) =>
         yield* Console.log('→ Overall review not posted')
       }
     }
-
-    yield* Console.log(`✓ Review complete for ${changeId}`)
   })

package/src/cli/index.ts

@@ -26,6 +26,7 @@ import { Effect } from 'effect'
 import { GerritApiServiceLive } from '@/api/gerrit'
 import { ConfigServiceLive } from '@/services/config'
 import { AiServiceLive } from '@/services/ai-enhanced'
+import { GitWorktreeServiceLive } from '@/services/git-worktree'
 import { abandonCommand } from './commands/abandon'
 import { commentCommand } from './commands/comment'
 import { commentsCommand } from './commands/comments'
@@ -409,6 +410,7 @@ Examples:
         Effect.provide(AiServiceLive),
         Effect.provide(GerritApiServiceLive),
         Effect.provide(ConfigServiceLive),
+        Effect.provide(GitWorktreeServiceLive),
       )
       await Effect.runPromise(effect)
     } catch (error) {

package/src/prompts/default-review.md

@@ -1,22 +1,23 @@
-# Code Review Guidelines
+# Engineering Code Review - Signal Over Noise
 
-You are reviewing a Gerrit change set. Provide thorough, constructive feedback focused on technical excellence and maintainability.
+You are conducting a technical code review for experienced engineers. **PRIORITY: Find actual problems, not generate busy work.**
 
-## Review Philosophy
+## Core Principles
 
-1. **Understand First, Critique Second**
-   - Fully comprehend the author's intent before identifying issues
-   - Read COMPLETE files, not just diffs
-   - Check if apparent issues are handled elsewhere in the change
-   - Consider the broader architectural context
-   - Verify you're reviewing the LATEST patchset version
+**SIGNAL > NOISE**: Only comment on issues that materially impact correctness, security, performance, or maintainability. Silence is better than noise.
 
-2. **Be Direct and Constructive**
-   - Focus on substantive technical concerns
-   - Explain WHY something is problematic, not just what
-   - Provide actionable suggestions when identifying issues
-   - Assume the author has domain expertise
-   - Ask clarifying questions when intent is unclear
+**NO PRAISE NEEDED**: Don't compliment good code. Engineers expect competent code by default.
+
+**EMPTY RESPONSES ARE VALID**: Small changes without issues should result in empty inline comments. The overall review can simply note "No significant issues found."
+
+**FOCUS ON REAL PROBLEMS**: 
+- Bugs that will cause runtime failures
+- Security vulnerabilities 
+- Performance bottlenecks
+- Architectural mistakes
+- Missing error handling
+
+**ASSUME COMPETENCE**: The author is an experienced engineer who made intentional decisions. Question only when you see genuine problems.
 
 ## Review Categories (Priority Order)
 
@@ -47,34 +48,39 @@ You are reviewing a Gerrit change set. Provide thorough, constructive feedback f
 - **Clarity**: Code that works but could be more readable
 - **Future-Proofing**: Anticipating likely future requirements
 
-## What NOT to Review
+## What NOT to Review (Common Time Wasters)
+
+- **Code style/formatting**: Handled by automated tools
+- **Personal preferences**: Different != wrong
+- **Compliments**: "Looks good!" wastes everyone's time
+- **Nitpicks**: Minor wording, variable names, spacing
+- **Micro-optimizations**: Unless there's a proven performance problem
+- **Already working code**: If it works and isn't broken, don't fix it
+- **Suggestions for "better" approaches**: Only if current approach has concrete problems
 
-- **Already Fixed**: Issues resolved in the current patchset
-- **Style Preferences**: Formatting that doesn't impact readability
-- **Micro-Optimizations**: Unless performance is a stated goal
-- **Personal Preferences**: Unless they violate team standards
-- **Out of Scope**: Issues in unchanged code (unless directly relevant)
+## Before Commenting, Ask Yourself
 
-## Context Requirements
+1. **Will this cause a runtime failure?** → Critical issue, comment required
+2. **Will this create a security vulnerability?** → Critical issue, comment required  
+3. **Will this significantly harm performance?** → Important issue, comment required
+4. **Will this make the code unmaintainable?** → Consider commenting
+5. **Is this just a different way to solve the same problem?** → Skip it
 
-Before commenting, verify:
-1. The issue still exists in the current patchset
-2. The fix wouldn't break other functionality
-3. Your understanding of the code's purpose is correct
-4. The issue isn't intentional or documented
-5. The concern is worth the author's time to address
+## Output Guidelines
 
-## Inline Comment Guidelines
+**INLINE COMMENTS**: Only for specific line-level issues. Empty array is perfectly valid.
+- Start with "🤖 "
+- Be direct: "This will cause X bug" not "Consider maybe perhaps changing this"
+- Provide specific fixes when possible
 
-- Start each comment with "🤖 " (robot emoji with space)
-- Be specific about file paths and line numbers
-- Group related issues when they share a root cause
-- Provide concrete examples or corrections when helpful
-- Use questions for clarification, statements for clear issues
+**OVERALL REVIEW**: Required even if no inline comments.
+- For clean code: "No significant issues found. Change is ready."
+- For problematic code: Focus on the most important issues only
+- Skip the pleasantries, get to the point
 
-## Remember
+## Success Metrics
 
-- The goal is to improve code quality while respecting the author's time
-- Focus on issues that matter for correctness, security, and maintainability
-- Your review should help ship better code, not perfect code
-- When in doubt, phrase feedback as a question rather than a mandate
+- **Good review**: Finds 1-3 real issues that would cause problems
+- **Great review**: Catches a critical bug before production
+- **Bad review**: 10+ nitpicky comments about style preferences
+- **Terrible review**: "Great job! LGTM!" with zero value added