codebase-refactor

name	codebase-refactor
description	Systematic codebase refactoring and reorganization following SOLID principles, strict naming conventions (with banned patterns), DRY consolidation, defensive programming, mirrored frontend/backend structure, async error handling, and a phased refactoring process with deliverables checklist.
user-invokable	true
args	[{"name":"target","description":"The project or codebase area to refactor (optional)","required":false}]

Follow every principle below rigorously. Do not skip steps, do not guess—research, verify, and validate before making changes.

1. Guiding Principles

SOLID Principles

• SRP: Every module has exactly one reason to change.
• OCP: Open for extension, closed for modification.
• LSP: Subtypes substitutable without breaking behavior.
• ISP: No module forced to depend on methods it doesn't use.
• DIP: High-level logic depends on abstractions, not implementations.

Core Philosophies

• KISS: Simplest correct solution wins.
• YAGNI: Don't build for hypothetical futures.
• DRY: Single authoritative representation (but don't couple unrelated things).
• Separation of Concerns: Each layer addresses one concern.
• Composition Over Inheritance: Combine simple pieces over deep hierarchies.
• Principle of Least Surprise: Code behaves as the name suggests.
• Fail Fast, Fail Loud: Detect errors at earliest point, surface immediately.

Defensive Programming

• Validate at boundaries. Trust nothing from outside your system.
• Use type systems aggressively. Avoid any, untyped signatures.
• Make illegal states unrepresentable (discriminated unions, enums).
• Prefer immutability. Mutate only with clear justification.

2. Naming & Nomenclature Standards

Banned Naming Patterns

Banned Pattern	Why Harmful	What to Do Instead
EnhancedWidget / ImprovedWidget	Implies non-enhanced version exists	Name for what it does: WidgetWithValidation
NewUserService / OldUserService	"New" is only new today	UserService. Period.
BetterParser / FastParser	Subjective, unverifiable	Name the mechanism: StreamingParser
utils2.js / helpers_new.py	Versioned filenames signal fear	One file. One name. Delete the old one.
temp_, test_, my_, foo, bar	Non-descriptive placeholders	Name for what it does
data, info, item, thing, stuff	Semantically empty	Name the domain concept
_backup, _copy, _orig, _fixed	Narrates changelog in the name	Strip the suffix. Git provides history.

Positive Naming Principles

• Describe behavior, not history.
• Describe what, not how (public APIs). How, not what (private helpers).
• Use domain language (ubiquitous language).
• Booleans read as true/false questions: isAuthenticated, hasPermission.
• Collections are plural. Single items singular.
• Constants: UPPER_SNAKE_CASE with meaningful names.

3. Directory Structure

project-root/
├── frontend/
├── backend/
├── shared/          # Types, constants, utilities shared between FE & BE
├── scripts/
├── docs/
│   ├── decisions/   # Architecture Decision Records
│   └── glossary.md  # Domain term → code name mapping
├── .github/
├── docker/
└── README.md

4. Mirrored Naming

Concept	Frontend Path	Backend Path
Auth	frontend/src/features/auth/	backend/src/features/auth/
API client / route	frontend/src/api/users.ts	backend/src/routes/users.py
Types / Schemas	frontend/src/types/user.ts	backend/src/schemas/user.py

Same domain noun across both sides. Group by feature, not by technical role.

5. Eliminating Code Duplication

1. Identify — Flag every duplicated function, component, type.
2. Consolidate — Extract to single module in appropriate location.
3. Re-export — Update all consumers.
4. Validate — Confirm no orphaned copies remain.

6. Modularity & Extensibility

• No function exceeds ~50 lines. No file exceeds ~300 lines.
• Frontend: separate presentational from container components.
• Backend: Routes → Services → Repositories layered architecture.
• Every public function has documentation.

7. Async & Error Handling

• Never use bare try/catch that swallows errors silently.
• Never use catch (e) {}.
• All Promises must be handled.
• Timeouts mandatory on all external calls.
• Structured logging with timestamp, operation, correlation ID, stack trace.
• Prefer Result<T, E> for expected failures; exceptions for unexpected.

8. Commenting Standards

• Section headers with clear comment blocks.
• Comments explain why, not what.
• TODO/FIXME tags with name and date.
• Architecture Decision Records for significant choices.

9. Refactoring Process

1. Audit — Map current structure, identify violations.
2. Test baseline — Ensure existing tests pass.
3. Establish glossary — Create docs/glossary.md.
4. Restructure directories — Move files, update imports, verify.
5. Rename for consistency — Eliminate banned patterns.
6. Extract shared code — Consolidate duplicates.
7. Refactor internals — Apply modularity patterns.
8. Add documentation — Fill in docstrings, ADRs.
9. Final validation — Full test suite, lint, type check, smoke test.

10. Deliverables Checklist

• All code under frontend/, backend/, or shared/
• docs/glossary.md exists
• Mirrored naming conventions applied
• Same domain concept uses same noun everywhere
• Zero banned naming patterns remain
• Zero duplicated logic
• No file >300 lines; no function >50 lines
• All async ops have error handling, logging, timeouts
• No silent catch blocks
• Every public API documented
• Section comments delineate logical groupings
• All dead code removed
• Full test suite passes
• App builds and runs in dev and production
• ADRs document significant decisions
• SOLID principles followed
• Types strict — no any, no untyped params