# Refactor Mode Rules

## Goal

This project is undergoing a large-scale refactor.

The objective is to improve maintainability, consistency, architecture, performance, and developer experience while preserving existing functionality.

## Analysis First

* Before making changes, identify the complete flow related to the requested feature.
* Trace controllers, services, models, requests, policies, views, Blade components, routes, jobs, events, and tests involved in the flow.
* Present a summary of findings before major refactoring work begins.

## Preserve Behaviour

* Existing functionality must remain unchanged unless explicitly requested.
* Refactor implementation, not business requirements.
* Maintain backward compatibility where possible.

## Architecture

* Consolidate duplicated logic.
* Remove dead code only when confirmed unused.
* Extract reusable services when duplication exists.
* Extract reusable Blade components when markup duplication exists.
* Move business logic out of controllers and views.
* Keep controllers focused on orchestration.

## Blade Rules

* Keep Blade templates presentation-focused.
* Avoid complex conditional logic in views.
* Avoid database queries in Blade templates.
* Reuse layouts, partials, and components.
* Consolidate duplicated UI patterns.

## Naming Consistency

* Use consistent naming conventions across:

  * Controllers
  * Services
  * Actions
  * DTOs
  * Events
  * Jobs
  * Policies
  * Blade components

* Rename unclear classes and methods when it improves maintainability.

## Database

* Review query efficiency.
* Eliminate N+1 issues.
* Standardize eager loading patterns.
* Identify missing indexes.
* Prefer additive migrations.

## Frontend Assets

* Remove unused CSS and JavaScript where safe.
* Consolidate duplicated scripts.
* Follow existing frontend conventions.

## Refactor Strategy

* Perform refactors in logical phases.
* Complete one subsystem before moving to another.
* Keep changes grouped by responsibility.
* Avoid mixing unrelated refactors in a single change set.

## Testing

* Update existing tests as part of refactoring.
* Add tests where coverage is missing.
* Run the minimum relevant tests for each subsystem.
* Verify behavior before and after major changes.

## Documentation

* Document architectural decisions made during the refactor.
* Explain why a structure was changed, not just what changed.

## Reporting

After each refactor task provide:

1. Files modified.
2. Architectural improvements made.
3. Performance improvements identified.
4. Technical debt removed.
5. Remaining refactor opportunities.


## Technical Debt Review

During analysis, identify:

- Fat controllers
- Fat models
- Duplicated validation
- Duplicated Blade markup
- Duplicated queries
- Unused routes
- Unused views
- Unused services
- Missing tests
- Inconsistent naming

Report findings before implementation.