---

name: noodlbox-refactoring description: >- Refactor code, rename symbols, extract modules, split services. Plan safe refactoring by mapping dependencies, find what depends on code before moving or deprecating APIs. NOT for quick change impact (use change-planning) or debugging failures (use debugging). metadata: author: noodlbox version: "{{VERSION}}"

Refactoring

Plan and execute safe refactoring by understanding dependencies and impact.

Quick Start

Copy1. noodlbox_query_with_context  → Find the code to refactor
2. noodlbox_raw_cypher_query   → Map all dependencies
3. noodlbox_detect_impact      → Preview blast radius

Tool Reference

noodlbox_query_with_context

Find code related to the refactoring target.

Copynoodlbox_query_with_context(
  repository: "current",
  q: "payment processing service",
  task_context: "planning to split PaymentService",
  current_goal: "find all payment-related code",
  search_intention: "map dependencies before refactor",
  limit: 10
)

noodlbox_raw_cypher_query

Map dependencies for safe refactoring.

Copy-- Find all callers (what depends on this?)
MATCH (caller)-[:CALLS]->(target:CODE_SYMBOL {name: "PaymentService"})
RETURN caller.name, caller.file_path, caller.community_id
ORDER BY caller.community_id

-- Find all callees (what does this depend on?)
MATCH (source:CODE_SYMBOL {name: "PaymentService"})-[:CALLS]->(callee)
RETURN callee.name, callee.file_path
ORDER BY callee.name

-- Find symbols that would need updating after rename
MATCH (s:CODE_SYMBOL)
WHERE s.name CONTAINS "Payment"
RETURN s.name, s.kind, s.file_path
ORDER BY s.file_path

For more Cypher patterns, see shared/cypher-patterns.md.

noodlbox_detect_impact

Preview what would be affected by the refactor.

Copynoodlbox_detect_impact(
  repository: "current",
  change_scope: "all",
  include_content: false,
  max_processes: 20
)

Workflow Checklist

Rename a Symbol

CopyRename Refactoring:
- [ ] Find all references to the symbol
- [ ] Check for string literals using the name
- [ ] Identify test files that reference it
- [ ] Check for external API surface changes
- [ ] Plan rename order (interfaces → implementations → usages)
- [ ] Verify no dynamic references (reflection, string keys)

Extract Module

CopyExtract Module Refactoring:
- [ ] Identify code to extract
- [ ] Map all internal dependencies
- [ ] Map all external callers
- [ ] Define new module interface
- [ ] Plan extraction order
- [ ] Update imports across codebase

Split Service

CopySplit Service Refactoring:
- [ ] Map current service responsibilities
- [ ] Group related methods by domain
- [ ] Identify shared state/dependencies
- [ ] Define new service boundaries
- [ ] Plan migration path
- [ ] Create facade for backwards compatibility (if needed)

Example: Rename getUserById to findUserById

Task: "I want to rename getUserById to findUserById. What needs to change?"

CopyStep 1: Find all references
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (caller)-[:CALLS]->(fn:CODE_SYMBOL {name: 'getUserById'}) RETURN caller.name, caller.file_path"
)

→ Results:
  AuthService.validateToken (src/auth/service.ts:45)
  ProfileController.getProfile (src/profile/controller.ts:23)
  OrderService.getOrderOwner (src/orders/service.ts:78)
  UserController.show (src/users/controller.ts:34)

Step 2: Find the definition
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (fn:CODE_SYMBOL {name: 'getUserById'}) RETURN fn.file_path, fn.kind"
)

→ Results:
  UserService (src/users/service.ts) - Method
  UserRepository (src/users/repository.ts) - Method

Step 3: Check for tests
noodlbox_query_with_context(
  repository: "current",
  q: "getUserById test spec",
  task_context: "finding tests for getUserById",
  limit: 5
)

→ Results:
  user.service.spec.ts
  user.repository.spec.ts

Step 4: Create rename plan
Files to update:
1. src/users/service.ts (definition)
2. src/users/repository.ts (definition)
3. src/auth/service.ts (caller)
4. src/profile/controller.ts (caller)
5. src/orders/service.ts (caller)
6. src/users/controller.ts (caller)
7. src/users/service.spec.ts (test)
8. src/users/repository.spec.ts (test)

Checklist for this example:

Copy- [x] Find all references (4 callers)
- [x] Find definitions (2 files)
- [x] Check for tests (2 test files)
- [ ] Check for string literals (grep for "getUserById")
- [ ] Check external API (not exposed)
- [x] Plan rename order

Example: Split PaymentService

Task: "Can I split PaymentService into separate services? Show dependencies."

CopyStep 1: Understand current structure
noodlbox_query_with_context(
  repository: "current",
  q: "PaymentService methods responsibilities",
  task_context: "planning to split payment service",
  current_goal: "map all payment functionality",
  limit: 10
)

→ Results:
  PaymentService methods:
  ├── processPayment
  ├── refundPayment
  ├── validateCard
  ├── calculateFees
  ├── sendReceipt
  └── generateReport

Step 2: Map internal dependencies
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (m)-[:CALLS]->(n) WHERE m.file_path CONTAINS 'payment' AND n.file_path CONTAINS 'payment' RETURN m.name, n.name"
)

→ Results:
  processPayment → validateCard
  processPayment → calculateFees
  refundPayment → calculateFees
  processPayment → sendReceipt

Step 3: Map external callers
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (caller)-[:CALLS]->(fn:CODE_SYMBOL) WHERE fn.file_path CONTAINS 'payment/service' AND NOT caller.file_path CONTAINS 'payment' RETURN DISTINCT caller.name, fn.name, caller.file_path"
)

→ Results:
  CheckoutHandler → processPayment
  WebhookHandler → processPayment
  AdminController → refundPayment
  ReportJob → generateReport

Step 4: Suggest split
Based on dependencies:
- PaymentProcessingService: processPayment, validateCard, calculateFees
- PaymentNotificationService: sendReceipt
- PaymentReportService: generateReport
- PaymentRefundService: refundPayment, calculateFees (shared)

Refactoring Patterns

Risk Assessment

When to Use Something Else