refine-code

Refine Code

Improve existing code without changing what it does — only how it's organized, how readable it is, how deep its abstractions run, and how much of it needs to exist at all.

This skill operates in three modes, chosen automatically based on what the user asks for:

• Code mode — sharpen specific files or recent changes for clarity, consistency, and maintainability
• Architecture mode — find structural friction across modules and propose deepening opportunities
• Entropy mode — prove which surfaces have no load-bearing reason to exist, then delete them

If the user's request is scoped to specific files or recent changes, use Code mode. If they're asking about module boundaries, coupling, testability, or codebase-wide structure, use Architecture mode. If they're asking what can be removed — dead surface, duplicate state, unused config, abandoned features, over-engineering — use Entropy mode. If several apply (e.g., "clean up this area and think about whether the abstraction is right"), run them in order: Code, Architecture, Entropy.

If a Code mode analysis reveals that the real problem is structural (e.g., a function is messy because it's doing three unrelated things that belong in different modules), say so and offer to switch to Architecture mode for that piece.

---

Code Mode

Refinement means making existing code clearer — not adding new capabilities. Don't suggest new error handling, new features, debug commands, or logging unless the user asked for them. The goal is to reduce what a reader must hold in their head to understand the code.

The core question

For every function, type, variable, or abstraction in scope, ask: "Does this earn its complexity?"

• The deletion test — imagine deleting this abstraction. If the callers get simpler, it was a pass-through adding indirection without value. If complexity reappears across N call sites, it was earning its keep.
• The reader test — if a new team member read this code top-to-bottom, where would they get confused? Where would they need to jump to another file to understand what's happening? Those are your improvement targets.
• The type test — are types telling the truth? A Record<string, unknown> that's always {name: string, age: number} forces every consumer to narrow manually. Types that lie create casts; casts hide bugs.