Refactor Loop

Dependency Rules

The following direction is enforced by architecture tests:

uk.osric.web → feature modules → uk.osric.common.web → uk.osric.common

Do not introduce cycles. If a helper is needed by a project that currently does not reference uk.osric.common, add the reference explicitly and verify it does not introduce a cycle.

The Loop — Step by Step

1. Scope

• Identify every callsite of the code to be extracted.
• Note the exact method signature(s) and any variations across callsites.
• Record which test files (if any) already cover the code.

2. Write Behavioral Tests First

• Use the write-behavioural-tests skill to add tests in uk.osric.fast that lock the current behavior.
• Run dotnet test tests/uk.osric.fast — all tests must pass before proceeding.
• If a test reveals a latent bug, document it but do not fix it as part of this refactor.

3. Create the Shared Helper

• Add the new method/class in the correct shared project (uk.osric.common or uk.osric.common.web).
• Use the tightest practical access modifier (internal if only used within the project, public if shared across assemblies).
• Seal implementation classes unless inheritance is explicitly required.
• Mirror the exact behavior of the original code — no new logic at this step.

4. Update Callsites

• Replace every callsite with a call to the new shared helper.
• Remove the original private/local copy.
• Add missing using or <ProjectReference> entries as needed.

5. Build and Test

dotnet build --configuration Release
dotnet test tests/uk.osric.fast

• All tests must pass before the task is considered complete.
• If tests fail, fix the root cause — do not comment out or skip tests.
• Do not mark the task done until the full loop completes green.

6. Commit

• Commit with a message that explains the why: e.g. refactor: extract SqliteConnectionString helper to uk.osric.common.
• Include the Co-authored-by trailer.

7. Update TODO.md

• Mark the completed item with ~~...~~ ✅ Done.

Common Failure Modes

References

• write-behavioural-tests skill
• AGENTS.md
• Verification checklist