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
- If the user explicitly specifies files, classes, packages, commits, or a
diff, use that scope and do not silently broaden it.
- 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.
- 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.
- 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.
1---
2name: java-code-review
3description: >
4 Review Java code for bugs, duplicate code, correctness risks, maintainability
5 improvements, and missing tests. By default review files modified in git;
6 when the user explicitly names files, classes, packages, or a diff, review
7 that scope instead. Generate a detailed review.md report with actionable
8 comments and fixes.
9metadata:
10 source: https://skillmd.com/skills/gabrielmoreira/java-code-review
11---
12
13# Java Code Review
14
15Perform a focused, evidence-based review of Java code and write the findings to
16`review.md` in the repository root unless the user specifies another location.
17This skill reviews code; do not modify production code unless the user
18explicitly asks for fixes.
19
20## Establish the review scope
21
221. If the user explicitly specifies files, classes, packages, commits, or a
23 diff, use that scope and do not silently broaden it.
242. Otherwise inspect the git worktree and review modified, added, or renamed
25 files. Use `git status --short` and the relevant `git diff` (including
26 staged changes when present). For renamed files, review the resulting file
27 and the meaningful diff.
283. Include only Java and Java-adjacent files relevant to behavior (for
29 example, tests, SQL migrations, configuration, or API schemas) when they
30 affect the reviewed Java code. State the selected scope in the report.
314. Read enough surrounding code, callers, tests, configuration, and interfaces
32 to validate each finding. Do not report a concern based only on a name or
33 a generic best practice.
34
35## Review for
36
37- **Potential bugs:** incorrect conditions, null/empty handling, state or
38 transaction errors, exception handling, resource leaks, concurrency issues,
39 security or authorization gaps, API/serialization mismatches, persistence
40 mistakes, and boundary cases.
41- **Duplicate code:** repeated logic, copy-pasted branches, duplicated
42 mappings/validation, and abstractions that would reduce meaningful drift.
43- **Needs improvement:** unclear or brittle design, excessive coupling,
44 misleading names, avoidable complexity, test gaps, performance concerns,
45 and violations of established project conventions.
46
47Prioritize correctness and impact over style. Do not flag formatting or an
48opinionated alternative unless it creates a concrete maintenance, reliability,
49security, or performance problem. Distinguish confirmed issues from risks or
50questions, and avoid speculative findings.
51
52## Validate findings
53
54For every finding, trace the relevant control flow and data flow. Check nearby
55tests and, when practical, run the narrowest useful test, compile, static
56analysis, or reproduction command. Do not change files to make validation pass.
57If validation cannot be run, say why. Check whether a suspected issue is
58already handled by a caller, framework contract, annotation, or configuration.
59
60## Write `review.md`
61
62Before writing, check whether the requested output file already exists.
63
64- If it exists, ask the user whether to overwrite it or use a new filename;
65 do not overwrite without that choice.
66- If the user chooses a new filename, use exactly that filename (within the
67 repository or requested output location).
68- If no report exists, create `review.md`.
69
70The report must be self-contained and include:
71
72```markdown
73# Java Code Review
74
75## Scope
76<!-- files/diff reviewed, review date, and validation performed -->
77
78## Summary
79<!-- concise overall assessment and finding counts by severity -->
80
81## Findings
82
83### [SEVERITY] Short title
84- **Location:** `path/to/File.java:line`
85- **Category:** Bug | Duplicate code | Improvement
86- **Confidence:** High | Medium | Low
87
88**Problem**
89Explain the concrete behavior and why it matters, citing the relevant code.
90
91**Suggested fix**
92Give a specific implementation approach, including edge cases and tests to
93add or update. Do not merely say “refactor” or “add validation.”
94
95## Positive observations
96<!-- optional; mention useful safeguards or clear design choices -->
97
98## Validation
99<!-- commands run and their outcomes, or why validation was unavailable -->
100```
101
102Use severity consistently: **Blocker** (unsafe or clearly broken), **High**
103(likely production failure or serious security/data issue), **Medium**
104(meaningful bug or maintainability risk), and **Low** (minor but actionable).
105Order findings by severity, then by file and line. Include one finding per
106distinct problem, avoid duplicates, and use precise line references that still
107make sense in the reviewed version. If no findings are found, say so clearly
108and still include scope, validation, and positive observations.
109
110## Final response
111
112Tell the user that the report was created and link to the generated file. Give
113the finding count and briefly call out any Blocker or High findings. If the
114report could not be created because an existing file needs a choice, ask the
115overwrite/new-filename question and stop before writing.