guiding-refactoring-with-code-health git:20261017.0e2246aA

Immutable. This exact content never changes and is served at /api/v1/blob/c5afcfe17f7d361e.

---
name: guiding-refactoring-with-code-health
description: Improve unhealthy code incrementally using measured Code Health feedback. Use when planning structural refactoring steps for complexity, size, cohesion or nesting and comparing each step with a baseline. Requires an opted-in cratis/codescene profile and available CodeScene MCP tools; otherwise skip. Do not use for a pre-commit change gate (use safeguarding-ai-generated-code) or portfolio debt ranking (use prioritizing-technical-debt).
license: Apache-2.0
---

<!-- Modified by Cratis from CodeScene AB's original (Apache-2.0): added profile guard, policy note, license field and this notice. Upstream: https://github.com/codescene-oss/codescene-mcp-server (skills/guiding-refactoring-with-code-health/SKILL.md; see NOTICE) -->

# Guiding Refactoring With Code Health

Use only in repositories that opted into `cratis/codescene` and have CodeScene MCP tools available; otherwise skip without blocking and say so. The Cratis policy in `.cratis/ai/rules/codescene.md` overrides this skill where they differ.

## Overview

Use Code Health as the control signal for refactoring. The agent should first understand why a file is hard to work with, establish a measurable baseline, then improve it in small structural steps and verify that each step helped. The goal is not just cleaner code, but code that is easier for both humans and agents to understand and modify safely.

## When to Use

- A file is hard to read, risky to change, or repeatedly attracts defects.
- The user asks for refactoring help and wants an objective way to measure progress.
- A safeguard or review points to complexity, size, low cohesion, or deep nesting.

Do not use this skill when the task is to rank project-wide priorities. Use `prioritizing-technical-debt` for that.

## Quick Reference

- `code_health_review`: Detailed maintainability findings for a file.
- `code_health_score`: Numeric baseline and trend check across refactoring iterations.

## Implementation

1. Run `code_health_review` on the target file.
2. Record the current `code_health_score` so the refactoring starts from a measurable baseline.
3. Identify the highest-leverage structural problems, such as excessive responsibilities, deep nesting, low cohesion, or hard-to-follow control flow.
4. Propose 3 to 5 small structural refactor steps, not a single rewrite.
5. After each meaningful step, re-run `code_health_review` to see whether the targeted structural problems were reduced.
6. Use `code_health_score` as the compact checkpoint to confirm directional improvement across iterations.
7. Stop only when the targeted structural issues are substantially reduced and the score has measurably improved, or when the user explicitly accepts a partial uplift.

## Common Mistakes

- Refactoring without a baseline review.
- Refactoring without recording the initial score.
- Making a large rewrite that hides whether things improved.
- Counting cosmetic cleanup as meaningful progress when the structural problems remain.
- Using score checks alone without re-running the detailed review.
- Forgetting to re-measure after each meaningful step.