Agent Skills: Refactor Code

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