learning_ai_common_plat/AI.dev/PROMPTS/refactor-with-tests.md

name	description	argument-hint	agent
refactor-with-tests	Safely refactor code with test-first methodology — capture behavior, refactor, verify nothing broke.	Target module/file and refactor goal, e.g. "backend/src/modules/auth — extract token service", "simplify scheduler engine in FlowMonk"	agent

Refactor with Tests Prompt

Safely refactor code by first capturing existing behavior in tests, then restructuring while keeping all tests green.

Context — ByteLyst Conventions

• Test runner: Vitest (TypeScript), pytest (Python)
• Test location: Same module directory or __tests__/
• Never modify tests to make them pass — fix the code
• Commit format: refactor(scope): description

Refactor Protocol

Step 1: Understand Current Behavior

Before touching any code:

1. Read the code — understand what it does, not just the structure
2. Read existing tests — understand what's already covered
3. Run existing tests — confirm they pass:

   pnpm test
   pnpm typecheck
   

4. Identify the API surface — what do consumers depend on?
   • Exported functions/types
   • REST endpoint contracts
   • Side effects (database writes, events emitted)

Step 2: Add Missing Tests (Before Refactoring)

If test coverage is insufficient, add tests for current behavior FIRST:

// Capture existing behavior before refactoring
describe('<Module> — pre-refactor behavior capture', () => {
  it('should return X when given Y', () => {
    // Test current behavior, even if the implementation is ugly
  });

  it('should throw NotFoundError for missing items', () => {
    // Edge cases that must be preserved
  });

  it('should include productId in all created documents', () => {
    // Ecosystem invariants
  });
});

Commit these tests separately:

git add .
git commit -m "test(<scope>): capture pre-refactor behavior (N tests)"

Step 3: Plan the Refactor

Document what will change and what must stay the same:

• Changing: Internal structure, file organization, naming
• Preserving: API surface, behavior, test contracts
• New patterns: What you're moving toward (e.g., extract service class, split module)

Step 4: Refactor in Small Steps

For each step:

1. Make ONE structural change
2. Run tests: pnpm test
3. Run typecheck: pnpm typecheck
4. If tests pass → commit
5. If tests fail → undo and retry with smaller step

# After each small refactor step
pnpm test && pnpm typecheck && \
git add . && git commit -m "refactor(<scope>): <what changed>"

Step 5: Verify Completeness

After all refactoring:

# Full validation
pnpm build && pnpm typecheck && pnpm test

# Check no exports were broken
# If this is a @bytelyst/* package:
cd learning_ai_common_plat && pnpm build && pnpm test

Step 6: Update Documentation

If the refactor changed:

• File locations → update AGENTS.md repo layout
• API surface → update README.md or API docs
• Module structure → update any roadmap or architecture docs

git add .
git commit -m "docs(<scope>): update docs after <module> refactor"
git push

Common Refactor Patterns

Extract Service Class

Before: routes.ts has business logic mixed with HTTP handling
After:  routes.ts → service.ts → repository.ts (routes are thin)

Split Module

Before: modules/schedule/ has 500-line routes.ts
After:  modules/schedule/ + modules/schedule-entries/ (each focused)

Extract Shared Package

Before: Two products have duplicate utility code
After:  New @bytelyst/* package consumed by both

Consolidate Re-exports

Before: Each file imports from @bytelyst/* directly
After:  src/lib/ re-exports, internal files import from src/lib/

Guardrails

• Test first, refactor second. Never refactor without test coverage.
• Small commits. Each commit should be revertible without losing other changes.
• No behavior changes. Refactoring changes structure, not behavior. If you're fixing bugs, that's a separate commit.
• No export changes without updating all consumers.
• Run the full suite after every commit, not just the changed module's tests.