---
name: improve-code-health
description: |
  Improve code health through architecture review, complexity reduction, safe refactoring, dependency cleanup, and behavior-preserving validation. Use when the user asks for an architecture sweep, codebase health review, simplification, refactor safely, reduce complexity, or improve maintainability.
---

# Improve Code Health

Use this skill to improve maintainability without changing intended behavior.

## Paths

- **architecture sweep**: map structure, complexity, boundaries, and high-leverage simplifications.
- **safe refactor**: execute scoped refactors with continuous validation.

Read `references/workflow.md` before starting.

## Documentation Output

When writing plans, reports, PRDs, briefs, findings, story tracking, scratch notes, or other generated documentation, write them under the repository-root `docs/` directory, preferably `docs/improve-code-health/...` or the specific `docs/` path named in the workflow. Do not use `.agents/`, `.pi/`, `.codex/`, `.claude/`, or other agent-specific directories for generated documentation.