Skip to content
Skills Library
Programming · Building & coding

refactor

/refactor

Change structure while preserving external behavior — characterize the contract, delete unnecessary code, transform mechanically and migrate consumers. Use for /haechi:refactor or an authorized behavior-preserving change within other work.

Repository
haechi ↗
Licence
MIT
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Change structure while preserving external behavior — characterize the contract, delete unnecessary code, transform mechanically and migrate consumers. Use for /haechi:refactor or an authorized behavior-preserving change within other work.

Original author description

Change structure while preserving external behavior — characterize the contract, delete unnecessary code, transform mechanically and migrate consumers. Use for /haechi:refactor or an authorized behavior-preserving change within other work.

How it works

  1. Methods
  2. Delegation contracts
Original SKILL.md headings · 124 lines, 593 words
SKILL.md preview
---
name: refactor
description: Change structure while preserving external behavior — characterize the contract, delete unnecessary code, transform mechanically and migrate consumers. Use for /haechi:refactor or an authorized behavior-preserving change within other work.
---

# Restructure without changing behavior

Apply the [common work contract](../../principles/work-contract.md) within the authorized scope. It owns required implementation, verification, review and completion obligations; this skill supplies methods. Use /haechi:delegate for a bounded worker task when independent execution helps. Existing step names below are compatible delegation entry points, not an exclusive workflow state.

## Methods

1. **Name the structural problem and preserved contract.** Define the intended end state in checkable terms, such as no remaining imports of a retired internal module. Use /haechi:spec when the boundaries need synthesis; settled requirements need no new approval.
2. **Characterize current behavior.** Reuse tests covering observable results or add missing characterization before changing structure. Where affected, cover errors and timing, input mutation, side-effect order and partial writes. An old/new equivalence check on the same inputs can be useful. Use /haechi:mutation-check when a concrete concern suggests the characterization could miss a regression.
3. **Delete before adding structure.** Remove dead code, unused exports and unnecessary checks when in scope. Keep independently verifiable cleanup and mechanical transformations in coherent units under the repo's commit rules.
4. **Transform mechanically.** Use a type-aware rename or codemod for symbol moves, rather than an indiscriminate text replacement. Move files with the repository's appropriate tools. Do not combine an intentional behavior change with a claimed behavior-preserving transformation.
5. **Migrate consumers and retire obsolete paths.** Remove old internal paths once their in-scope consumers are migrated. Do not invent a compatibility layer merely to avoid completing the migration; retain public compatibility explicitly required by the task. Resolve consumers outside the authorized scope before deleting their dependency.
6. **Investigate a broken check.** If it asserts internals, replace it with a behavior assertion and explain why. If observable behavior changed unintentionally, restore it rather than changing the expected result. A necessary intentional behavior change follows the user's authorization and common obligations; choosing another method is not a new approval by itself.

Inspect remaining consumers, unused exports and stale documentation. The common contract governs preservation evidence and any affected rendered behavior, including use of /haechi:screen-parity when an independent comparison adds evidence.

## Delegation contracts

These compatible entries identify delegated methods, not an exclusive workflow or a mandatory agent sequence. Packet assembly also supplies the canonical common work contract. The main session fills the named context fields and task-specific acceptance criteria; detailed procedures and principle bodies stay in their referenced files. `read-only` means repository files remain unchanged; authorized temporary or report outputs must be named separately in `artifactPaths`.

```haechi-handoffs
{
  "implement": {
    "skills": [
      "implement-work"
    ],
    "principles": [
      "dry",
      "yagni",
      "kiss",
      "boundary-validation",
      "root-cause",
      "failing-test-first",
      "behavior-tests"
    ],
    "checks": [],
    "writeScope": "scoped",
    "contextRequired": [
      "repository",
      "requirements",
      "pinningEvidence",
      "ownership"
    ],
    "completion": [
      "Report the assigned implement work, its observed results and any remaining scope limitations."
    ]
  },
  "attack": {
    "skills": [
      "attack-tests",
      "sibling-path-map",
      "mutation-check"
    ],
    "principles": [
      "sibling-paths",
      "behavior-tests"
    ],
    "checks": [],
    "writeScope": "scoped",
    "contextRequired": [
      "repository",
      "requirements",
      "changedFiles",
      "ownership"
    ],
    "completion": [
      "Demonstrate that tests detect the targeted defects without weakening expected behavior."
    ]
  },
  "review": {
    "skills": [
      "verify-work",
      "review-diff",
      "impact-map"
    ],
    "principles": [
      "evidence-levels",
      "behavior-tests"
    ],
    "checks": [
      "agent-defects",
      "sibling-paths",
      "dry",
      "yagni",
      "kiss"
    ],
    "writeScope": "read-only",
    "contextRequired": [
      "repository",
      "requirements",
      "base",
      "changedFiles",
      "priorEvidence"
    ],
    "completion": [
      "Report concrete defects with expected and observed behavior and affected consumers.",
      "Distinguish passing checks, failures, missing proof and unresolved expectations."
    ]
  },
  "parity": {
    "skills": [
      "screen-parity"
    ],
    "principles": [
      "real-artifact"
    ],
    "checks": [],
    "writeScope": "read-only",
    "contextRequired": [
      "repository",
      "beforeUrl",
      "afterUrl",
      "states",
      "intendedDifferences",
      "artifactLocation",
      "loginContext"
    ],
    "completion": [
      "Return PASS or FAIL against real rendered comparisons and the noise baseline, or BLOCKED."
    ]
  }
}
```

Versions

RepositoryScoreLicence
This page · jisuzzzz/haechi100MIT
froglet-studio/cosmic-shore100MIT
mgiovani/cc-arsenal100MIT
jongio/skills100MIT
boshu2/agentops100Apache-2.0
y-miyazaki/terraform-aws-base100Apache-2.0
mickeyyaya/evolve-loop100Apache-2.0
j0hanz/j0hanz-marketplace100MIT
kriscard/kriscard-claude-plugins100MIT

Database snapshot: 13.11.2026 · package version 7609df685e18 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100refactor-safely
    Use when code is hard to change, has accumulated cruft, or before a feature that the current structure resists — improve structure in small, behavior-preserving steps under green tests; never mix a refactor with a behavior change.
  • 100workflow-refactor
    Scoped, behavior-preserving refactor: map dependencies, change structure, run affected tests. Use when "refactor this", "reduce duplication", or "improve readability". Dead code → plan-dead-code. Repo-wide smells → audit-code-quality.
  • 100dev-refactor
    Use when changing structure without changing behavior: restructure, extract, rename, dedupe or split code.
  • 100class-refactoring
    Use when refactor PHP classes to improve structure, readability, and maintainability while preserving behavior
  • 90trove-refactor
    Behavior-preserving change to structure: rename, extract, inline, dedupe, move, or migrate an internal API. Pin behavior first, migrate callers and delete the legacy API in one wave, prove behavior unchanged on the real artifact. Use for refactors and internal-API migrations.
  • 90dev-refactor-plan
    Use when the user asks for a behavior-preserving refactor plan before implementation. Do not trigger when the user already requested a clear, scoped refactor to be implemented directly.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.