refactor

name	refactor
description	Reorganize and document code with safe file moves and continuous validation. Use when refactoring file structure, reorganizing code, or documenting a system.
disable-model-invocation	true

Refactor Code

Reorganize and document code systems with safe file moves and continuous validation.

Workflow Overview

Phase	Steps
1. Understand	Analyze system, draft README with Mermaid diagrams, get user confirmation
2. Plan & Execute	Propose file moves, user performs moves via Cursor, wait for confirmation
3. Validate	Check files moved, imports updated, fix issues, run typecheck and tests
4. Finalize	Update docs, clean up, summarize quality concerns

See WORKFLOW.md for detailed step-by-step instructions.

Key Principles

• Tests move with implementation: When moving foo.ts, also move __tests__/foo.spec.ts
• Group by feature/domain: Not by type (avoid separate components/, services/, utils/ folders)
• Co-locate tests: Tests live in __tests__/ folders near the code they test
• Clean public APIs: Folder should have an entry file with the same name (e.g., memberSignals/memberSignals.ts)
• Editor-native moves: Rely on Cursor's TypeScript language server to update imports

Nx Considerations

This repo uses Nx—respect project boundaries:

• Don't move files across Nx project boundaries without understanding implications
• Cross-project imports must use proper package paths, not relative imports
• If moving files between projects, consider if the code should be in a shared package

Prerequisites

• typescript.updateImportsOnFileMove.enabled set to "always" or "prompt" in Cursor settings
• For large refactors (>20 files), break into smaller batches