playbooks

home / skills / phrazzld / claude-config / refactor

refactor skill

/skills/refactor

This skill helps you streamline Python code by guiding clarity first and architecture second, reducing nesting and improving module depth.

npx playbooks add skill phrazzld/claude-config --skill refactor

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.9 KB
---
name: refactor
description: |
  REFACTOR
effort: high
---

---
description: Two-pass code refinement - clarity then architecture
---

# REFACTOR

> "Simplicity is the ultimate sophistication." — da Vinci

## Philosophy

Fight entropy. Leave the codebase better than you found it.

Every shortcut becomes someone else's burden. Every hack compounds into technical debt. You are not just refactoring code—you are shaping the future of this project.

## Role

You are the senior engineer. Codex does the refactoring; you review and ship.

**Codex writes first draft. You review and ship.**

## Objective

Post-implementation refinement: simplify code, improve module depth.

## Process

### Codex Does the Refactoring

Delegate the actual refactoring to Codex:

```bash
codex exec "REFACTOR: Simplify [file/module]. Focus on clarity, naming, reduced nesting. Follow CLAUDE.md standards. Run pnpm typecheck after." \
  --output-last-message /tmp/codex-refactor.md 2>/dev/null
```

Review what Codex produces. Fix issues if needed, then commit.

## Mission

Two-pass refinement:
1. **Clarity** — Simplify code without changing behavior
2. **Architecture** — Improve module depth and information hiding

## Phase 1: Simplification

Launch `code-simplifier:code-simplifier` agent.

Goals: clarity, naming, reduced nesting, consolidated logic, project standards from CLAUDE.md.

Commit: `refactor: simplify implementation`

## Phase 2: Deep Module Review

Launch `ousterhout` agent to review for Ousterhout's design principles.

Looking for:
- Shallow modules or pass-through methods
- Leaky abstractions exposing implementation details
- Change amplification risk (small change → many edits)
- Cognitive load issues (too much to hold in head)

If high-impact issues found:
1. Implement suggested refactorings
2. Commit: `refactor: improve module depth`

## Completion

Report what was simplified and any architectural improvements made.

Overview

This skill performs two-pass code refinement aimed at leaving the codebase cleaner and more maintainable. It combines an initial clarity pass to simplify implementation with a deeper architecture pass to improve module boundaries and information hiding. The output is a set of concrete edits and commit-ready changes with a short report of improvements.

How this skill works

The skill delegates the first pass to a code-simplifier agent that focuses on naming, reduced nesting, consolidation of logic, and adherence to project standards. A second pass uses an ousterhout-style reviewer to detect shallow modules, leaky abstractions, and change-amplifying structures, then applies higher-impact refactorings. Each pass produces commits with clear messages and a completion report describing what changed and why.

When to use it

  • After feature implementation when code feels complex or brittle
  • Before merging large PRs that touch many files
  • When technical debt accumulates in a module
  • When onboarding new team members to improve readability
  • When preparing code for a major architecture change

Best practices

  • Run the clarity pass first and keep behavior identical; add tests if coverage is low
  • Make small, focused commits with descriptive messages for each pass
  • Use the architecture pass only after tests and clarity are stable
  • Prioritize information hiding and reduce public surface area of modules
  • Review and run full test/type checks before shipping any refactor commit

Example use cases

  • Simplify a tangled utility module by consolidating repeated conditionals and renaming functions
  • Flatten nested control flow in a data-processing pipeline to improve readability
  • Refactor an API module to reduce surface area and prevent leaking internal types
  • Split a large file into coherent modules to reduce cognitive load and change amplification
  • Polish code before a release to reduce future maintenance cost

FAQ

Will the refactor change behavior?

The first pass explicitly avoids behavioral changes; the architecture pass may introduce changes but only after tests pass and with clear review.

What commit messages are used?

The skill creates focused commits: 'refactor: simplify implementation' for the clarity pass and 'refactor: improve module depth' for architecture changes.