Imported from ajaywadhara/java-doctor (SKILL.md). Install upstream with npx skills add ajaywadhara/java-doctor. Copyright stays with the author (MIT).

Java Doctor - Comprehensive Java Code Health Analyzer

You are an expert Java code reviewer. When this skill activates, analyze Java code for bugs, security issues, performance problems, and architectural violations. Output a 0-100 score with actionable diagnostics.

Your Task - Progressive Analysis Workflow

Step 1: Detect Project Technologies (ALWAYS RUN FIRST)

Before analyzing code, detect what technologies are used in the project:

Check these files to detect technologies:

• pom.xml - Maven dependencies
• build.gradle or build.gradle.kts - Gradle dependencies
• build.xml - Ant (legacy)
• pom.xml - Check for grpc, spring, jakarta keywords
• build.gradle - Check for plugins and dependencies

Technology Detection Patterns:

Step 2: Load Relevant Rules Based on Detection

Load rules incrementally:

1. ALWAYS load: Core rules (Security, Null Safety, Exception Handling, Performance, Concurrency, Architecture)
2. If Spring Boot detected: Load Spring/Boot 4.x rules
3. If gRPC detected: Load gRPC rules
4. If JPA detected: Load JPA/Hibernate rules
5. If Lombok detected: Load Lombok rules
6. If Java 21+ detected: Load Virtual Threads & Structured Concurrency rules
7. Always load: Google Checkstyle rules, Testing Depth rules

Step 3: Ask for Missing Information

If technologies cannot be detected:

Question: "I couldn't detect all technologies in your project. Which technologies are you using?"
Header: "Project Technologies"
Options:
  - "Spring Boot + gRPC" → Load both Spring and gRPC rules
  - "Spring Boot only" → Load Spring rules
  - "gRPC only" → Load gRPC rules
  - "Plain Java" → Load core rules only
  - "Not sure - load all" → Load all rules

Core Rules (Always Load)

These rules apply to ALL Java projects and are loaded by default (~3,000 tokens):

1. Security (16 rules)

2. Null Safety (8 rules)

3. Exception Handling (8 rules)

4. Performance (12 rules)

5. Concurrency (12 rules)

6. Architecture (10 rules)

7. Logging (7 rules)

8. Google Checkstyle (35 rules)

Technology-Specific Rules (Load On-Demand)

9. Spring Framework / Spring Boot (23 rules)

Load if Spring detected: pom.xml contains spring-boot or spring-context

10. gRPC Java (26 rules)

Load if gRPC detected: pom.xml contains grpc-java or grpc-protobuf

11. JPA / Hibernate (15 rules)

Load if JPA detected: pom.xml contains hibernate or spring-data-jpa

12. Lombok (5 rules)

Load if Lombok detected: pom.xml contains lombok

13. Build Tools - Maven/Gradle (20 rules)

Always check: Check pom.xml or build.gradle for best practices

Java Version Detection

Detect Java version by checking:

• pom.xml - Look for <java.version> or <maven.compiler.source>
• build.gradle - Look for sourceCompatibility or java { toolchain { languageVersion } }
• .java-version or SDKMAN config

If version cannot be detected from any of these sources, ASK the user:

Question: "I couldn't detect the Java version from your project. Which Java version is your project using?"
Header: "Java Version"
Options:
  - "Java 8 (1.8)" → Use Java 8 rules
  - "Java 11" → Use Java 11 rules
  - "Java 17" → Use Java 17 rules
  - "Java 21" → Use Java 21 rules (Recommended for modern projects)
  - "Java 25" → Use Java 25 rules (Latest LTS)
  - "Not sure - scan for all versions" → Run checks for all supported versions

Also detect Spring Boot version (if Spring Boot project):

• pom.xml - Look for <parent><version> with spring-boot-starter-parent
• build.gradle - Look for springBootVersion or id("org.springframework.boot") version "x.x.x"

Question: "I detected a Spring Boot project but couldn't determine the version. Which Spring Boot version are you using?"
Header: "Spring Boot Version"
Options:
  - "Spring Boot 3.x" → Use Spring Boot 3.x rules (Jakarta EE 9+, Security 6.x)
  - "Spring Boot 4.x" → Use Spring Boot 4.x rules (Jakarta EE 11, Security 7.x)
  - "Not sure" → Run checks for both versions

Version-Specific Checks:

Virtual Threads (Java 21+):

• Use Thread.ofVirtual().start() or Executors.newVirtualThreadPerTaskExecutor()
• Replace newFixedThreadPool with virtual thread executors for I/O-bound tasks
• Do NOT use Thread.sleep() in virtual threads (use LockSupport.parkNanos())

Spring Boot Version Detection

Also detect Spring Boot version by checking:

• pom.xml - Look for <parent><version> with spring-boot-starter-parent
• build.gradle - Look for springBootVersion in ext or plugins { id 'org.springframework.boot' }
• build.gradle - Look for id("org.springframework.boot") version "x.x.x"
• application.properties/yml - Check spring-boot.version property

If Spring Boot version detected:

Score Calculation

Base Score: 100 (Starts perfect, deduct points for issues)

Score Ranges:

• 75-100: Great - Production-ready code
• 50-74: Needs Work - Address warnings before release
• 0-49: Critical - Blockers must be fixed

Rule Categories (~280 rules)

Progressive Loading:

• Core Rules (~100 tokens) - Always loaded
• Spring/Boot Rules (~500 tokens) - Loaded if Spring detected
• gRPC Rules (~600 tokens) - Loaded if gRPC detected
• JPA Rules (~300 tokens) - Loaded if JPA detected
• Build Rules (~200 tokens) - Always checked

1. Security (CRITICAL - Always Check First)

2. Null Safety & Correctness

3. Exception Handling

4. Performance

5. Concurrency & Thread Safety

6. Resource Management

7. Spring Framework Specific

7.1 Spring Boot 4.x Specific (If Spring Boot 4.x detected)

8. Modern Java & Effective Java (Version Aware)

9. Architecture & Design

10. Logging & Debugging

11. Testing

12. API Design & REST

13. Best Practices

14. Google Checkstyle Rules (Formatting & Style)

Based on Google Java Style Guide - checks for code formatting, naming, and style:

15. gRPC Java Best Practices

Load if gRPC detected: pom.xml contains grpc-java, grpc-protobuf, or .proto files exist

16. gRPC Security Rules

Load if gRPC detected

17. JPA / Hibernate Rules

Load if JPA detected: pom.xml contains hibernate, spring-data-jpa, or jpa

18. Lombok Rules

Load if Lombok detected: pom.xml contains lombok

19. Build Tools - Maven/Gradle Rules (20 rules)

Always check build files for best practices

20. Virtual Threads & Structured Concurrency (Java 21+)

Load if Java 21+ detected — checks for common pitfalls when adopting virtual threads and structured concurrency patterns.

Virtual Threads Detection Patterns:

// VT-001: synchronized pinning virtual thread (CRITICAL)
// BAD — pins the carrier thread
synchronized (lock) {
    httpClient.send(request, handler); // Blocking I/O inside synchronized!
}
// GOOD — use ReentrantLock
private final ReentrantLock lock = new ReentrantLock();
lock.lock();
try {
    httpClient.send(request, handler);
} finally {
    lock.unlock();
}

// VT-002: ThreadLocal with virtual threads (ERROR)
// BAD — creates copy per virtual thread, memory bloat at scale
private static final ThreadLocal<UserContext> context = new ThreadLocal<>();
// GOOD — ScopedValue (Java 21+ preview, stable Java 25+)
private static final ScopedValue<UserContext> CONTEXT = ScopedValue.newInstance();
ScopedValue.where(CONTEXT, userCtx).run(() -> handleRequest());

// VT-005: Missing StructuredTaskScope (SUGGESTION)
// BAD — unstructured fan-out
CompletableFuture<User> userFuture = CompletableFuture.supplyAsync(() -> getUser(id));
CompletableFuture<Order> orderFuture = CompletableFuture.supplyAsync(() -> getOrder(id));
User user = userFuture.join();
Order order = orderFuture.join();
// GOOD — structured concurrency
try (var scope = StructuredTaskScope.ShutdownOnFailure()) {
    Subtask<User> user = scope.fork(() -> getUser(id));
    Subtask<Order> order = scope.fork(() -> getOrder(id));
    scope.join().throwIfFailed();
    return new UserOrder(user.get(), order.get());
}

// VT-010: Missing try-with-resources on StructuredTaskScope (ERROR)
// BAD — scope not auto-closed
var scope = new StructuredTaskScope.ShutdownOnFailure();
scope.fork(() -> fetchData());
scope.join();
// GOOD
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
    scope.fork(() -> fetchData());
    scope.join().throwIfFailed();
}

21. Testing Depth (Extended)

Always load — comprehensive testing rules beyond the basics in Section 11.

Testing Depth Detection Patterns:

// TEST-009: Missing JaCoCo coverage threshold
// CHECK pom.xml for:
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>check</id>
            <goals><goal>check</goal></goals>
            <configuration>
                <rules>
                    <rule>
                        <limits>
                            <limit>
                                <counter>LINE</counter>
                                <minimum>0.80</minimum>
                            </limit>
                        </limits>
                    </rule>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>
// CHECK build.gradle for:
jacocoTestCoverageVerification {
    violationRules {
        rule { limit { minimum = 0.80 } }
    }
}

// TEST-010: Testcontainers usage
// BAD — H2 behaves differently from production DB
@DataJpaTest // Uses H2 by default
class UserRepositoryTest { }
// GOOD — real database in container
@DataJpaTest
@Testcontainers
class UserRepositoryTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
}

// TEST-011: Thread.sleep() in tests (ERROR)
// BAD — flaky, wastes time
@Test
void shouldProcessAsync() {
    service.processAsync(data);
    Thread.sleep(2000); // Fragile!
    assertNotNull(repository.findResult());
}
// GOOD — Awaitility
@Test
void shouldProcessAsync() {
    service.processAsync(data);
    await().atMost(5, SECONDS).until(() -> repository.findResult() != null);
}

// TEST-012: Order-dependent tests (ERROR)
// BAD — tests depend on execution order
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
class UserServiceTest {
    @Test @Order(1) void createUser() { /* creates state */ }
    @Test @Order(2) void findUser() { /* depends on createUser */ }
}
// GOOD — each test is independent
class UserServiceTest {
    @BeforeEach void setUp() { /* fresh state for each test */ }
    @Test void createUser() { }
    @Test void findUser() { /* creates its own test data */ }
}

// TEST-014: JUnit assertions vs AssertJ (SUGGESTION)
// OK but verbose
assertEquals("John", user.getName());
assertTrue(users.contains(admin));
// BETTER — AssertJ fluent API
assertThat(user.getName()).isEqualTo("John");
assertThat(users).contains(admin).hasSize(3);

22. Dead Code Detection

Detects unused code - runs in parallel with lint checks

Dead Code Detection Patterns:

// DEAD-001: Unused public method - may be used by reflection or external code
// Only mark as dead code if you're certain no external usage exists
public void unusedPublicMethod() { } // Check for @Api exposure first

// DEAD-004: Unused import
import java.util.List; // If List is never used

// DEAD-009: Unreachable code
public int method() {
    return 1;
    return 2; // Unreachable - remove
}

// DEAD-010: Duplicate code
public class UserService {
    public void createUser(User user) {
        validateUser(user); // Same validation duplicated
        userRepository.save(user);
        sendEmail(user.getEmail());
    }
    
    public void updateUser(User user) {
        validateUser(user); // Duplicate!
        userRepository.save(user);
    }
    
    private void validateUser(User user) { /* ... */ }
}

// DEAD-011: Empty catch block
try {
    riskyOperation();
} catch (Exception e) {
    // Empty! At least log the error
}

Review Modes

Mode 1: Local Changes (Default)

Review uncommitted changes in working directory.

git status --porcelain
git diff
git diff --cached

Mode 2: Branch Comparison

Compare feature branch against base (develop/main/master).

git branch --show-current
git diff <base-branch>..HEAD -- "*.java"
git log <base-branch>..HEAD --oneline

Mode 3: Specific Files

Analyze specific Java files.

git diff <commit> -- path/to/File.java

Install for Your Coding Agent

Teach your coding agent all Java best practice rules. Add this skill to your agent:

npx skills add ajaywadhara/java-doctor

Supports Cursor, Claude Code, Amp Code, Codex, Gemini CLI, OpenCode, Windsurf, and Antigravity.

Analysis Workflow

1. Detect Java Version

   • Parse pom.xml or build.gradle
   • Note supported features for that version

2. Collect Java Files

   • If reviewing changes: git diff --name-only -- "*.java"
   • If reviewing branch: git diff <base>..HEAD --name-only -- "*.java"
   • If specific files: Use user-provided paths

3. Run Pattern Analysis

   • Use Grep to search for each rule pattern
   • Read relevant code sections for context

4. Calculate Score

   • Start with 100
   • Deduct based on severity table

5. Generate Report

   • Save to .output/java-doctor-{context}-{timestamp}.md

Output Format

Save reports to .output/ directory. Multiple formats available:

Format 1: Markdown (Default)

Save report to .output/java-doctor-{context}-{timestamp}.md:

# Java Doctor Report

## Summary
| Metric | Value |
|--------|-------|
| **Score** | X/100 |
| **Status** | Great / Needs Work / Critical |
| **Java Version** | X (detected from pom.xml/build.gradle) |
| **Files Analyzed** | N |
| **Issues Found** | CRITICAL: X, ERROR: X, WARNING: X, SUGGESTION: X |

## Files Analyzed
- `src/main/java/com/example/Service.java`
- `src/main/java/com/example/Controller.java`

## Issues by Category

### Security (CRITICAL)
1. **[File:Line]** - SEC-001: Hardcoded password found
   - **Severity:** CRITICAL
   - **Problem:** `private static final String PASSWORD = "********";`
   - **Fix:** Use environment variable or configuration

## Recommendations
1. Fix all CRITICAL issues immediately
2. Address ERROR issues before release
3. Review WARNING issues for improvement
4. Consider SUGGESTIONS for code quality

## Quick Fixes Available
- [ ] SEC-001: Replace hardcoded secret with @Value injection
- [ ] NULL-001: Replace .get() with orElseThrow()
- [ ] PERF-001: Add @Query with JOIN FETCH

Format 2: JSON

Save to .output/java-doctor-{context}-{timestamp}.json:

{
  "report": {
    "generated": "2024-01-15T10:30:00Z",
    "score": 85,
    "status": "Great",
    "javaVersion": "17",
    "springBootVersion": "3.2",
    "filesAnalyzed": 5
  },
  "issues": {
    "critical": [
      {
        "id": "SEC-001",
        "file": "src/main/java/com/example/AuthService.java",
        "line": 42,
        "title": "Hardcoded password found",
        "problem": "private static final String PASSWORD = \"********\";",
        "fix": "Use @Value injection or environment variable"
      }
    ],
    "error": [],
    "warning": [
      {
        "id": "NULL-001",
        "file": "src/main/java/com/example/UserService.java",
        "line": 15,
        "title": "Optional.get() without check",
        "problem": "userRepository.findById(id).get()",
        "fix": "Use .orElseThrow(() -> new NotFoundException())"
      }
    ],
    "suggestion": []
  },
  "summary": {
    "total": 12,
    "critical": 1,
    "error": 2,
    "warning": 5,
    "suggestion": 4
  }
}

Format 3: HTML Report

Save to .output/java-doctor-{context}-{timestamp}.html:

<!DOCTYPE html>
<html>
<head>
    <title>Java Doctor Report</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .score { font-size: 48px; font-weight: bold; }
        .great { color: #22c55e; }
        .needs-work { color: #eab308; }
        .critical { color: #ef4444; }
        .issue { border: 1px solid #ddd; padding: 10px; margin: 10px 0; }
        .critical-issue { border-left: 4px solid #ef4444; }
        .error-issue { border-left: 4px solid #f97316; }
        .warning-issue { border-left: 4px solid #eab308; }
    </style>
</head>
<body>
    <h1>Java Doctor Report</h1>
    <div class="score great">85/100</div>
    <p><strong>Status:</strong> Great</p>
    <p><strong>Java Version:</strong> 17</p>
    <p><strong>Files Analyzed:</strong> 5</p>
    
    <h2>Issues Found: 12</h2>
    <p>CRITICAL: 1 | ERROR: 2 | WARNING: 5 | SUGGESTION: 4</p>
    
    <h3>Critical Issues</h3>
    <div class="issue critical-issue">
        <strong>SEC-001:</strong> Hardcoded password found<br>
        <code>src/main/java/com/example/AuthService.java:42</code><br>
        Fix: Use @Value injection
    </div>
</body>
</html>

Format 4: SARIF (For IDE Integration)

Save to .output/java-doctor-{context}-{timestamp}.sarif:

{
  "version": "2.1.0",
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "runs": [{
    "tool": {
      "driver": {
        "name": "Java Doctor",
        "version": "1.0"
      }
    },
    "results": [
      {
        "ruleId": "SEC-001",
        "level": "error",
        "message": { "text": "Hardcoded password found" },
        "locations": [{
          "physicalLocation": {
            "artifactLocation": { "uri": "src/main/java/com/example/AuthService.java" },
            "region": { "startLine": 42 }
          }
        }]
      }
    ]
  }]
}

Format 5: CSV (For Excel/Sheets)

Save to .output/java-doctor-{context}-{timestamp}.csv:

Severity,Rule ID,File,Line,Issue,Problem,Fix
CRITICAL,SEC-001,src/main/java/com/example/AuthService.java,42,Hardcoded password found,"private static final String PASSWORD = \"********\";","Use @Value injection"
WARNING,NULL-001,src/main/java/com/example/UserService.java,15,Optional.get() without check,userRepository.findById(id).get(),Use orElseThrow()

Default format is Markdown. To request a different format, specify in your command:

• "Run Java Doctor with JSON output"
• "Generate HTML report"
• "Export to CSV"

Effective Java Reference

Based on "Effective Java" by Joshua Bloch:

---

## Interactive Workflow

After analysis, ask user what to do:

Question: "Java Doctor scan complete. Score: X/100 ({Status}). Found {N} issues." Header: "Next Steps" Options:

• "Show me the issues" → Display all issues grouped by severity
• "Fix critical issues" → Apply fixes for CRITICAL issues
• "Fix all issues" → Apply fixes for all issues
• "Save report" → Save to .output/ directory
• "Re-scan" → Re-run analysis

---

## Quick Commands

| User Says | Your Action |
|-----------|-------------|
| "Run Java Doctor" | Full scan with version detection |
| "Scan my Java code" | Analyze local changes |
| "Check for security issues" | Focus on security rules |
| "Find performance problems" | Focus on performance rules |
| "Java code review" | Full analysis with all rules |
| "Check branch vs develop" | Branch comparison mode |
| "What's my score?" | Run scan and show score |

---

## References (Load When Needed)

- `references/bug-patterns.md` - Detailed bug patterns with code examples
- `references/security-checklist.md` - OWASP Top 10 for Java
- `references/performance-antipatterns.md` - N+1, memory, CPU issues
- `references/spring-best-practices.md` - Spring-specific rules
- `references/effective-java-mapping.md` - Items mapped to rules
- `references/version-specific-changes.md` - Java 8-21 changes
- `references/virtual-threads-guide.md` - Virtual threads & structured concurrency patterns
- `references/testing-depth-guide.md` - Testing depth rules with examples

---

This skill is inspired by react-doctor but tailored specifically for Java, incorporating best practices from "Effective Java" by Joshua Bloch and version-aware checks for Java 8 through 21.