Step 1 · Assess

Goal

Decide what to refactor, why it matters, and whether it is safe to do so now. Refactoring without tests is rewriting. Refactoring without a clear goal is churn.

Instructions

You are in workflow step 1 of the refactor-cycle. Code has been identified as a candidate for improvement. Your job is to assess it thoroughly before touching anything.

Tasks to Perform

1. Establish a Test Safety Net

Before evaluating what to refactor, check if tests exist:

# Find existing tests for the target module
find . -type f | grep -iE "\.(test|spec)\." | grep -v node_modules | grep -v vendor | grep "[module-name]"

# Run them
[test runner command] [path/to/tests for this module]

If tests do not exist: Write characterisation tests first. They don't test the correct behaviour — they capture the current behaviour. Their purpose is to alert you if your refactoring changes the observable output.

# Run the full suite to confirm baseline health
[full test runner command]
# All tests must pass before any refactoring begins

2. Identify Code Quality Issues

Read the target code completely. Look for these maintainability problems:

Size problems:

• [ ] Functions longer than 20-30 lines (hard to understand in one read)
• [ ] Classes longer than 300 lines (likely doing too many things)
• [ ] Files longer than 500 lines (difficult to navigate)

Complexity problems:

• [ ] Deeply nested conditionals (3+ levels of if/else)
• [ ] Boolean parameter flags (doTheThing(true, false, true) — what does this mean?)
• [ ] Switch statements on a type/kind field (sign of missing polymorphism)
• [ ] Long if-else chains that keep growing
• [ ] Functions with 5+ parameters

Duplication:

• [ ] Identical or near-identical code blocks in multiple places
• [ ] Same business rule implemented differently in two locations
• [ ] Copy-pasted test data setup in every test instead of a factory

Bad names:

• [ ] Variables named data, result, temp, thing
• [ ] Functions named doStuff(), process(), handle()
• [ ] Abbreviations that require decoding (usr, cfg, btn)
• [ ] Names that describe implementation rather than intent

Wrong abstraction level:

• [ ] Business logic mixed with database queries
• [ ] HTTP concepts leaking into business logic
• [ ] UI rendering logic in a service class

3. Score the Target Code

Rate each dimension:

4. Risk Assessment

Before deciding to refactor:

Overall risk: Low / Medium / High

5. Write the Refactoring Plan

Create docs/refactoring/REFACTOR-MODULE-NAME.md:

# Refactor: [Module Name]

## Problem
[Why does this code need improvement?]

## Goal
[What will it look like after the refactoring?]

## Scope
[Exactly what files/classes/functions are in scope]

## Out of Scope
[What will NOT change during this refactoring]

## Test Safety Net
[What tests exist / what characterisation tests were added]

## Steps
1. [First atomic refactoring step]
2. [Second step]
3. ...

## Risk
[Low / Medium / High — justification]

6. Populate TODO.md

Always include a source reference on every task. Status rules: [ ] = not started · [~] = in progress (one at a time) · [x] = done (prefix the date).

## Todo
- [ ] refactor: [first atomic step — e.g., extract validateEmail() from UserService] _(ref: workflows/refactor-cycle/01-assess.md)_
- [ ] refactor: [second step] _(ref: workflows/refactor-cycle/01-assess.md)_
- [ ] test: [any missing tests to add before refactoring begins] _(ref: workflows/refactor-cycle/01-assess.md)_

Go / No-Go Decision

Any ❌ is a NO-GO. Address it before proceeding.

Exit Criteria

This step is complete when:

• [ ] Test safety net is confirmed (tests exist and are passing)
• [ ] Code quality issues are documented
• [ ] Refactoring plan is written
• [ ] Risk is assessed and acceptable
• [ ] TODO.md has the step-by-step refactoring tasks
• [ ] Ready to proceed to Step 2 (Plan)