UKHO.GitHubCopilot.ToolKit refactoring.instructions.md

Refactoring guidance

Overview

These instructions define how refactoring work should be performed in this repository. The goal is to improve readability, maintainability, testability, and structure without changing intended behavior unless the work item explicitly calls for a functional change.

Scope

Applies to: src/**/*.cs, src/**/*.razor, src/**/*.razor.cs, test/**/*.cs

• Applies when restructuring existing production or test code under src/ and test/.
• These rules are additive to /.github/copilot-instructions.md, /.github/instructions/csharp.instructions.md, /.github/instructions/tests.instructions.md, and any feature-specific instruction files.
• For Blazor code, apply these rules to component markup, code-behind, and related view-model logic together.

Instructions

MUST

• Preserve observable behavior unless the request explicitly includes a behavior change.
  • Treat routes, request and response shapes, rendered UI outcomes, validation rules, configuration keys, dependency injection registrations, service lifetimes, and persistence contracts as observable behavior.
• Apply established design principles when refactoring.
  • Use Separation of Concerns to keep UI, application, domain, infrastructure, and test responsibilities distinct.
  • Use the Single Responsibility Principle to ensure a type, component, or method has one clear reason to change.
  • Use Dependency Inversion and Explicit Dependencies to depend on abstractions and constructor-injected collaborators instead of hidden ambient state or concrete infrastructure details.
  • Use DRY to remove true duplication by centralizing shared behavior in one authoritative implementation.
• Prefer compiler-assisted or IDE-assisted refactorings for structural changes.
  • Use safe rename for symbols instead of manual search-and-replace.
  • Use extract method, extract local function, extract interface, move type to matching file, sync namespace and folder name, and move declaration near reference when those operations match the intended change.
• Review rename and move previews before applying changes when the refactoring spans multiple files, projects, or public-facing symbols.
• Keep each refactoring step small enough that build failures and regressions can be localized to a narrow change.
• Add or update automated tests when a refactor touches behavior-critical logic or when existing coverage is missing for the refactored path.
  • Regression-focused tests MUST verify behavior, not implementation details.
• Preserve public contracts unless the request explicitly authorizes changing them.
• Preserve nullable annotations, asynchronous behavior, cancellation flow, and exception semantics unless the request explicitly authorizes changing them.
• When extracting shared logic, introduce the narrowest abstraction that removes current duplication or clarifies an existing responsibility.
• When moving or splitting C# types, keep one top-level type per file and ensure the file name, type name, folder, and namespace remain aligned.
• Introduce seams for testability through explicit dependencies and dependency injection rather than through hidden ambient state, service location, or direct instantiation of infrastructure-heavy collaborators.
• Validate the result after refactoring by running a build and the relevant automated tests for the affected area.