migrate-nullable-references

What it does

Instructs an AI coding agent to perform a nullable reference type (NRT) migration on an existing C# project or solution. The aim is to switch to <Nullable>enable</Nullable> (or manage via a staged approach), systematically resolve CS8602/CS8618/CS86xx warnings, annotate public APIs for nullability, clean up null-forgiving operators, and adapt dependencies with new nullable annotations. It supports both file-by-file and project-wide migrations and outlines a commit strategy that creates discrete, reviewable changes across several steps.

How it works

• The skill targets enabling NRTs in an existing codebase and requires generating a project (or solution) with <Nullable>enable</Nullable>, zero nullable warnings, and correctly annotated public APIs.
• It is used when enabling NRTs in an existing project, resolving dereference warnings, annotating declarations, applying nullable attributes, and cleaning up suppressions (Steps 2–6).
• It prescribes a step-by-step workflow with a strong emphasis on not changing runtime behavior: only metadata changes such as nullable annotations, NotNullWhen attributes, and nullable directives are allowed; any latent runtime bugs discovered should be deferred with TODO comments for separate fixes.
• It defines a commit strategy: commit after enabling Nullable, after fixing dereference warnings, after annotating declarations, after applying nullable attributes, and after cleaning up suppressions.
• It provides guidance on how to handle build and readiness checks, including language/framework suitability checks (C# 8.0+ and compatible targets), and whether to proceed based on existing Nullable and warnings state.
• It includes detailed guidance for handling common dereference warnings (CS8602, CS8600, CS8603, CS8604) and explicit rules about when to use nullable markers, null-forgiving operators, or guard checks.

When to use it

• Enabling nullable reference types in an existing C# project or solution.
• Systematically resolving CS86xx nullable warnings after enabling NRTs.
• Annotating a library’s public API surface for accurate nullability information.
• Upgrading a dependency that introduces new nullable annotations and warnings.
• Analyzing suppressions in a codebase with NRTs to determine possible removals.

What it can touch

• The policy discusses touching project files to add <Nullable>enable</Nullable> (or <Nullable>warnings</Nullable> during staged strategies).
• It covers annotations on public API surface and various code declarations to reflect intended nullability (e.g., adding ?, NotNullWhen, and related metadata-only changes).
• It references commands and tools for readiness checks and builds but the concrete touched items are primarily code entities and project properties as part of the migration process.

Caveats

• Runtime behavior must not be altered; changes are metadata-only where possible (nullable annotations, directives, and certain attributes).
• If a latent bug is discovered during migration, the recommended action is to add a TODO comment suggesting a separate fix (e.g., ArgumentNullException.ThrowIfNull) rather than addressing it inline in this migration step.
• The workflow emphasizes committing at natural boundaries and starting with core types to minimize cascading warnings.
• It cautions against enabling NRTs on projects that target C# 7.3 or earlier and outlines what to do if language/framework requirements are not met.