overkill 0.2.1__tar.gz → 0.4.0__tar.gz

{overkill-0.2.1 → overkill-0.4.0}/.github/workflows/publish.yml

@@ -13,9 +13,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.12"
 

{overkill-0.2.1 → overkill-0.4.0}/.github/workflows/test.yml

@@ -14,9 +14,9 @@ jobs:
         python-version: ["3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -30,4 +30,4 @@ jobs:
         run: uv run mypy src
 
       - name: Pytest
-        run: uv run pytest
+        run: uv run pytest --cov=mr_overkill --cov-report=term-missing --cov-fail-under=70

{overkill-0.2.1 → overkill-0.4.0}/.gitignore

@@ -3,7 +3,9 @@
 
 # Legacy log directory from previous versions
 .ai-review-logs/
-# review-loop self-hosted install
+# overkill self-hosted install
+.overkill/
+# Legacy directory (pre-migration)
 .review-loop/
 
 # Python

overkill-0.2.1/.reviewlooprc.example → overkill-0.4.0/.overkillrc.example

@@ -1,5 +1,5 @@
-# .reviewlooprc — project-level configuration for review-loop.sh
-# Copy this file to your project root as ".reviewlooprc" and customize.
+# .overkillrc — project-level configuration for overkill review-loop
+# Place this file in .overkill/.overkillrc and customize.
 # CLI arguments always take precedence over these values.
 
 # Target branch to diff against (default: develop)

{overkill-0.2.1 → overkill-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overkill
-Version: 0.2.1
+Version: 0.4.0
 Summary: AI-powered code review loop — automates Codex review + Claude fix cycles
 Project-URL: Repository, https://github.com/modocai/mr-overkill
 Project-URL: Issues, https://github.com/modocai/mr-overkill/issues
@@ -161,7 +161,7 @@ Examples:
 
 ## Usage: overkill init
 
-Initialize `.review-loop/` in a project directory. Safe to re-run — prompts are refreshed, user-edited configs are preserved.
+Initialize `.overkill/` in a project directory. Safe to re-run — prompts are refreshed, user-edited configs are preserved.
 
 ```
 overkill init [TARGET_DIR]   # default: current directory
@@ -170,9 +170,9 @@ overkill init [TARGET_DIR]   # default: current directory
 Creates:
 
 ```
-.review-loop/
+.overkill/
 ├── prompts/active/          # 10 prompt templates
-├── .reviewlooprc            # review-loop config
+├── .overkillrc              # review-loop config
 ├── .refactorsuggestrc       # refactor-suggest config
 ├── logs/                    # runtime logs
 │   └── refactor/            # refactor-suggest logs
@@ -207,9 +207,9 @@ Recommended workflow: start with `--dry-run` to review findings, then re-run wit
 
 ## Configuration
 
-After running `overkill init`, config files live in `.review-loop/`:
+After running `overkill init`, config files live in `.overkill/`:
 
-### .review-loop/.reviewlooprc
+### .overkill/.overkillrc
 
 ```bash
 TARGET_BRANCH="main"
@@ -220,9 +220,9 @@ REVIEWER_BACKEND="codex"    # or "claude"
 PROMPTS_DIR="./custom-prompts"
 ```
 
-See `.review-loop/.reviewlooprc` for all available options.
+See `.overkill/.overkillrc` for all available options.
 
-### .review-loop/.refactorsuggestrc
+### .overkill/.refactorsuggestrc
 
 ```bash
 SCOPE="auto"
@@ -243,7 +243,7 @@ PROMPTS_DIR="./custom-prompts"
 
 ```
 1. Check prerequisites (git, codex, claude, jq, envsubst, target branch)
-2. Create .review-loop/logs/ directory
+2. Create .overkill/logs/ directory
 3. Loop (iteration 1..N):
    a. Generate diff: git diff $TARGET...$CURRENT
    b. Empty diff → exit
@@ -258,14 +258,14 @@ PROMPTS_DIR="./custom-prompts"
    h. Push to remote (updates PR)
    i. Post review/fix/self-review summary as PR comment
    j. Next iteration reviews the updated committed state
-4. Write summary to .review-loop/logs/summary.md
+4. Write summary to .overkill/logs/summary.md
 ```
 
 ## Output Files
 
-All logs are git-ignored by default (inside `.review-loop/`).
+All logs are git-ignored by default (inside `.overkill/`).
 
-### review-loop logs (`.review-loop/logs/`)
+### review-loop logs (`.overkill/logs/`)
 
 | File | Description |
 |------|-------------|
@@ -277,7 +277,7 @@ All logs are git-ignored by default (inside `.review-loop/`).
 | `refix-N-M.md` | Claude re-fix log (iteration N, sub-iteration M) |
 | `summary.md` | Final summary with status and per-iteration results |
 
-### refactor-suggest logs (`.review-loop/logs/refactor/`)
+### refactor-suggest logs (`.overkill/logs/refactor/`)
 
 | File | Description |
 |------|-------------|
@@ -316,7 +316,7 @@ Go/no-go decision based on current usage percentage:
 
 ## Customizing Prompts
 
-Edit the templates in `.review-loop/prompts/active/`.
+Edit the templates in `.overkill/prompts/active/`.
 
 ### review-loop prompts
 
@@ -364,7 +364,7 @@ The loop terminates when any of these occur:
 
 ```bash
 # Quick — just nuke the directory
-rm -rf .review-loop
+rm -rf .overkill
 
 # Also remove the Python package
 pip uninstall overkill       # or: uv tool uninstall overkill / pipx uninstall overkill

{overkill-0.2.1 → overkill-0.4.0}/README.md

@@ -139,7 +139,7 @@ Examples:
 
 ## Usage: overkill init
 
-Initialize `.review-loop/` in a project directory. Safe to re-run — prompts are refreshed, user-edited configs are preserved.
+Initialize `.overkill/` in a project directory. Safe to re-run — prompts are refreshed, user-edited configs are preserved.
 
 ```
 overkill init [TARGET_DIR]   # default: current directory
@@ -148,9 +148,9 @@ overkill init [TARGET_DIR]   # default: current directory
 Creates:
 
 ```
-.review-loop/
+.overkill/
 ├── prompts/active/          # 10 prompt templates
-├── .reviewlooprc            # review-loop config
+├── .overkillrc              # review-loop config
 ├── .refactorsuggestrc       # refactor-suggest config
 ├── logs/                    # runtime logs
 │   └── refactor/            # refactor-suggest logs
@@ -185,9 +185,9 @@ Recommended workflow: start with `--dry-run` to review findings, then re-run wit
 
 ## Configuration
 
-After running `overkill init`, config files live in `.review-loop/`:
+After running `overkill init`, config files live in `.overkill/`:
 
-### .review-loop/.reviewlooprc
+### .overkill/.overkillrc
 
 ```bash
 TARGET_BRANCH="main"
@@ -198,9 +198,9 @@ REVIEWER_BACKEND="codex"    # or "claude"
 PROMPTS_DIR="./custom-prompts"
 ```
 
-See `.review-loop/.reviewlooprc` for all available options.
+See `.overkill/.overkillrc` for all available options.
 
-### .review-loop/.refactorsuggestrc
+### .overkill/.refactorsuggestrc
 
 ```bash
 SCOPE="auto"
@@ -221,7 +221,7 @@ PROMPTS_DIR="./custom-prompts"
 
 ```
 1. Check prerequisites (git, codex, claude, jq, envsubst, target branch)
-2. Create .review-loop/logs/ directory
+2. Create .overkill/logs/ directory
 3. Loop (iteration 1..N):
    a. Generate diff: git diff $TARGET...$CURRENT
    b. Empty diff → exit
@@ -236,14 +236,14 @@ PROMPTS_DIR="./custom-prompts"
    h. Push to remote (updates PR)
    i. Post review/fix/self-review summary as PR comment
    j. Next iteration reviews the updated committed state
-4. Write summary to .review-loop/logs/summary.md
+4. Write summary to .overkill/logs/summary.md
 ```
 
 ## Output Files
 
-All logs are git-ignored by default (inside `.review-loop/`).
+All logs are git-ignored by default (inside `.overkill/`).
 
-### review-loop logs (`.review-loop/logs/`)
+### review-loop logs (`.overkill/logs/`)
 
 | File | Description |
 |------|-------------|
@@ -255,7 +255,7 @@ All logs are git-ignored by default (inside `.review-loop/`).
 | `refix-N-M.md` | Claude re-fix log (iteration N, sub-iteration M) |
 | `summary.md` | Final summary with status and per-iteration results |
 
-### refactor-suggest logs (`.review-loop/logs/refactor/`)
+### refactor-suggest logs (`.overkill/logs/refactor/`)
 
 | File | Description |
 |------|-------------|
@@ -294,7 +294,7 @@ Go/no-go decision based on current usage percentage:
 
 ## Customizing Prompts
 
-Edit the templates in `.review-loop/prompts/active/`.
+Edit the templates in `.overkill/prompts/active/`.
 
 ### review-loop prompts
 
@@ -342,7 +342,7 @@ The loop terminates when any of these occur:
 
 ```bash
 # Quick — just nuke the directory
-rm -rf .review-loop
+rm -rf .overkill
 
 # Also remove the Python package
 pip uninstall overkill       # or: uv tool uninstall overkill / pipx uninstall overkill

{overkill-0.2.1 → overkill-0.4.0}/bin/lib/common.sh

@@ -277,7 +277,7 @@ _changed_files_since_snapshot() {
   _out=$(mktemp)
   _git_all_dirty_nul | while IFS= read -r -d '' _f; do
     [[ -n "$_f" ]] || continue
-    [[ "$_f" == .review-loop/logs/* ]] && continue
+    [[ "$_f" == .overkill/logs/* || "$_f" == .review-loop/logs/* ]] && continue
     if [[ -f "$_f" ]]; then
       _cur_hash=$(git hash-object "$_f" 2>/dev/null || echo UNHASHABLE)
       if [[ -x "$_f" ]]; then _cur_mode="100755"; else _cur_mode="100644"; fi

{overkill-0.2.1 → overkill-0.4.0}/prompts/active/claude-review.prompt.md

@@ -8,15 +8,23 @@ You are a code reviewer analyzing a proposed change.
 
 ## Instructions
 
-Run the following command to get the diff:
+Start by running the following command to get the diff:
 
 ```
 git diff ${TARGET_BRANCH}...${CURRENT_BRANCH}
 ```
 
+Then **actively explore the codebase** to understand context before flagging issues:
+
+- Use `Read` to examine surrounding code when a change touches a function or module.
+- Use `Grep` to check if a pattern, variable, or function is used elsewhere before calling it dead code or flagging a naming issue.
+- Use `Glob` to find related files (e.g. tests, configs) that may clarify intent.
+
 Review the diff according to the guidelines below.
 
-## Review Guidelines
+## Review Guidelines — HIGH SIGNAL ONLY
+
+We only want findings where you are confident the issue is real. **If you are not certain an issue is real, do not flag it.** False positives erode trust and waste reviewer time.
 
 1. Only flag issues the original author would fix if they knew about them.
 2. The issue must be **introduced by this diff** — do not flag pre-existing problems.
@@ -24,6 +32,16 @@ Review the diff according to the guidelines below.
 4. Do not flag trivial style issues unless they obscure meaning or violate documented standards.
 5. Do not speculate — you must identify the exact code location and explain why it is a problem.
 6. If this is iteration > 1, focus on whether issues from prior reviews have been properly fixed, and identify any new issues introduced by the fixes.
+7. **Only flag issues where your confidence is >= 0.85.** If you cannot reach that threshold after investigating, do not include the finding.
+
+### Do NOT flag (false positive filter)
+
+- Pre-existing issues not introduced by this diff.
+- Something that appears to be a bug but is actually correct when you read the surrounding code.
+- Pedantic nitpicks that a senior engineer would not flag in a real review.
+- Issues that a linter or formatter will catch — do not run the linter to verify.
+- Potential issues that depend on specific inputs or state that are not demonstrated in the diff.
+- General code quality concerns (e.g. lack of test coverage, general security hygiene) unless they are concretely exploitable.
 
 ## Priority Levels
 

overkill-0.4.0/prompts/active/codex-review.prompt.md

@@ -0,0 +1,81 @@
+You are a code reviewer analyzing a proposed change.
+
+## Context
+
+- **Current branch**: ${CURRENT_BRANCH}
+- **Target branch**: ${TARGET_BRANCH}
+- **Review iteration**: ${ITERATION}
+
+## Instructions
+
+Run the following command to get the diff:
+
+```
+git diff ${TARGET_BRANCH}...${CURRENT_BRANCH}
+```
+
+Review the diff according to the guidelines below.
+
+## Review Guidelines
+
+1. Only flag issues the original author would fix if they knew about them.
+2. The issue must be **introduced by this diff** — do not flag pre-existing problems.
+3. The issue must meaningfully impact the accuracy, performance, security, or maintainability of the code.
+4. The issue must be discrete, actionable, and concretely provable.
+5. Fixing the bug does not demand a level of rigor not present in the rest of the codebase (e.g. one doesn't need detailed comments and input validation in a repository of one-off scripts).
+6. The bug does not rely on unstated assumptions about the codebase or author's intent.
+7. It is not enough to speculate that a change may disrupt another part of the codebase — you must identify the other parts of the code that are provably affected.
+8. The bug is clearly not just an intentional change by the original author.
+9. Do not flag trivial style issues unless they obscure meaning or violate documented standards.
+10. If this is iteration > 1, focus on whether issues from prior reviews have been properly fixed, and identify any new issues introduced by the fixes.
+
+Output all findings that the original author would fix if they knew about them. If there is no finding that a person would definitely want to fix, prefer outputting no findings. Do not stop at the first qualifying finding — continue until you've listed every qualifying finding.
+
+## Priority Levels
+
+- **P0** — Drop everything. Blocking release, operations, or major usage. Universal issues not dependent on assumptions.
+- **P1** — Urgent. Should be addressed in the next cycle.
+- **P2** — Normal. To be fixed eventually.
+- **P3** — Low. Nice to have.
+
+## Comment Guidelines
+
+- One comment per distinct issue.
+- Brief (at most 1 paragraph body).
+- Clearly state the scenarios, environments, or inputs required for the bug to manifest.
+- Appropriately communicate severity — do not overclaim. Immediately indicate if the issue's severity depends on specific conditions.
+- The comment should be written such that the original author can immediately grasp the idea without close reading.
+- Matter-of-fact tone, no flattery. Avoid "Great job …", "Thanks for …".
+- Code snippets max 3 lines, wrapped in markdown code tags.
+- Use ```suggestion blocks only for concrete replacement code (minimal lines; no commentary inside the block). Preserve exact leading whitespace.
+
+## Output Format
+
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+
+{
+  "findings": [
+    {
+      "title": "<P-tag + imperative description, max 80 chars>",
+      "body": "<Markdown explaining why this is a problem; cite files/lines/functions>",
+      "confidence_score": <float 0.0-1.0>,
+      "priority": <int 0-3>,
+      "code_location": {
+        "file_path": "<repo-relative file path, e.g. src/main.ts>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "overall_correctness": "patch is correct" | "patch is incorrect",
+  "overall_explanation": "<1-3 sentence justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}
+
+If there are no findings, return:
+
+{
+  "findings": [],
+  "overall_correctness": "patch is correct",
+  "overall_explanation": "<brief justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}

overkill-0.4.0/prompts/active/gemini-refactor-full.prompt.md

@@ -0,0 +1,115 @@
+You are a refactoring advisor analyzing an entire codebase for **architecture-level** redesign opportunities.
+
+## Context
+
+- **Target branch**: ${TARGET_BRANCH}
+- **Scope**: full (architecture redesign)
+- **Blast radius**: high-critical — changes may restructure the entire project
+- **Iteration**: ${ITERATION}
+- **Source files list**: ${SOURCE_FILES_PATH}
+
+## Instructions
+
+1. Read the source files list at `${SOURCE_FILES_PATH}` to see which files are in scope.
+2. Read the files and identify architecture-level refactoring opportunities — **structural problems only**:
+   - Wrong abstractions: code is organized around the wrong concepts, forcing workarounds
+   - Inverted dependencies: high-level modules depend on low-level implementation details
+   - Layer violations: business logic in presentation layer, I/O in pure-logic modules, etc.
+   - Missing architectural boundaries the codebase has outgrown not having
+   - Scalability bottlenecks baked into the current structure
+3. Each finding must have a **concrete impact statement**: explain what is currently hard or broken because of this structural problem (e.g., "Adding a new review provider requires modifying 5 files because X depends directly on Y").
+4. **Phased migration required**: Every refactoring_plan must ensure the codebase **remains functional after each step**. No "big bang" rewrites.
+5. **Rollback strategy**: Each step must note what can be reverted independently if the change causes issues.
+6. **Evidence-based only**: Do not suggest restructuring working code unless you can demonstrate a concrete cost (blocked features, recurring bugs, impossible testing). "This would be cleaner" is not sufficient justification.
+7. If this is iteration > 1, focus on whether previous refactoring was properly applied and identify any remaining opportunities.
+
+## Anti-patterns (DO NOT flag these)
+
+- Micro-optimizations (rename variable, split function) — this is micro scope
+- "Trendy" pattern adoption (rewrite in a new framework, adopt microservices) without demonstrated need
+- Suggesting patterns because they exist in other projects, not because this codebase needs them
+- Proposing changes with high blast radius but only cosmetic benefit
+- Restructuring that would break the project's existing CI/CD or deployment model without justification
+
+## Example: Good Finding
+
+```json
+{
+  "title": "[P1] Invert dependency: review-loop.sh hardcodes AI provider details",
+  "body": "Currently `bin/review-loop.sh` directly calls OpenAI/Claude APIs with provider-specific logic scattered across lines 150-220, 340-380, and 450-490. This means:\n- Adding a new AI provider requires modifying 3 sections of a 700-line file\n- Testing with a mock provider is impossible without editing production code\n- Provider-specific retry/error logic is interleaved with review orchestration\n\n**Suggested structure**: Extract a `lib/ai-provider.sh` interface with `call_ai()` that encapsulates provider selection, API calls, and retries. `review-loop.sh` calls only `call_ai()` and doesn't know which provider is behind it.\n\n**Rollback**: If `lib/ai-provider.sh` causes issues, revert the single file and restore inline calls — the orchestration logic in review-loop.sh doesn't change.",
+  "confidence_score": 0.8,
+  "priority": 1,
+  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 150, "end": 220} }
+}
+```
+
+## Example: Bad Finding (DO NOT produce)
+
+```json
+{
+  "title": "[P2] Consider adopting MVC pattern",
+  "body": "The codebase would benefit from separating concerns into Model-View-Controller layers for better organization.",
+  "confidence_score": 0.5,
+  "priority": 2,
+  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 700} }
+}
+```
+Why this is bad: no concrete impact statement, no evidence of current pain, suggests a pattern without demonstrating need, no phased migration.
+
+## Priority Levels
+
+- **P0** — The architecture actively prevents correctness or causes data loss.
+- **P1** — The architecture blocks important feature work or causes systematic bugs.
+- **P2** — Normal improvement: restructuring significantly improves maintainability.
+- **P3** — Strategic: long-term structural improvement.
+
+## Output Format
+
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+
+{
+  "findings": [
+    {
+      "title": "<P-tag + imperative description, max 80 chars>",
+      "body": "<Markdown explaining the structural problem, concrete impact, and migration strategy; cite files/modules>",
+      "confidence_score": <float 0.0-1.0>,
+      "priority": <int 0-3>,
+      "code_location": {
+        "file_path": "<repo-relative file path>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "refactoring_plan": {
+    "scope": "full",
+    "summary": "<1-3 sentence overview of the architectural change>",
+    "estimated_files_affected": <int>,
+    "steps": [
+      {
+        "order": <int>,
+        "description": "<what to do in this phase; must leave codebase functional; include rollback note>",
+        "files": ["<file1>", "<file2>"]
+      }
+    ],
+    "estimated_blast_radius": "high-critical"
+  },
+  "overall_correctness": "needs refactoring" | "code is clean",
+  "overall_explanation": "<1-3 sentence justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}
+
+If there are no findings, return:
+
+{
+  "findings": [],
+  "refactoring_plan": {
+    "scope": "full",
+    "summary": "No refactoring needed.",
+    "estimated_files_affected": 0,
+    "steps": [],
+    "estimated_blast_radius": "none"
+  },
+  "overall_correctness": "code is clean",
+  "overall_explanation": "<brief justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}

overkill-0.4.0/prompts/active/gemini-refactor-layer.prompt.md

@@ -0,0 +1,115 @@
+You are a refactoring advisor analyzing an entire codebase for **layer-level** (cross-cutting) improvements.
+
+## Context
+
+- **Target branch**: ${TARGET_BRANCH}
+- **Scope**: layer (cross-cutting concerns across modules)
+- **Blast radius**: medium-high — changes span multiple modules or layers
+- **Iteration**: ${ITERATION}
+- **Source files list**: ${SOURCE_FILES_PATH}
+
+## Instructions
+
+1. Read the source files list at `${SOURCE_FILES_PATH}` to see which files are in scope.
+2. Read the files and identify cross-cutting refactoring opportunities:
+   - Inconsistent error handling patterns across the codebase
+   - Logging/observability concerns scattered without a clear strategy
+   - Configuration management that should be centralized
+   - Security patterns applied inconsistently (input validation, auth checks)
+   - Cross-cutting concerns (retry logic, caching, rate limiting) duplicated across layers
+3. **Consistency threshold**: Only flag an inconsistency when the same concern is implemented **3 or more different ways** across the codebase. Two slightly different approaches may be intentional.
+4. **Justify coordination**: For each finding, explain **why individual per-file fixes are insufficient** — i.e., why a coordinated cross-cutting change is needed.
+5. **Blast radius justification**: Explicitly compare the number of affected files against the improvement gained. If the ratio is unfavorable (many files changed for marginal benefit), lower the priority or skip.
+6. Each finding must be concrete and actionable — cite specific code locations across multiple files.
+7. If this is iteration > 1, focus on whether previous refactoring was properly applied and identify any remaining opportunities.
+
+## Anti-patterns (DO NOT flag these)
+
+- Architecture redesign (moving modules, changing project structure) — this is full scope
+- Single-file local improvements (renaming, splitting functions) — this is micro scope
+- Suggesting a logging framework when simple stderr output is sufficient for the project's scale
+- Proposing middleware/interceptor patterns when the codebase has < 5 files
+- Flagging minor formatting inconsistencies as cross-cutting concerns
+
+## Example: Good Finding
+
+```json
+{
+  "title": "[P1] Unify error exit pattern across all bin/ scripts",
+  "body": "Error exits are handled 3 different ways:\n1. `bin/review-loop.sh` uses `die()` (lines 25-28) which logs to stderr and exits 1\n2. `bin/refactor-suggest.sh` uses `log_error` + bare `exit 1` (lines 88, 142, 201)\n3. `bin/apply-fix.sh` calls `echo \"ERROR: ...\" >&2` directly (lines 33, 67)\n\nThis makes it easy to miss cleanup (temp file removal) on error paths. A coordinated change to use a shared `die()` that includes cleanup would prevent resource leaks across all scripts.",
+  "confidence_score": 0.85,
+  "priority": 1,
+  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 25, "end": 28} }
+}
+```
+
+## Example: Bad Finding (DO NOT produce)
+
+```json
+{
+  "title": "[P2] Improve error handling",
+  "body": "The codebase could benefit from more consistent error handling patterns.",
+  "confidence_score": 0.5,
+  "priority": 2,
+  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 700} }
+}
+```
+Why this is bad: no specific examples of inconsistency, no file/line citations, doesn't explain why a coordinated change is needed.
+
+## Priority Levels
+
+- **P0** — Security or reliability gap: inconsistent application of a critical concern.
+- **P1** — Systematic debt: the inconsistency actively causes bugs or makes them likely.
+- **P2** — Normal improvement: unifying a pattern improves maintainability.
+- **P3** — Nice-to-have: consistency improvement with low immediate impact.
+
+## Output Format
+
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+
+{
+  "findings": [
+    {
+      "title": "<P-tag + imperative description, max 80 chars>",
+      "body": "<Markdown explaining the problem and suggested change; cite files/lines/functions>",
+      "confidence_score": <float 0.0-1.0>,
+      "priority": <int 0-3>,
+      "code_location": {
+        "file_path": "<repo-relative file path>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "refactoring_plan": {
+    "scope": "layer",
+    "summary": "<1-3 sentence overview of all proposed changes>",
+    "estimated_files_affected": <int>,
+    "steps": [
+      {
+        "order": <int>,
+        "description": "<what to do>",
+        "files": ["<file1>", "<file2>"]
+      }
+    ],
+    "estimated_blast_radius": "medium-high"
+  },
+  "overall_correctness": "needs refactoring" | "code is clean",
+  "overall_explanation": "<1-3 sentence justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}
+
+If there are no findings, return:
+
+{
+  "findings": [],
+  "refactoring_plan": {
+    "scope": "layer",
+    "summary": "No refactoring needed.",
+    "estimated_files_affected": 0,
+    "steps": [],
+    "estimated_blast_radius": "none"
+  },
+  "overall_correctness": "code is clean",
+  "overall_explanation": "<brief justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}