# GitHub Copilot Repository Instructions: C++23 Modernization

## Context
- Language: C++
- Target standard: C++23
- Goal: modernize legacy C++11/14/17 code safely and incrementally

## Primary Rule
Preserve existing behavior unless functional changes are explicitly requested.

## Balanced Modernization Policy
- Prefer modern C++23 constructs when they clearly improve safety, readability, or maintainability.
- Keep refactors focused and reviewable; avoid broad rewrites unless requested.
- Prefer standard library solutions over custom or legacy patterns.
- Respect toolchain limitations, ABI-sensitive interfaces, and repository-local style.

## Preferred Modernizations
- Use `auto` where the type is obvious from the initializer; avoid it when it hides important type information.
- Prefer structured bindings over `std::tie` or manual pair/tuple access when clearer.
- Replace raw owning pointers and manual `delete` with RAII, usually `std::unique_ptr`.
- Use `std::make_unique` and `std::make_shared`; prefer `std::shared_ptr` only for real shared ownership.
- Use `std::string_view` for read-only string parameters only when lifetime safety is clear.
- Prefer `std::span` for non-owning contiguous ranges.
- Use `std::mdspan` only when multidimensional access is central and the change improves clarity or safety.
- Prefer `.contains()` over `find(...) != end()` where available and clearer.
- Prefer standard algorithms and ranges over manual loops when readability improves.
- Use `[[nodiscard]]` where ignoring the result is likely a bug.
- Prefer early returns over deeply nested control flow.
- Use `std::optional` monadic operations (`and_then`, `transform`, `or_else`) when they make the code simpler.
- Prefer `constexpr`, `if constexpr`, concepts, and `requires` over legacy `std::enable_if` / SFINAE where practical.
- Add `noexcept`, `override`, `final`, `= default`, and `= delete` where correct and useful.
- Prefer `enum class` over unscoped enums where practical.
- Prefer `std::print` / `std::println` for console output when supported by the project toolchain.
- Prefer typed `std::chrono` durations and `std::jthread` where appropriate.

## Avoid
- Do not modernize mechanically if readability becomes worse.
- Do not introduce unsupported C++23 features.
- Do not introduce dangling references, dangling `std::string_view`, or unclear ownership.
- Do not silently change ABI, object lifetime, exception behavior, or performance characteristics.
- Do not rewrite unrelated code.

## Expected Copilot Behavior
When making migration suggestions:
- produce small, focused updates
- explain non-trivial changes briefly
- call out risky refactors explicitly
- note compatibility or toolchain caveats
- leave optional follow-up improvements separate

## Preferred Output
Provide:
- updated code
- short rationale
- compatibility/toolchain caveats
- optional next modernization steps