refactor_skill

Overview

This skill improves code quality while preserving behavior in an opinionated TypeScript monorepo. It targets tech debt, pattern migrations, and structural improvements for an Express 5 server and CDKTF infrastructure while treating the test suite as the behavioral contract. All changes must keep the test suite green and maintain existing public APIs.

How this skill works

Refactoring begins by verifying sufficient test coverage for the target area (>80%) and recording a test baseline. Work proceeds with small, atomic changes: run tests and type/lint checks after every change, commit only when everything is green, and document each change with rationale and traceability. If coverage is insufficient or tests fail, refactor is blocked and the appropriate follow-up (add tests or revert) is required.

When to use it

• Reduce accumulated technical debt in critical services
• Migrate code to newer patterns consistently across the repo
• Prepare code for dependency or major version upgrades
• Optimize internal structure or performance without adding features
• Clean up after merges or spec implementations to improve maintainability

Best practices

• Require >80% coverage on refactor targets; add tests first if not met
• Establish and record a baseline (tests, type errors, lint, coverage) before changes
• Make incremental, atomic, reversible commits and run full test suite after each change
• Preserve public APIs and do not modify production behavior — tests are the contract
• Document rationale, files changed, commits, and related spec group IDs for traceability

Example use cases

• Extract long function logic into smaller methods to reduce cyclomatic complexity and improve readability
• Replace complex conditional logic with polymorphic strategies for pricing or authorization
• Introduce dependency injection to make services testable without real resources
• Consolidate error handling patterns and remove dead code while ensuring tests remain unchanged
• Block refactor of legacy module until coverage improved, then add targeted tests and proceed