/java-code-review

name: java-code-review
description: >
  Review Java code for bugs, duplicate code, correctness risks, maintainability
  improvements, and missing tests. By default review files modified in git;
  when the user explicitly names files, classes, packages, or a diff, review
  that scope instead. Generate a detailed review.md report with actionable
  comments and fixes.

Java Code Review

Perform a focused, evidence-based review of Java code and write the findings to `review.md` in the repository root unless the user specifies another location. This skill reviews code; do not modify production code unless the user explicitly asks for fixes.

Establish the review scope

1. If the user explicitly specifies files, classes, packages, commits, or a diff, use that scope and do not silently broaden it. 2. Otherwise inspect the git worktree and review modified, added, or renamed files. Use `git status --short` and the relevant `git diff` (including staged changes when present). For renamed files, review the resulting file and the meaningful diff. 3. Include only Java and Java-adjacent files relevant to behavior (for example, tests, SQL migrations, configuration, or API schemas) when they affect the reviewed Java code. State the selected scope in the report. 4. Read enough surrounding code, callers, tests, configuration, and interfaces to validate each finding. Do not report a concern based only on a name or a generic best practice.

Review for

• **Potential bugs:** incorrect conditions, null/empty handling, state or

transaction errors, exception handling, resource leaks, concurrency issues, security or authorization gaps, API/serialization mismatches, persistence mistakes, and boundary cases.

• **Duplicate code:** repeated logic, copy-pasted branches, duplicated

mappings/validation, and abstractions that would reduce meaningful drift.

• **Needs improvement:** unclear or brittle design, excessive coupling,

misleading names, avoidable complexity, test gaps, performance concerns, and violations of established project conventions.

Prioritize correctness and impact over style. Do not flag formatting or an opinionated alternative unless it creates a concrete maintenance, reliability, security, or performance problem. Distinguish confirmed issues from risks or questions, and avoid speculative findings.

Validate findings

For every finding, trace the relevant control flow and data flow. Check nearby tests and, when practical, run the narrowest useful test, compile, static analysis, or reproduction command. Do not change files to make validation pass. If validation cannot be run, say why. Check whether a suspected issue is already handled by a caller, framework contract, annotation, or configuration.

Write `review.md`

Before writing, check whether the requested output file already exists.

• If it exists, ask the user whether to overwrite it or use a new filename;

do not overwrite without that choice.

• If the user chooses a new filename, use exactly that filename (within the

repository or requested output location).

• If no report exists, create `review.md`.

The report must be self-contained and include:

# Java Code Review

## Scope
<!-- files/diff reviewed, review date, and validation performed -->

## Summary
<!-- concise overall assessment and finding counts by severity -->

## Findings

### [SEVERITY] Short title
- **Location:** `path/to/File.java:line`
- **Category:** Bug | Duplicate code | Improvement
- **Confidence:** High | Medium | Low

**Problem**
Explain the concrete behavior and why it matters, citing the relevant code.

**Suggested fix**
Give a specific implementation approach, including edge cases and tests to
add or update. Do not merely say “refactor” or “add validation.”

## Positive observations
<!-- optional; mention useful safeguards or clear design choices -->

## Validation
<!-- commands run and their outcomes, or why validation was unavailable -->

Use severity consistently: **Blocker** (unsafe or clearly broken), **High** (likely production failure or serious security/data issue), **Medium** (meaningful bug or maintainability risk), and **Low** (minor but actionable). Order findings by severity, then by file and line. Include one finding per distinct problem, avoid duplicates, and use precise line references that still make sense in the reviewed version. If no findings are found, say so clearly and still include scope, validation, and positive observations.

Final response

Tell the user that the report was created and link to the generated file. Give the finding count and briefly call out any Blocker or High findings. If the report could not be created because an existing file needs a choice, ask the overwrite/new-filename question and stop before writing.