When should I use this skill instead of just refactoring?

Use it when you face recurring bugs, fragile tests, or complex legacy code where the risk of regression is high and you need a prioritized plan.

What kind of 'traps' does it look for?

It identifies code smells, test-specific smells, and complex concurrency or Inter-Process Communication (IPC) traps that often lead to system instability.

How does it decide between refactoring and rewriting?

It uses specific rules of thumb, evaluating test availability, behavior stability, and previous refactor failures to provide a data-driven recommendation.

What is Refactoring Diagnosis?

It is a Claude Code skill that performs a deep analysis of code quality and design flaws, providing a structured report before any refactoring begins.

Does this skill automatically change my source code?

No, this skill is for diagnosis and planning. Once the report is generated, you should use skills like 'refactoring-design' and 'refactoring-safely' for implementation.

Refactoring Diagnosis

Name: Refactoring Diagnosis
Author: withzombies

bywithzombies

•

Developer Tools

Diagnoses code quality issues and architectural smells to provide a structured, evidence-based refactoring roadmap.

Refactoring Diagnosis is a specialized capability for Claude Code designed to systematically analyze codebases for technical debt, architectural smells, and concurrency traps. Instead of making haphazard changes, this skill requires concrete evidence and risk assessment to justify code modifications. It produces a standardized diagnosis report that covers scope, evidence-backed smells, risk matrices, and a definitive refactor vs. rewrite recommendation. This ensures that developers can prioritize high-impact targets, address fragile test suites, and minimize the risk of regressions in complex systems.

Key Features

0158 GitHub stars

02Evidence-backed code smell and architectural trap identification

03Dedicated analysis for concurrency, IPC, and test smells

04Comprehensive diagnosis report generation with prioritized targets

05Formal Refactor vs. Rewrite decision framework

06Standardized risk assessment matrix (Severity, Risk, and Blast Radius)

Use Cases

01Evaluating legacy modules to decide if they should be incrementally improved or completely replaced

02Identifying the root cause of recurring bugs such as deadlocks or fragile test suites

03Creating a defensible, evidence-based technical debt roadmap for project stakeholders

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add withzombies/hyperpowers refactoring-diagnosis

For use in Claude.ai and ChatGPT

Download Skill