Making The Business Case For Code Health

Making the Business Case for Code Health

Overview

Use this skill when the user needs quantified justification for refactoring work. The purpose is to convert current Code Health into a clear argument about delivery speed and defect reduction.

When to Use

• A user asks for ROI, business value, or management justification.
• The workflow needs evidence to prioritize refactoring work.
• An engineering team needs a short case for why improving a file is worth the effort.

Do not use this skill to explain Code Health fundamentals. Use explaining-code-health for that.

Quick Reference

• code_health_refactoring_business_case: Generate modeled outcomes for one file.
• code_health_score: Optional supporting baseline when the user wants the current score called out separately.

Implementation

1. Run code_health_refactoring_business_case for the target file.
2. Present the recommended target scenario.
3. Summarize the optimistic and pessimistic outcomes as a bounded range, not a promise.
4. Translate the output into a short investment rationale tied to delivery speed and defect reduction.
5. If needed, pair the result with code_health_score or code_health_review to show why the file is a refactoring candidate.

Common Mistakes

• Presenting modeled outcomes as guarantees.
• Using this skill for project-wide ranking without first narrowing candidate files.
• Explaining raw JSON instead of converting it into a short business argument.
• Forgetting that the tool is file-scoped.