Aos Refactor

/aos-refactor

Select files to refactor, then run /aos-refactor.

For targeted refactors: /aos-refactor complexity · /aos-refactor naming · /aos-refactor duplication · /aos-refactor debt · /aos-refactor size

Golden rule

Never refactor without a safety net. If the code has no tests, write characterisation tests first — then refactor. A characterisation test is a test that pins the current behaviour, not the desired behaviour.

What gets checked

Safety net

• The behaviour being changed has tests that describe outcomes, not implementation details
• CI runs automatically so regressions are caught immediately
• Tests do not assert internal state or method calls — they will survive a refactor

Naming

• Variable names reveal intent: user not u, expiresAt not ts
• Functions named for what they return or do: getUserByEmail, not process
• Booleans positive and assertive: isActive, hasPermission — not notInactive, permMissing
• No unexplained abbreviations (HTTP, URL, ID, OK are fine; usr, mgr, tmp are not)
• No misleading names — getUser that also deletes is a broken contract

Function complexity

• Functions have a single responsibility
• Cyclomatic complexity ≤ 10 per function (count if, else, for, while, case, &&, ||)
• Functions ≤ 30 lines — if scrolling is required to understand it, extract
• Nested if/else deeper than 3 levels flattened with guard clauses or extraction
• No functions that take a boolean flag to switch between two different behaviours — split into two

Duplication

• Duplicate logic extracted to a shared, named function
• Duplicate configuration extracted to a named constant
• Similar classes with minor differences unified with a parameter or strategy pattern

Abstraction level

• No premature abstraction — extracted only when used in ≥ 2 real places
• Abstractions named for what they do, not how: PaymentGateway, not IStripeWrapper
• No leaky abstractions — the caller does not need to know the implementation detail
• Code at one level of abstraction per function — no mixing of high-level intent and low-level detail

Technical debt classification

• Reckless / inadvertent — never acceptable. Fix now.
• Prudent / intentional — documented in a tracked issue with a timeline.
• Bit rot — outdated patterns. Fix opportunistically using the Boy Scout Rule.

Refactoring patterns

Output format

[WARN] Safety net — OrderService has no tests
Action: write characterisation tests before refactoring
  Suggested: it('should return the correct total for a standard order')
  Suggested: it('should apply promo code discount when code is valid')

[REFACTOR] Extract function — discount logic on lines 45–68 buried inside processOrder()
File: src/orders/order.service.ts:45
Pattern: Extract Function
Steps:
  1. Create: async applyPromoCode(subtotal: number, code: string): Promise<number>
  2. Move lines 45–68 into the new function
  3. Replace with: const finalPrice = await this.applyPromoCode(total, code)
  4. Run tests — no behaviour change should occur

[REFACTOR] Split function — processUser(user, isDryRun: boolean) does two different things
File: src/users/user.service.ts:88
Pattern: Split Function
Steps:
  1. Create validateUser(user) — the dry-run path
  2. Create persistUser(user) — the real path
  3. Call the right one at each call site
  4. Delete processUser

[REFACTOR] Naming — variable 'd' holds a discount percentage
File: src/orders/order.service.ts:47
Pattern: Rename
Fix: rename d → discountPercent

Full reference

See REFERENCE.md for before/after examples of every pattern.