Use this skill when the code already works but is becoming hard to trust, test, or extend because the business rules are scattered across transport and persistence code.
Refactor Loop
- Find the use case from the edge of the system.
- Start from HTTP handlers, gRPC methods, commands, repository callbacks, or transaction blocks.
- Write down the business operation in plain language before introducing any new types.
- Extract the rules hiding inside conditionals.
- Look for "walls of
if" that decide whether something may happen. - Turn those rules into invariants and behavior methods on a domain type.
- Create or tighten the domain type.
- Prefer constructors that reject invalid state.
- Prefer private fields when external mutation would bypass invariants.
- Replace setters with behavior methods named in business language.
- Make the domain database-agnostic.
- Remove Firestore, SQL, protobuf, or HTTP concerns from domain packages.
- Introduce separate persistence models if storage shape differs from the domain shape.
- Rebuild the repository boundary.
- Put the repository interface next to the code that consumes it.
- Prefer generic repository capabilities such as load or update over repository methods that mirror every business action.
- Use closure-based update methods when the write requires transactional read-modify-save behavior.
- Add black-box tests around the domain.
- Test exported behavior, not private fields.
- Use helpers that create meaningful domain objects such as "available hour" or "canceled training".
- Keep mocks out of domain tests.
- Shrink the old code paths.
- Make handlers, services, and repositories delegate to the new domain behavior.
- Delete duplicated validation once the domain enforces it reliably.
Guardrails
- Do not invent entities and value objects unless they clarify real business behavior.
- Do not move pure transport validation into the domain unless it is a business rule.
- Do not leak database transaction types or clients into the domain.
- Do not keep public writable fields just because the old code used them.
Use These References
- Read references/domain-rules.md for the core rules adapted for this skill pack.
- Read references/refactor-playbook.md for a step-by-step migration path and anti-pattern checklist.
Deliverables
- behavior-oriented domain methods,
- constructors or factories that enforce validity,
- narrowed repository contracts,
- removed duplicated business checks from handlers or adapters,
- focused domain tests that describe the behavior in business terms.