agentleFS
Sign inStart free
harshsinghmpharshsinghmp/muse-skills/skills/design-interface/refactor/SKILL.md

refactor

Skill1 starsChanged 18 days agoMITView on GitHub

Universal refactoring engine: systematically evaluate, modernize, and refactor user interfaces, application code, software architecture, runtime performance, database schemas, and multi-page consistency — routed through twenty execution modes. Use when asked to refactor UI components or layouts, clean up code smells and reduce cyclomatic complexity, decouple architectural modules and boundaries, optimize runtime performance and bundle sizes, refactor database schemas with zero downtime, sweep consistency across an entire app, or run a pre-release polish pass. Not for novel feature creation from scratch (new-project/webdev) or full security vulnerability exploitation (muse-security).

We split this skill into the rules it gives an agent

7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 160 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every invocation resolves to exactly one mode.

    line 42
  2. Very specific:

    Only the resolved mode's reference is loaded — the rest stay on disk, saving tokens on every run.

    line 55
  3. Very specific:

    When executing the ui or sweep mode, adhere strictly to the 10 atomic heuristics:

    line 91
  4. Very specific:

    Ensure existing tests pass (bun test).

    line 123
  5. Distinctive:

    Never combine refactoring with behavioral feature additions.

    line 127
  6. Distinctive:

    Pixel drift in tokens mode: When centralizing design tokens, pixel values must remain visually identical.

    line 143
  7. Distinctive:

    Run before reporting completion:

    line 149

“Common” is measured: kept by at least 6 in 10 of the 160 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

🪄 refactor — Universal Refactoring Engine

One unified department for systematic software refactoring across all layers of the stack. Transforms legacy, messy, or inconsistent code and interfaces into clean, maintainable, and high-performance production assets without altering external behavior.

Modes

Every invocation resolves to exactly one mode. Match the request, then load only the matched reference:

ModeTrigger phrasesBehaviorReference
ui"refactor this UI", "make this look professional", "improve design", "fix contrast", "refactoring-ui", "ui polish"Visual and interface refactoring: 10 Refactoring UI atomic heuristics, spacing ladders, modern container queries, typography hierarchy, and WCAG 2.2 contrast parityreferences/ui.md
code"refactor this function", "clean up this code", "reduce complexity", "make this DRY", "extract method"Code-level refactoring: cyclomatic complexity reduction, SOLID principles, eliminating dead code, function extraction, and TypeScript strict typingreferences/code.md
architecture"refactor codebase structure", "decouple modules", "clean architecture", "break circular dependency", "modularize"Structural refactoring: modular boundaries, separating business logic from UI/framework, domain-driven organization, and dependency inversionreferences/architecture.md
perf"optimize performance", "refactor for speed", "reduce bundle size", "fix memory leak", "perf refactor"Runtime & build refactoring: algorithmic efficiency ($O(n^2) \rightarrow O(n)$), tree-shaking, component memoization, dynamic imports, and Core Web Vitals optimizationreferences/perf.md
database"refactor schema", "zero-downtime migration", "normalize tables", "fix N+1 queries", "db refactor"Data layer refactoring: non-breaking column migrations, query optimization, indexing strategy, and ORM query batchingreferences/database.md
sweep"sweep consistency", "unify all pages", "standardize components across app", "design consistency"Multi-page consistency refactoring (strictly on-demand, never runs automatically): sweeping duplicate components into single sources of truth, aligning button styles, cards, and patterns across the appreferences/sweep.md
polish"final polish before release", "clean up deprecated code", "pre-merge polish", "ship readiness"Pre-launch refactoring pass: dead-letter triage, deprecated API cleanup, lint/formatting sweep, and edge-case hardeningreferences/polish.md
audit"pre-refactor audit", "audit codebase health", "refactor scope audit"Measured pain, test-covered seams, blast radius, surgical-diff and rollback discipline — before code moves.references/audit.md

Only the resolved mode's reference is loaded — the rest stay on disk, saving tokens on every run. Note: sweep mode carries codebase-wide blast radius and is strictly on-demand; automated agents must never run it automatically without explicit user direction.

Support references (load on topic)

Loadable by topic; also routable as /refactor-<file> commands (not separate routed modes):

  • 06-visual-clutter.md
  • 11-five-state-anti-slop.md
  • 08-shadows-elevation.md
  • 03-color-palette.md
  • 04-spacing-layout.md
  • 05-button-hierarchy.md
  • modern-techniques.md
  • 02-typography-scale.md
  • 09-contrast-accessibility.md
  • 07-empty-states.md
  • 01-visual-hierarchy.md
  • 10-grouping-alignment.md

When to Use

  • Refactoring a UI component, screen, or dashboard using the 10 atomic Refactoring UI heuristics.
  • Simplifying complex functions, reducing cyclomatic complexity, or cleaning up messy procedural code.
  • Decoupling monolithic modules, breaking circular dependencies, or enforcing clean architecture boundaries.
  • Diagnosing and refactoring performance bottlenecks, memory leaks, and oversized bundles.
  • Migrating database tables or columns with zero production downtime using the expand/contract pattern.
  • Sweeping duplicate UI components or hardcoded tokens across an entire multi-page application.
  • Conducting a final pre-merge or pre-launch technical polish pass.

Quick Reference & Atomic UI Heuristics

When executing the ui or sweep mode, adhere strictly to the 10 atomic heuristics:

#Heuristic DomainCore Problem SolvedPrimary Technique
01Visual HierarchyEverything competing for attentionPrimary focal point + aggressive de-emphasis of secondary elements
02Typography ScaleInconsistent, uncalibrated font sizesModular type scale (12, 14, 16, 20, 24, 32, 48px) with optical weights
03Color PaletteSaturated, garish, or arbitrary colors9-step neutrals + primary brand hue + functional status semantics
04Spacing GridArbitrary margins and cramped layoutsStrict 4px/8px ramp; generous whitespace before adding borders
05Button HierarchyCompeting CTAs of equal visual weightSolid primary, neutral secondary, ghost/link tertiary
06Visual ClutterBorder soup, redundant divider linesSurface contrast, directional spacing, removing self-evident labels
07Empty StatesBlank screens that confuse usersAction-oriented guidance, illustrative placeholder, instant CTA
08Shadows & DepthFlat cards, muddy drop-shadowsLayered diffuse shadows; shadows = depth, borders = structure
09Color ContrastLow-contrast text failing accessibilityWCAG 2.2 AA ($\ge 4.5:1$ text, $\ge 3:1$ UI/large)
10Grouping & ProximityRelated items drifting apartInter-group gap $\ge 2\times$ intra-group; space before surfaces before lines
11Anti-Slop 5-State GateHappy-path only components break in prodExplicit Empty, Loading, Error, Success, and Overflow states

Automated Tooling

Ships zero-dependency Bun scripts under scripts/:

  • Anti-Pattern Scanner: bun refactor/scripts/audit-ui.ts <file_or_dir>
  • WCAG Contrast Checker: bun refactor/scripts/check-contrast.ts <file_or_dir>

Procedure

  1. Intake & Scope:
    • Identify the exact layer requiring refactoring (UI, code, architecture, performance, database, or cross-page sweep).
    • Resolve to exactly one execution mode.
  2. Safety Baseline:
    • Ensure existing tests pass (bun test). Never refactor on broken tests.
    • For database refactoring, confirm a staging replica and rollback path exist.
  3. Execute Atomic Transformations:
    • Make small, incremental changes. Rerun tests after each atomic step.
    • Never combine refactoring with behavioral feature additions.
  4. Verification:
    • For ui: check 5-state gate and run check-contrast.ts.
    • For code: check complexity reduction and clean linting (bun run lint).
    • For architecture: verify dependency acyclicity.
    • For perf: confirm benchmark delta.
    • For database: verify zero locks held >100ms.
    • For sweep & polish: verify zero regressions and type-check passing.

Pitfalls

  • Refactoring without tests: Blindly refactoring complex logic without automated regression tests causes subtle bugs. Write a characterization test first if tests are missing.
  • Scope creep: Adding "just one quick feature" while refactoring breaks the refactoring discipline.
  • Over-abstraction: Introducing 5 layers of design patterns for a simple 20-line utility function. Keep it lean and pragmatic.
  • Pixel drift in tokens mode: When centralizing design tokens, pixel values must remain visually identical.

Verification

Run before reporting completion:

  • Target files verified and exist.
  • No secrets in output artifacts.
  • WCAG 2.2 AA contrast verified for any color or typography change.
  • bun test passes with zero behavioral regressions.
  • bun run lint and bun run type-check pass cleanly.
  • Release verdict emitted (SHIP READY or BLOCK).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free