Skill: Review Java

Purpose

Review code in Java for language and runtime conventions only. Do not define scope (diff vs codebase) or perform security/architecture analysis; those are handled by scope and cognitive skills. Emit a findings list in the standard format for aggregation. Focus on concurrency and thread safety, exceptions and try-with-resources, API and version compatibility, collections and Streams, NIO and proper closing, modules (JPMS) where relevant, and testability.

Core Objective

Primary Goal: Produce a Java language/runtime findings list covering concurrency, exceptions, resource management, API compatibility, collections/Streams, NIO, and testability for the given code scope.

Success Criteria (ALL must be met):

1. ✅ Java-only scope: Only Java language and runtime conventions are reviewed; no scope selection, security, or architecture analysis performed
2. ✅ All six Java dimensions covered: Concurrency/thread safety, exceptions/resources, API/version compatibility, collections/Streams, NIO/closing, and testability are assessed where relevant
3. ✅ Findings format compliant: Each finding includes Location, Category (language-java), Severity, Title, Description, and optional Suggestion
4. ✅ File:line references: All findings reference specific file locations with line numbers
5. ✅ Non-Java code excluded: Non-Java files are not analyzed for Java-specific rules unless explicitly in scope

Acceptance Test: Does the output contain a Java-focused findings list with file:line references covering all relevant language/runtime dimensions without performing security, architecture, or scope analysis?

Scope Boundaries

This skill handles:

• Concurrency and thread safety (synchronized, volatile, concurrent collections, executor lifecycle)
• Exception handling (try-with-resources, Throwable hierarchy, rethrow patterns)
• API stability and version compatibility (deprecated APIs, JPMS boundaries)
• Collections and Stream API (allocation, boxing, side effects, immutability)
• NIO and resource closing (streams, channels, selectors)
• Testability (DI, singleton usage, final/overridable design)

This skill does NOT handle:

• Scope selection — scope is provided by the caller
• Security analysis — use review-security
• Architecture analysis — use review-architecture
• SQL-specific analysis — use review-sql
• Full orchestrated review — use review-code

Handoff point: When all Java findings are emitted, hand off to review-code for aggregation. For SQL or security issues found in Java code, note them and suggest the appropriate cognitive skill.

Use Cases

• Orchestrated review: Used as the language step when review-code runs scope → language → framework → library → cognitive for Java projects.
• Java-only review: When the user wants only language/runtime conventions checked.
• Pre-PR Java checklist: Ensure concurrency, resource management, and API compatibility are correct.

When to use: When the code under review is Java and the task includes language/runtime quality. Scope is determined by the caller or user.

Behavior

Scope of this skill

• Analyze: Java language and runtime conventions in the given code scope (files or diff provided by the caller). Do not decide scope; accept the code range as input.
• Do not: Perform scope selection, security review, or architecture review; do not review non-Java files for Java rules unless explicitly in scope.

Review checklist (Java dimension only)

1. Concurrency and thread safety: Correct use of synchronized, volatile, locks, or concurrent APIs; visibility and happens-before; shared mutable state; executor usage and shutdown.
2. Exceptions and resources: try-with-resources for Closeable/AutoCloseable; exception handling and suppression; avoiding empty catch or overly broad catch.
3. API and version compatibility: Public API stability; backward compatibility; use of deprecated APIs and migration path; module boundaries (JPMS) if applicable.
4. Collections and Streams: Appropriate use of Stream API; side effects in streams; allocation and boxing; immutable collections where appropriate.
5. NIO and closing: Proper closing of streams, channels, and selectors; avoid resource leaks; use try-with-resources.
6. Testability: Dependency injection; static and singleton usage; overridable vs final; test doubles and mocking.

Tone and references

• Professional and technical: Reference specific locations (file:line). Emit findings with Location, Category, Severity, Title, Description, Suggestion.

Input & Output

Input

• Code scope: Files or directories (or diff) already selected by the user or by the scope skill. This skill does not decide scope; it reviews the provided Java code for language conventions only.

Output

• Emit zero or more findings in the format defined in Appendix: Output contract.
• Category for this skill is language-java.

Restrictions

Hard Boundaries

• Do not perform security, architecture, or scope selection. Stay within Java language and runtime conventions.
• Do not give conclusions without specific locations or actionable suggestions.
• Do not review non-Java code for Java-specific rules unless explicitly in scope.

Skill Boundaries

Do NOT do these (other skills handle them):

• Do NOT select or define the code scope — scope is determined by the caller or review-code
• Do NOT perform security analysis — use review-security
• Do NOT perform architecture analysis — use review-architecture
• Do NOT perform comprehensive SQL analysis — use review-sql

When to stop and hand off:

• When all Java findings are emitted, hand off to review-code for aggregation
• When the user needs a full review (scope + language + cognitive), redirect to review-code
• When SQL or security issues are found, note them and suggest appropriate cognitive skills

Self-Check

Core Success Criteria

• Java-only scope: Only Java language and runtime conventions are reviewed; no scope selection, security, or architecture analysis performed
• All six Java dimensions covered: Concurrency/thread safety, exceptions/resources, API/version compatibility, collections/Streams, NIO/closing, and testability are assessed where relevant
• Findings format compliant: Each finding includes Location, Category (language-java), Severity, Title, Description, and optional Suggestion
• File:line references: All findings reference specific file locations with line numbers
• Non-Java code excluded: Non-Java files are not analyzed for Java-specific rules unless explicitly in scope

Process Quality Checks

• Was only the Java language/runtime dimension reviewed (no scope/security/architecture)?
• Are concurrency, exceptions, resources, collections/Streams, NIO, and testability covered where relevant?
• Is each finding emitted with Location, Category=language-java, Severity, Title, Description, and optional Suggestion?
• Are issues referenced with file:line?

Acceptance Test

Does the output contain a Java-focused findings list with file:line references covering all relevant language/runtime dimensions without performing security, architecture, or scope analysis?

Examples

Example 1: Resource and exception

• Input: Java method that opens an InputStream and does not use try-with-resources.
• Expected: Emit a finding for resource management; suggest try-with-resources. Category = language-java.

Example 2: Concurrency

• Input: Shared mutable list accessed from multiple threads without synchronization or concurrent collection.
• Expected: Emit finding(s) for thread safety (e.g. use CopyOnWriteArrayList or synchronize); reference the field and usage. Category = language-java.

Edge case: Mixed Java and SQL

• Input: File with JDBC or JPA and Java logic.
• Expected: Review only Java conventions (resources, exceptions, concurrency). Do not emit SQL-injection findings here; that is for review-security or review-sql.

Appendix: Output contract

Each finding MUST follow the standard findings format:

Example:

- **Location**: `src/main/java/com/example/Loader.java:45`
- **Category**: language-java
- **Severity**: major
- **Title**: InputStream not closed in all paths
- **Description**: Leak possible if an exception is thrown before close.
- **Suggestion**: Use try-with-resources for the InputStream.