cleo_quality_review 0.2.0 → 0.4.0

data/lib/cleo_quality_review/incremental_base_resolver.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "github_client"
+require_relative "llm_errors"
+
+module CleoQualityReview
+  ##
+  # Resolves the git base for an incremental review.
+  #
+  # On a pull request that cleo-quality-review has already reviewed, this
+  # returns the most recent previously-reviewed commit that is still an
+  # ancestor of the current head, so only changes made since that review are
+  # analysed. It falls back to +nil+ (meaning "review the full diff") outside a
+  # pull request context, when no prior review survives in history, or on any
+  # lookup error.
+  class IncrementalBaseResolver
+    REVIEW_MARKER_PREFIX = "<!-- cleo-quality-review:"
+    DISABLED_VALUES = %w[0 false no off].freeze
+    ENABLED_ENV_KEY = "CLEO_QUALITY_REVIEW_INCREMENTAL"
+    REVIEWS_PER_PAGE = 100
+    MAX_REVIEW_PAGES = 20
+
+    ##
+    # @param [CommandRunner] command_runner for executing git commands
+    # @param [Hash{String => String}] env process environment
+    # @param [GitHubClient, nil] client GitHub API client (built from env when omitted)
+    def initialize(command_runner:, env: ENV, client: nil)
+      @command_runner = command_runner
+      @env = env
+      @client = client
+    end
+
+    ##
+    # Resolve the incremental base commit.
+    # @param [String] head git ref for the current head
+    # @return [String, nil] commit SHA to diff against, or nil to review the full diff
+    def resolve(head: "HEAD")
+      return nil unless incremental_lookup_available?
+
+      newest_reviewed_ancestor(head)
+    rescue StandardError => error
+      warn("cleo-quality-review: incremental base lookup failed (#{error.message}); reviewing the full diff")
+      nil
+    end
+
+    private
+
+    attr_reader :command_runner, :env
+
+    ##
+    # @return [Boolean] whether an incremental lookup can run in this context
+    def incremental_lookup_available?
+      enabled? && !pull_request_number.nil? && !token.nil? && !repository.nil?
+    end
+
+    def newest_reviewed_ancestor(head)
+      reviewed_commit_ids.find { |sha| ancestor?(sha, head) }
+    end
+
+    def reviewed_commit_ids
+      reviews
+        .select { |review| quality_review?(review) }
+        .sort_by { |review| review["submitted_at"].to_s }
+        .reverse
+        .filter_map { |review| review["commit_id"] }
+        .reject { |sha| sha.to_s.strip.empty? }
+        .uniq
+    end
+
+    ##
+    # Fetch every submitted review, following pagination so the newest reviews
+    # are not missed on pull requests with more than one page of reviews.
+    # @return [Array<Hash>]
+    def reviews
+      (1..MAX_REVIEW_PAGES).each_with_object([]) do |page, all|
+        page_reviews = reviews_page(page)
+        all.concat(page_reviews)
+        break all if page_reviews.length < REVIEWS_PER_PAGE
+      end
+    end
+
+    def reviews_page(page)
+      response = client.get("/repos/#{repository}/pulls/#{pull_request_number}/reviews?per_page=#{REVIEWS_PER_PAGE}&page=#{page}")
+      raise Error, "GitHub review lookup returned status #{response.status_code}" unless response.success?
+
+      parsed = JSON.parse(response.body)
+      parsed.is_a?(Array) ? parsed : []
+    end
+
+    ##
+    # Only trust bot-authored reviews that carry our marker. A human contributor
+    # could otherwise forge the marker in their own review and steer the base
+    # past changes the tool never analysed.
+    # @param [Hash] review
+    # @return [Boolean]
+    def quality_review?(review)
+      bot_authored?(review) && marked?(review)
+    end
+
+    def bot_authored?(review)
+      review.dig("user", "type") == "Bot"
+    end
+
+    def marked?(review)
+      review.fetch("body") { "" }.to_s.include?(REVIEW_MARKER_PREFIX)
+    end
+
+    def ancestor?(sha, head)
+      command_runner.run("git", "merge-base", "--is-ancestor", sha, head).success?
+    end
+
+    def enabled?
+      !DISABLED_VALUES.include?(env.fetch(ENABLED_ENV_KEY) { "" }.to_s.strip.downcase)
+    end
+
+    def pull_request_number
+      return @pull_request_number if defined?(@pull_request_number)
+
+      @pull_request_number = event && (event["number"] || event.dig("pull_request", "number"))
+    end
+
+    def event
+      return @event if defined?(@event)
+
+      @event = load_event
+    end
+
+    def load_event
+      path = env["GITHUB_EVENT_PATH"]
+      return nil if path.to_s.empty? || !File.file?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def token
+      value = env["GITHUB_TOKEN"].to_s
+      value unless value.empty?
+    end
+
+    def repository
+      value = env["GITHUB_REPOSITORY"].to_s
+      value unless value.empty?
+    end
+
+    def api_url
+      env.fetch("GITHUB_API_URL") { GitHubClient::DEFAULT_API_URL }
+    end
+
+    def client
+      @client ||= GitHubClient.new(token: token, api_url: api_url)
+    end
+  end
+end

data/lib/cleo_quality_review/llm_client.rb

@@ -19,10 +19,12 @@ module CleoQualityReview
 
     ##
     # Generate a review from the given prompt
-    # @param [String] prompt
+    # @param [String] prompt the format-specific prompt sent as input
+    # @param [String, nil] instructions shared configuration prompt applied to
+    #   every run
     # @return [String] the generated review
-    def generate_review(prompt)
-      generate_with_logging(prompt)
+    def generate_review(prompt, instructions: nil)
+      generate_with_logging(prompt, instructions)
     rescue StandardError => e
       log_error(prompt, e)
       raise
@@ -32,8 +34,10 @@ module CleoQualityReview
 
     attr_reader :config, :logger
 
-    def generate_with_logging(prompt)
-      provider_client.generate_review(prompt).tap { |response| log_success(prompt, response) }
+    def generate_with_logging(prompt, instructions)
+      provider_client.generate_review(prompt, instructions: instructions).tap do |response|
+        log_success(prompt, response)
+      end
     end
 
     def log_success(prompt, response)

data/lib/cleo_quality_review/llm_providers/open_ai.rb

@@ -89,11 +89,13 @@ module CleoQualityReview
 
         ##
         # Generate a review using the OpenAI Responses API.
-        # @param [String] prompt the prompt to send
+        # @param [String] prompt the format-specific prompt to send as input
+        # @param [String, nil] instructions shared configuration prompt sent as
+        #   the system-level instructions applied to every run
         # @return [String] generated review text
         # @raise [ApiError] if the API request fails
-        def generate_review(prompt)
-          response = execute_request(prompt)
+        def generate_review(prompt, instructions: nil)
+          response = execute_request(request_body(prompt, instructions))
           parse_response(response)
         end
 
@@ -101,9 +103,9 @@ module CleoQualityReview
 
         attr_reader :config, :http_transport
 
-        def execute_request(prompt)
+        def execute_request(body)
           timeout_seconds = config.timeout_seconds
-          http_transport.post_json(build_request(prompt, timeout_seconds))
+          http_transport.post_json(build_request(body, timeout_seconds))
         rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
           raise ApiError, timeout_error_message(timeout_seconds, e)
         end
@@ -116,15 +118,21 @@ module CleoQualityReview
           raise ApiError, "OpenAI Responses API returned invalid JSON: #{e.message}"
         end
 
-        def build_request(prompt, timeout_seconds)
+        def build_request(body, timeout_seconds)
           HttpRequest.new(
             uri: RESPONSES_API_URL,
             headers: headers,
-            body: { model: config.model, input: prompt },
+            body: body,
             timeout_seconds: timeout_seconds,
           )
         end
 
+        def request_body(prompt, instructions)
+          body = { model: config.model, input: prompt }
+          body[:instructions] = instructions unless instructions.to_s.strip.empty?
+          body
+        end
+
         def timeout_error_message(timeout_seconds, error)
           "OpenAI Responses API request timed out after #{timeout_seconds} seconds: #{error.class}: #{error.message}"
         end

data/lib/cleo_quality_review/llm_providers/stub.rb

@@ -54,21 +54,25 @@ module CleoQualityReview
       ##
       # Stub LLM client, mirrors OpenAi::Client interface.
       class Client
-        attr_reader :received_prompts
+        attr_reader :received_prompts, :received_instructions
 
         ##
         # @param [Config] config stub configuration
         def initialize(config:)
           @config = config
           @received_prompts = []
+          @received_instructions = []
         end
 
         ##
         # Generate a review by returning the configured response.
-        # @param [String] prompt the prompt sent
+        # @param [String] prompt the format-specific prompt sent as input
+        # @param [String, nil] instructions shared configuration prompt applied
+        #   to every run
         # @return [String] the configured response
-        def generate_review(prompt)
+        def generate_review(prompt, instructions: nil)
           received_prompts << prompt
+          received_instructions << instructions
           response = config.response
 
           case response

data/lib/cleo_quality_review/options.rb

@@ -25,7 +25,9 @@ module CleoQualityReview
     #   @return [Array<String>] checks to exclude
     # @!attribute [r] changed
     #   @return [Boolean] whether to filter to changed files only
-    ParseResult = Struct.new(:format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file, keyword_init: true) do
+    # @!attribute [r] jobs
+    #   @return [Integer, nil] max checks to run in parallel, or nil to auto-size
+    ParseResult = Struct.new(:format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file, :jobs, keyword_init: true) do
       ##
       # @return [String] validated review_id
       # @raise [OptionParser::MissingArgument] if review_id is blank
@@ -64,6 +66,7 @@ module CleoQualityReview
       @log = false
       @review_id = nil
       @review_file = nil
+      @jobs = nil
     end
 
     ##
@@ -85,17 +88,19 @@ module CleoQualityReview
         log: log,
         review_id: review_id,
         review_file: review_file,
+        jobs: jobs,
       )
     end
 
     private
 
-    attr_reader :argv, :format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file
+    attr_reader :argv, :format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file, :jobs
 
     def parser
       OptionParser.new do |opts|
         opts.banner = "Usage: check_quality [options] [files...]"
         register_options(opts)
+        register_help_option(opts)
       end
     end
 
@@ -104,7 +109,13 @@ module CleoQualityReview
       register_check_options(opts)
       register_target_options(opts)
       register_output_options(opts)
-      register_help_option(opts)
+      register_jobs_option(opts)
+    end
+
+    def register_jobs_option(opts)
+      opts.on("-j", "--jobs N", Integer, "Max checks to run in parallel (default: CPU cores)") do |value|
+        @jobs = value
+      end
     end
 
     def register_format_option(opts)
@@ -120,7 +131,7 @@ module CleoQualityReview
     end
 
     def register_checks_option(opts)
-      opts.on("-c", "--checks CHECKS", Array, "Checks to run: all, reek, flog, fasterer, debride") { |values| checks.concat(values) }
+      opts.on("-c", "--checks CHECKS", Array, "Checks to run: all, reek, flog, fasterer") { |values| checks.concat(values) }
     end
 
     def register_only_option(opts)
@@ -128,7 +139,7 @@ module CleoQualityReview
     end
 
     def register_exclude_option(opts)
-      opts.on("-x", "--exclude CHECKS", Array, "Checks to exclude: reek, flog, fasterer, debride") { |values| exclude.concat(values) }
+      opts.on("-x", "--exclude CHECKS", Array, "Checks to exclude: reek, flog, fasterer") { |values| exclude.concat(values) }
     end
 
     def register_target_options(opts)

data/lib/cleo_quality_review/run.rb

@@ -38,6 +38,14 @@ module CleoQualityReview
     :log,
     keyword_init: true,
   ) do
+    ##
+    # Whether the run has any files to review. Runs with no target files
+    # (e.g. a branch that only changes non-Ruby files) have nothing to analyse.
+    # @return [Boolean]
+    def reviewable?
+      !Array(target_files).empty?
+    end
+
     ##
     # Convert the run to a hash representation
     # @return [Hash{Symbol => Object}]

data/lib/cleo_quality_review/runner.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require "digest"
+require "forwardable"
 require "json"
 
 require_relative "changes_diff"
 require_relative "checks"
 require_relative "command_runner"
+require_relative "concurrent_executor"
 require_relative "git_diff_base"
 require_relative "run"
 require_relative "run_artifacts"
@@ -15,6 +17,8 @@ module CleoQualityReview
   ##
   # Orchestrates a complete quality review run
   class Runner
+    extend Forwardable
+
     ##
     # Grouped values resolved at the start of an analysis run
     AnalysisContext = Struct.new(:timestamp, :base_ref, :target, :changes, :review_id, :check_classes, keyword_init: true) do
@@ -32,16 +36,28 @@ module CleoQualityReview
       end
     end
 
+    ##
+    # Runtime collaborators for a quality review run
+    Dependencies = Struct.new(:command_runner, :clock, :check_registry, :base_resolver, :executor, keyword_init: true) do
+      def self.for(options, overrides)
+        new(
+          **{
+            command_runner: CommandRunner.new,
+            clock: Time,
+            check_registry: Checks,
+            base_resolver: nil,
+            executor: ConcurrentExecutor.new(max_workers: options.jobs),
+          }.merge(overrides),
+        )
+      end
+    end
+
     ##
     # @param [Options::ParseResult] options parsed command-line options
-    # @param [CommandRunner] command_runner for executing shell commands
-    # @param [#now] clock time source for timestamps
-    # @param [CheckRegistry] check_registry registry for resolving check names
-    def initialize(options:, command_runner: CommandRunner.new, clock: Time, check_registry: Checks)
+    # @param [Hash] dependencies optional runtime collaborators for tests or alternate runners
+    def initialize(options:, **dependencies)
       @options = options
-      @command_runner = command_runner
-      @clock = clock
-      @check_registry = check_registry
+      @dependencies = Dependencies.for(options, dependencies)
     end
 
     ##
@@ -57,7 +73,9 @@ module CleoQualityReview
 
     private
 
-    attr_reader :options, :command_runner, :clock, :check_registry
+    attr_reader :options, :dependencies
+    def_delegators :dependencies, :command_runner, :clock, :check_registry, :base_resolver, :executor
+    private :command_runner, :clock, :check_registry, :base_resolver, :executor
 
     def epoch_milliseconds
       (clock.now.to_r * 1_000).to_i
@@ -127,7 +145,9 @@ module CleoQualityReview
     end
 
     def run_checks(check_classes, ruby_files, timestamp)
-      check_classes.map do |check_class|
+      return [] if ruby_files.empty?
+
+      executor.map(check_classes) do |check_class|
         check_class.new(command_runner: command_runner, timestamp: timestamp).run(ruby_files)
       end
     end
@@ -170,6 +190,10 @@ module CleoQualityReview
     end
 
     def base_ref
+      @base_ref ||= base_resolver&.resolve || default_base_ref
+    end
+
+    def default_base_ref
       options.base || GitDiffBase::DEFAULT_BASE_REF
     end
   end

data/lib/cleo_quality_review/version.rb

@@ -3,5 +3,5 @@
 module CleoQualityReview
   ##
   # Gem version
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/cleo_quality_review.rb

@@ -14,7 +14,6 @@ module CleoQualityReview
   Checks.register("Reek", Checks::Reek, tool_type: :smell_detection)
   Checks.register("Flog", Checks::Flog, tool_type: :complexity)
   Checks.register("Fasterer", Checks::Fasterer, tool_type: :performance)
-  Checks.register("Debride", Checks::Debride, tool_type: :dead_code)
 
   ##
   # Register all supported LLM APIs for formatting output here

data/prompts/agent.md

@@ -1,13 +1,8 @@
 You are reviewing Ruby code quality findings for consumption by AI coding assistants.
 
-Analyze the raw tool outputs and git diff provided. Prioritize actionable issues affecting maintainability, readability, performance, and complexity. Filter out low-signal findings.
-
-## Tool Thresholds
-
-- **Flog**: Ignore scores below 40.0
-- **Reek**: Focus on FeatureEnvy, TooManyStatements, DuplicateMethodCall, NestedIterators, LongParameterList
-- **Fasterer**: Include all performance suggestions
-- **Debride**: Treat as lower-confidence static dead-code detection. Include only findings that are clearly actionable and avoid recommending deletion without checking dynamic call paths.
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
 ## Output Format
 
@@ -21,7 +16,7 @@ Output valid JSON matching this exact schema:
     "target_files": [<file paths from metadata>],
     "findings": [
       {
-        "tool_name": "<reek|flog|fasterer|debride>",
+        "tool_name": "<reek|flog|fasterer>",
         "tool_type": "<smell_detection|complexity|performance|dead_code>",
         "check": "<specific check type>",
         "filepath": "<relative file path>",
@@ -33,7 +28,7 @@ Output valid JSON matching this exact schema:
   "check_outputs": [
     {
       "check_name": "<check name>",
-      "tool_name": "<reek|flog|fasterer|debride>",
+      "tool_name": "<reek|flog|fasterer>",
       "tool_type": "<smell_detection|complexity|performance|dead_code>",
       "extension": "<json|txt>",
       "path": "<raw output artifact path>",
@@ -44,10 +39,8 @@ Output valid JSON matching this exact schema:
 }
 ```
 
-## Guidelines
+## Output rules
 
-1. Include only findings that exceed thresholds and are actionable
-2. Order findings by priority: high-complexity methods first, then code smells, then performance
-3. Write concise `result` descriptions an agent can act on
-4. Include the raw check outputs in `check_outputs` for reference
-5. Output ONLY valid JSON - no markdown fences, no explanatory text
+1. Write concise `result` descriptions an agent can act on.
+2. Include the raw check outputs in `check_outputs` for reference.
+3. Output ONLY valid JSON - no markdown fences, no explanatory text.

data/prompts/configuration.md

@@ -0,0 +1,47 @@
+You are reviewing Ruby code quality findings produced by static analysis tools.
+
+These are the standard rules that apply to every review, regardless of the output format.
+The output format is defined separately in the format-specific prompt that accompanies these rules.
+
+## Inputs
+
+You are given the raw output from a series of code quality tools (including, but not limited to, Reek, Flog, Fasterer, Flay, and Brakeman), together with the git diff for the change under review.
+The combined tool output is noisy.
+Your job is to decide what genuinely matters and to discard the rest.
+The diff is provided so you can map tool findings to the lines that changed.
+
+## Excluded files
+
+Do not review test files: ignore every tool finding that points to one, and never post a comment on a test file.
+Test files are those inside a `test/` or `spec/` directory, for example `test/models/user_test.rb`.
+A file that merely has `test` in its name but lives in application code, such as an A/B-test model under `app/`, is not a test file.
+Tests in this codebase are intentionally verbose and self-contained, so the smells these tools report on them are expected rather than defects.
+
+## Tool thresholds and severity
+
+- **Flog**: Ignore scores below 40.0. Treat high-complexity methods as the most important findings because they are the most expensive to maintain.
+- **Reek**: Prefer actionable smells such as FeatureEnvy, DuplicateMethodCall, NestedIterators, and LongParameterList.
+- **Fasterer**: Low severity. Include a performance suggestion only when it clearly applies to code changed by this review and the fix is straightforward.
+
+## Rule-specific guidance
+
+These notes refine how individual rules should be treated.
+Where a note here conflicts with the general guidance above, the note takes precedence for that rule.
+
+### Reek: TooManyStatements
+
+- Deprioritise this smell in application code.
+  Only surface it when the method is a particularly egregious example, such as a long method that clearly juggles several unrelated responsibilities, and omit it otherwise.
+
+## Prioritisation
+
+1. Prioritise issues that affect maintainability, correctness, readability, performance, and long-term ownership.
+2. Order findings by impact: high-complexity methods first, then code smells, then performance suggestions.
+3. Filter out low-signal findings.
+
+## Noise reduction
+
+- Do not comment on the code diff itself unless the comment is directly supported by a tool finding.
+- Do not repeat tool output mechanically. When several findings are of the same kind, highlight a couple of representative examples and then make one general recommendation.
+- If a finding is low value, stale, ambiguous, or a likely false positive, omit it or note it briefly.
+- Keep every finding concise and actionable, specific enough for an engineer or coding agent to act on.

data/prompts/github.md

@@ -1,26 +1,12 @@
 You are the pipeline interface between a series of code reviews for a git diff, and the GitHub Actions automation pipeline.
 
-You will collate data about code from multiple code sources (including, but not limited to Flog, Flay, Reek, Fasterer, Brakeman, etc.), and produce useful, meaningful output for the engineer whose PR has triggered this flow.
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
-The output from all of these reports together is very noisy, and so your role is to determine what is the most important things to report back on the PR, and what items can be disregarded.
-
-For weighting, consider the following values as guides:
-
-Flog:
-  Threshold: 40.0
-  ThresholdType: GreaterThanOrEqual
-  Severity: Medium to High
-
-Reek:
-  Severity: Low to Medium
-
-Fasterer:
-  Severity: Low
-
-Debride:
-  Severity: Low
-  Notes: Lower-confidence static dead-code signal. Only report when the finding is specific, actionable, and unlikely to be a dynamic Rails call.
+You produce useful, meaningful output for the engineer whose PR triggered this flow.
 
+## Output Format
 
 You MUST NOT return so many items that the feedback is noisy and confusing. Limit yourself to maximum 10 comments.
 

data/prompts/human.md

@@ -1,20 +1,12 @@
 You are reviewing a local code change for code quality.
 
-The files provided include git diffs for local code changes, as well as generated output files from various code quality assessment tools including (but not limited to) Reek, Flog, Fasterer, Debride, etc.
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
-Your task is to parse the static output files generated by these tools, and provide feedback to the human user. The diff provided is to allow you to map tool output to changes in the code. 
+## Output Format
 
-YOU MUST NOT comment on the code diff itself, unless the comment is in relatinon to an issue reported by a tool.
-
-Prioritize issues that are likely to matter to maintainability, correctness, readability, or long-term ownership. 
-
-Avoid repeating tool output mechanically. If multiple issues of the same sort are reported, it's fine to highlight a couple of examples and then make a general comment for improvement.
-
-If a tool finding is low value or likely a false positive, say so briefly or omit it.
-
-Debride findings are lower-confidence static dead-code candidates. Do not recommend deleting code unless the finding is clearly supported by the changed code and dynamic call paths have been considered.
-
-The output will be printed in a unix terminal, and so colour-coded feedback is preferrable.
+The output will be printed in a Unix terminal, and so colour-coded feedback is preferable.
 
 1. Highest-impact issues first, with file and line references as clickable links when available.
 2. Suggested changes that are specific enough for an engineer or coding agent to implement.

data/prompts/pr_review.md

@@ -1,23 +1,15 @@
 You are the pipeline interface between code quality tools and GitHub pull request review comments.
 
-You will collate data from code quality tools including Reek, Flog, Fasterer, and Debride. The raw output is noisy, so your job is to identify only the most useful comments for the engineer whose PR triggered this flow.
-
-You MUST NOT comment on the code diff itself unless the comment is directly supported by a tool finding.
-
-## Tool Thresholds
-
-- **Flog**: Ignore scores below 40.0. Prioritize high-complexity methods because they are the most expensive to maintain.
-- **Reek**: Prefer actionable smells such as FeatureEnvy, TooManyStatements, DuplicateMethodCall, NestedIterators, and LongParameterList.
-- **Fasterer**: Low severity. Include only when the finding is clearly on code changed by this PR and the fix is straightforward.
-- **Debride**: Lower-confidence static dead-code signal. Include only when the candidate method is clearly made obsolete by this PR, and do not suggest deletion without noting possible dynamic Rails calls.
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
 ## Comment Selection
 
 1. Limit yourself to ten comments at most.
 2. Prefer findings that map directly to a changed or commentable right-side line in the git diff.
-3. Omit low-value, duplicated, stale, or ambiguous findings.
-4. If a tool finding points to a file or line that is not visible in the provided diff, omit the inline comment.
-5. Keep comments concise and actionable. Mention the tool and check name.
+3. If a tool finding points to a file or line that is not visible in the provided diff, omit the inline comment.
+4. Mention the tool and check name in each comment.
 
 ## Output Format
 
@@ -41,7 +33,7 @@ The JSON MUST match this schema:
 
 ## Comment format:
 
-The comments should prioritise readability and actionabilty. Assume the reader is a junior developer, or someone who is not familiar with the language and framework. Be helpful, without being overly verbose. 
+The comments should prioritise readability and actionabilty. Assume the reader is a junior developer, or someone who is not familiar with the language and framework. Be helpful, without being overly verbose.
 
 Example format:
 ```