Skip to content
Skills Library
Programming · Building & coding

refactor

/refactor

Behavior-preserving structural refactors with verification gates. Use in conversation when surveying or applying structural refactors. Also the loop entry skill when automation supplies hints (duplication_block, oversized_unit). Interactive default is survey only; apply edits when the user explicitly requests apply or automation sets may_edit in Constraints. Not for lint-only style, features, behavior-changing bugfixes, or upgrades.

Licence
Apache-2.0
Last repository change
18.10.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
41
Scripts
10
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 10 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/detect_refactor.sh, scripts/lib/all.sh, scripts/lib/aws.sh, scripts/lib/common.sh, scripts/lib/csv.sh, scripts/lib/json.sh, scripts/lib/repo_paths.sh, scripts/lib/terraform.sh, scripts/lib/validation.sh, scripts/lib/yaml_map_order.py

What it does and when to use it

Behavior-preserving structural refactors with verification gates. Use in conversation when surveying or applying structural refactors. Also the loop entry skill when automation supplies hints (duplication_block, oversized_unit). Interactive default is survey only; apply edits when the user explicitly requests apply or automation sets may_edit in Constraints. Not for lint-only style, features, behavior-changing bugfixes, or upgrades.

Original author description

Behavior-preserving structural refactors with verification gates. Use in conversation when surveying or applying structural refactors. Also the loop entry skill when automation supplies hints (duplication_block, oversized_unit). Interactive default is survey only; apply edits when the user explicitly requests apply or automation sets may_edit in Constraints. Not for lint-only style, features, behavior-changing bugfixes, or upgrades.

How it works

  1. Input
  2. Output Specification
  3. Execution Scope
  4. Reference Files Guide
  5. Workflow
Original SKILL.md headings · 110 lines, 947 words
SKILL.md preview
---
name: refactor
description: >-
  Behavior-preserving structural refactors with verification gates. Use in
  conversation when surveying or applying structural refactors. Also the loop
  entry skill when automation supplies hints (duplication_block,
  oversized_unit). Interactive default is survey only; apply edits when the
  user explicitly requests apply or automation sets may_edit in Constraints.
  Not for lint-only style, features, behavior-changing bugfixes, or upgrades.
license: Apache-2.0
metadata:
  author: y-miyazaki
  version: "2.8.7"
---

**UTILITY SKILL** — structural refactor survey and apply, not feature work.

## Input

- **Interactive (required):** paths/symbols and optional mode — constraints in `## Constraints` or [category-scope.md](references/category-scope.md)
- **Automation (optional):** detect JSON with `hints[]` in prompt — from a caller or optional skill detect script; not required for interactive runs. Read `may_edit`, `write_target`, and `report_file` (when `write_target: report`) from `## Constraints` per [category-automation-envelope.md](references/category-automation-envelope.md)

Path allowlist, when present, arrives in `## Constraints`.

## Output Specification

Refactor report per [common-output-format.md](references/common-output-format.md). Survey shape when no files are edited; apply shape when edited — within [category-scope.md](references/category-scope.md). Automation path: [common-output-format-automation.md](references/common-output-format-automation.md) and [category-automation-envelope.md](references/category-automation-envelope.md).

## Execution Scope

### USE FOR:

- Survey structural candidates; dedupe, extract/inline, clarify, shallow moves; automation hints; architecture Phase A/B; characterization tests

### DO NOT USE FOR:

- Lint/style-only; features/API/behavior fixes; cross-boundary apply; platform-wide architecture refactors; external debt-survey apply input

## Reference Files Guide

- [common-checklist.md](references/common-checklist.md) (always read)
- [common-output-format.md](references/common-output-format.md) (always read)
- [category-scope.md](references/category-scope.md) (always read)
- [category-contract.md](references/category-contract.md) (always read)
- [category-detect-scope.md](references/category-detect-scope.md) (read on interactive path)
- [category-verification.md](references/category-verification.md) (read when may_edit is true)
- [category-techniques.md](references/category-techniques.md) (read when may_edit is true)
- [category-input-schema.md](references/category-input-schema.md) (read when structured mode JSON, automation detect JSON, or the optional detect script is run)
- [category-automation-envelope.md](references/category-automation-envelope.md) (read on automation path)
- [common-output-format-automation.md](references/common-output-format-automation.md) (read on automation path)
- [common-troubleshooting.md](references/common-troubleshooting.md) (read on failure)

## Workflow

Phases, modes, depth tiers, and intent: [category-contract.md](references/category-contract.md). Self-check gates: [common-checklist.md](references/common-checklist.md).

Canonical sequence: resolve `may_edit` → Phase A (discover/classify; emit only when stopping) → Phase B only when edit-authorized → emit **one** result shape (OUT-01).

Resolve **may_edit** before Phase B. Interactive rows — first match wins:

| Source                                                      | `may_edit`                                                                                                                                                 |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Interactive — structured JSON `mode` present                | From `mode` only (`survey` → `false`; `apply` → `true`) — wins over natural-language; load [category-input-schema.md](references/category-input-schema.md) |
| Interactive — explicit apply language in the same request   | `true` — examples: apply, 適用して, "apply the candidates". Do **not** treat bare skill name `refactor` or bare `fix` as apply                             |
| Interactive — follow-up after a prior survey in the session | `true` when the user explicitly asks to apply listed candidates                                                                                            |
| Interactive — default                                       | `false` — survey only; do not edit files                                                                                                                   |
| Automation — `## Constraints`                               | `may_edit: true` or `may_edit: false` from [category-automation-envelope.md](references/category-automation-envelope.md)                                   |

When `may_edit` is `true`, resolve `write_target`: interactive → `fix`; automation → from `## Constraints`. Do not branch on other caller metadata. Before Phase B, load [category-techniques.md](references/category-techniques.md).

Phase B runs only when `may_edit` is `true` and `write_target` is `fix`. Architecture without `approved_slice` never enters Phase B (INTENT-02).

### Phase A — Survey (always)

Discover and classify only. Emit a final report from Phase A **only** when this run will not enter Phase B (see Interactive / Automation paths).

1. Resolve scope ([category-scope.md](references/category-scope.md)); parse structured/detect JSON when present ([category-input-schema.md](references/category-input-schema.md)).
2. Classify intent ([category-contract.md](references/category-contract.md)).
3. **Architecture without `approved_slice`:** emit survey shape with `### Architecture Proposal` only; stop (INTENT-02). Do **not** treat as zero-actionable no-op.
4. Discover candidates (SURVEY-01): structural → all in-scope; architecture Phase B → **only** the `approved_slice`. Read targets before classifying (SURVEY-03); route apply-worthy → Candidates, else → Watch (SURVEY-02).
5. Structural zero actionable → no-op report; stop.

### Phase B — Apply (`may_edit: true` and `write_target: fix`)

1. For each **apply** candidate: one technique ([category-techniques.md](references/category-techniques.md)); gate ([category-verification.md](references/category-verification.md)); on failure revert → Deferred; continue (APPLY-01).
2. Re-run gates on touched areas; emit apply shape; reconcile with `git diff --name-only` (OUT-01).

### Automation path (`hints[]` in detect JSON)

1. Parse detect JSON; read `may_edit` / `write_target` from `## Constraints`.
2. Empty/`skip` → no-op; stop.
3. Phase A on **all** `hints[]` (structural only — no architecture Phase A/B).
4. `may_edit: false` or `write_target` ≠ `fix` → emit survey shape + Session Metrics (note expected `write_target: fix` when mismatched); no Phase B.
5. Else → Phase B; emit apply shape + Session Metrics ([category-automation-envelope.md](references/category-automation-envelope.md)).

### Interactive path

1. Resolve `may_edit` (table above). Load [category-detect-scope.md](references/category-detect-scope.md).
2. Resolve universe from the prompt (default = `REFACTOR_SCAN_GLOBS` / skill defaults). If the user named paths/globs, narrow the universe before detect.
3. If detect JSON is absent, run `scripts/detect_refactor.sh` with the resolved scope (default `--scope all`; set `REFACTOR_SCAN_GLOBS` for a temporary universe). On non-zero exit or `status: "error"`, read stdout and stop.
4. Phase A: classify every `hints[]` entry and Agent-complement structural candidates (read targets — SURVEY-03). Architecture without `approved_slice` stops inside Phase A step 3.
5. Empty detect alone is not a no-op if complement found apply-worthy or watch-worthy work.
6. `may_edit: false` or `write_target` ≠ `fix` → emit survey shape; stop.
7. Else → Phase B; emit apply shape.

### Error Handling

| Condition                                        | Severity    | Action                                                                          |
| ------------------------------------------------ | ----------- | ------------------------------------------------------------------------------- |
| Detect script non-zero exit or `status: "error"` | Fatal       | Read stdout; stop — do not treat as success-path detect JSON                    |
| Automation: empty/`skip`                         | Info        | No-op report; stop                                                              |
| Survey: zero candidates                          | Info        | No-op report; stop                                                              |
| Architecture request without slice               | Recoverable | Architecture proposal only; stop                                                |
| Lint-primary or feature/API candidate            | Recoverable | Watch on candidate; skip apply                                                  |
| Weak or failed gate for one candidate            | Recoverable | Revert that candidate; Deferred; continue                                       |
| Cross-boundary or out-of-scope target            | Recoverable | Watch on candidate; skip apply                                                  |
| Apply requested but `may_edit` is `false`        | Info        | Survey only; note that edits require explicit apply request or `may_edit: true` |
| `may_edit` true with `write_target` not `fix`    | Recoverable | Survey only; note expected `write_target: fix`                                  |

### Examples

- Prompt: `Survey structural refactor candidates in this package`
- Result: Survey report per [references/common-output-format.md](references/common-output-format.md); apply only when `may_edit` is true, `write_target` is `fix`, and candidates are marked apply.
Files in this package (41)
  • SKILL.md 10 KB
  • eval.yaml 1 KB
  • assets/pr-body-template-survey.md 1 KB
  • assets/pr-body-template.md 1 KB
  • evals/README.md 1 KB
  • evals/evals.json 6 KB
  • evals/tasks/automation-production-constraints.yaml 1 KB
  • evals/tasks/interactive-architecture-proposal-only.yaml 1 KB
  • evals/tasks/interactive-bare-refactor-stays-survey.yaml 1 KB
  • evals/tasks/interactive-fix-follow-up.yaml 1 KB
  • evals/tasks/interactive-fix-same-turn.yaml 1 KB
  • evals/tasks/interactive-mode-survey-wins-over-apply-language.yaml 1 KB
  • evals/tasks/interactive-survey-default.yaml 1 KB
  • evals/tasks/may-edit-false.yaml 1 KB
  • evals/tasks/refactor-automation-dist01-negative.yaml 1 KB
  • evals/tasks/refactor-automation-duplication.yaml 1 KB
  • evals/tasks/refactor-automation-noaction.yaml 1 KB
  • evals/tasks/refactor-noop.yaml 1 KB
  • evals/tasks/refactor-survey.yaml 1 KB
  • references/category-automation-envelope.md 4 KB
  • references/category-contract.md 6 KB
  • references/category-detect-scope.md 2 KB
  • references/category-input-schema.md 6 KB
  • references/category-pr-body-links.md 1 KB
  • references/category-scope.md 1 KB
  • references/category-techniques.md 5 KB
  • references/category-verification.md 1 KB
  • references/common-checklist.md 6 KB
  • references/common-output-format-automation.md 3 KB
  • references/common-output-format.md 6 KB
  • references/common-troubleshooting.md 1 KB
  • scripts/detect_refactor.sh 16 KB
  • scripts/lib/all.sh 1 KB
  • scripts/lib/aws.sh 29 KB
  • scripts/lib/common.sh 9 KB
  • scripts/lib/csv.sh 4 KB
  • scripts/lib/json.sh 8 KB
  • scripts/lib/repo_paths.sh 15 KB
  • scripts/lib/terraform.sh 13 KB
  • scripts/lib/validation.sh 14 KB
  • scripts/lib/yaml_map_order.py 6 KB

Versions

RepositoryScoreLicence
This page · y-miyazaki/terraform-aws-base100Apache-2.0
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

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 548a563f7600 (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

  • 100tech-debt
    Discover and classify technical debt from mechanical signals; apply closed-set fixes when requested. Use in conversation when the user asks to survey or fix safe documentation/dependency debt. Also the loop entry skill for scheduled scans or detect JSON. Interactive default is…
  • 100dev-refactor
    AI DevKit · Systematic structural or multi-file refactors across any stack while preserving behavior and public contracts. Use for reorganizing modules, boundaries, naming, APIs/contracts, staged refactor plans, or refactor risk review.
  • 100changelog
    Survey and update CHANGELOG.md from unreleased commits and undocumented releases. Use in conversation when the user asks to check, review, or update the changelog. Also the loop entry skill when automation supplies commit/release detect JSON. Interactive default is survey only;…
  • 100refactor-safe
    Use for safe refactors that preserve behavior. Keep diffs small and verification strong.
  • 100refactoring-guide
    Plan and apply small, behavior-preserving refactors one step at a time, running tests after each step and adding characterization tests first when coverage is thin. Use when the user asks to refactor, clean up, simplify, split a large function or class, remove duplication,…
  • 100tdd-workflow
    Use this skill for test-first implementation of new features, bug fixes, and refactors with RED-GREEN-REFACTOR discipline and explicit verification gates.

Feedback and reports

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