Null Safety and Optional Handling Prompt

This prompt is designed for engineering teams that want to automate the detection of null pointer exceptions, improper optional unwrapping, and missing null guards in code changes. It reviews a pull request diff and produces a structured list of unsafe access patterns with fix suggestions. Use this prompt in CI/CD pipelines, pre-merge review checks, or as part of a developer's local workflow. It is most effective for languages with explicit nullability concerns such as Java, Kotlin, Swift, TypeScript (strict mode), C#, and Rust. The prompt assumes a unified diff format as input and does not execute code. It is a static analysis reasoning layer, not a replacement for a compiler or a human reviewer on critical paths.

The prompt requires a unified diff as the primary [INPUT]. For best results, provide additional [CONTEXT] such as the language version, nullability annotations used in the project (e.g., @NonNull, ?), and any team-specific conventions for optional handling. The expected [OUTPUT_SCHEMA] is a JSON array of findings, where each object includes the file path, line number, unsafe pattern description, severity (CRITICAL, HIGH, MEDIUM), and a concrete fix suggestion. You must validate that the output line numbers map to actual lines in the input diff; a hallucinated line reference is a common failure mode that should trigger a retry or human review. For high-risk codebases such as payment processing or safety-critical systems, always require a human to approve findings marked CRITICAL before merging.

Do not use this prompt for languages without nullability concepts, for runtime null analysis, or for diffs that exceed the model's context window without chunking. The prompt identifies patterns, not guaranteed exploits—it will miss null risks that depend on runtime state or cross-method invariants. Pair this prompt with a static analysis tool and treat its output as an additional review layer, not a sole gate. For production CI/CD integration, wrap the prompt in a harness that validates output schema, retries on malformed JSON, logs every finding with the commit SHA, and routes CRITICAL findings to a human approval queue before the merge can proceed.

This section provides the core prompt for analyzing a pull request diff to identify potential null pointer exceptions, improper optional unwrapping, and missing null guards. The template is designed to be copied directly into your AI harness, CI/CD pipeline, or local development workflow. Replace the square-bracket placeholders with your specific diff content, target language, and output preferences before sending it to the model. The prompt is structured to produce a machine-readable JSON output, making it suitable for integration with code review tools and automated quality gates.

textCopy
You are a senior software engineer specializing in null safety and defensive programming. Your task is to review the provided code diff for potential null pointer exceptions, improper optional unwrapping, and missing null guards.

## INPUT
[DIFF]

## LANGUAGE CONTEXT
[LANGUAGE] (e.g., Java, Kotlin, Swift, TypeScript, Python with type hints)

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "findings": [
    {
      "file": "string (relative file path)",
      "line": "number (the line in the new file where the issue occurs)",
      "severity": "HIGH | MEDIUM | LOW",
      "category": "NULL_DEREFERENCE | UNSAFE_UNWRAP | MISSING_GUARD | REDUNDANT_CHECK | INCONSISTENT_NULLABILITY",
      "description": "string (clear explanation of the risk)",
      "suggestion": "string (concrete fix, including code pattern or language-specific idiom)",
      "context_snippet": "string (the relevant 2-3 lines from the diff)"
    }
  ],
  "summary": {
    "total_findings": "number",
    "high_severity": "number",
    "medium_severity": "number",
    "low_severity": "number",
    "risk_assessment": "SAFE | CAUTION | UNSAFE"
  }
}

## CONSTRAINTS
- Only report findings that are introduced or affected by the diff. Do not flag pre-existing issues in unchanged code unless the diff makes them reachable.
- For [LANGUAGE], use language-specific idioms: Optional chaining (?.) and nullish coalescing (??) for JavaScript/TypeScript; `Optional.ofNullable` or `@Nullable` annotations for Java; `if let`, `guard let`, or nil-coalescing for Swift; safe call (?.) and Elvis (?:) for Kotlin.
- If the diff adds a public API, flag any parameter or return type that is nullable without documentation.
- If a finding is a false positive due to a framework guarantee or an invariant enforced elsewhere, do not include it.
- Do not suggest removing null checks unless they are provably redundant and the removal does not introduce risk.

## EXAMPLES
Input diff line: `String name = user.getName();` followed by `name.toLowerCase();`
Output finding: HIGH severity, NULL_DEREFERENCE, "user.getName() may return null, but the result is dereferenced without a null check on the next line."

Input diff line: `val value = optional.get()` without a preceding `isPresent()` check.
Output finding: HIGH severity, UNSAFE_UNWRAP, "Calling optional.get() without checking isPresent() will throw NoSuchElementException if the Optional is empty."

## RISK_LEVEL
[RISK_LEVEL] (e.g., CRITICAL_PATH, STANDARD, LOW_RISK) - If CRITICAL_PATH, flag even LOW severity findings and require explicit nullability annotations on all new public methods.

To adapt this template for your workflow, replace the [DIFF] placeholder with the actual unified diff output from your version control system. Set [LANGUAGE] to the primary language of the codebase, as this controls the idioms suggested in fix recommendations. The [RISK_LEVEL] parameter adjusts the strictness of the review: use CRITICAL_PATH for authentication, payment, or data integrity code where any null dereference is unacceptable; use STANDARD for general application code; use LOW_RISK for internal tooling or scripts where a failure is tolerable. The output JSON is designed to be parsed by a validation harness that can check line numbers against the actual diff, verify that context snippets match the referenced code, and route HIGH severity findings for mandatory human review before merge.

The null safety prompt is designed to be called programmatically as part of a PR review workflow. It expects a raw diff as input and returns a structured JSON payload of findings. The implementation harness should treat this prompt as a deterministic analysis step: same diff, same model, same temperature (0) should produce consistent results. Wire it into your CI pipeline as a non-blocking check for non-critical paths, or as a blocking check with a human override for repositories where null safety is a hard gate. For local use, integrate it into a pre-commit hook that runs the prompt against staged changes and surfaces findings before the commit is finalized.

The harness must validate the model's output against a strict JSON schema before accepting it. Each finding object requires file, line, severity, pattern, and suggestion fields. If the model returns malformed JSON or missing required fields, retry once with a repair prompt that includes the raw output and the schema. If the retry also fails, log the failure and fall back to a human review flag. For high-risk repositories (e.g., payment processing, safety-critical systems), route all critical severity findings to a human approval queue before the PR can merge. Use a model with strong code understanding and JSON mode support—Claude 3.5 Sonnet or GPT-4o are good defaults. Avoid smaller or older models that may hallucinate line numbers or miss language-specific null patterns like Swift's force-unwrap or Kotlin's !! operator.

Log every prompt invocation with the diff hash, model version, findings count, and validation status. This creates an audit trail for debugging false positives and tracking prompt drift over time. For evaluation, maintain a golden dataset of diffs with known null safety issues and run the prompt against it on every prompt change. Measure precision (are flagged lines actually unsafe?) and recall (did it miss known issues?). If false positive rates exceed 15% on your golden set, tune the prompt's [CONSTRAINTS] or add few-shot examples of safe patterns that the model is over-flagging. Do not ship a prompt update without running it against your eval set first.