refactor
Safe multi-file refactoring with automatic rollback. Establishes a type/test baseline, plans all changes, executes file-by-file, and verifies zero regressions. Reverts if verification fails after two fix attempts. Handles renames, extracts, moves, splits, merges, and inlines.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- refactor
- license
- MIT
- description
- Safe multi-file refactoring with automatic rollback. Establishes a type/test baseline, plans all changes, executes file-by-file, and verifies zero regressions. Reverts if verification fails after two fix attempts. Handles renames, extracts, moves, splits, merges, and inlines.
- auto-trigger
- false
- last-updated
- 1773964800000
- user-invocable
- true
- trigger_keywords
- [ "refactor", "rename", "extract", "inline", "move file", "split file", "merge files" ]
02 资源文件 2
- 参考文档__benchmarks__/no-target.md714 B
- 参考文档__benchmarks__/specific-refactor.md774 B
03 SKILL.md 正文
/refactor — Safe Multi-File Refactoring
Orientation
Use /refactor when you need to:
- Rename a symbol, file, or module across the codebase
- Extract a function, component, hook, class, or module from existing code
- Inline a function or module back into its callers
- Move a file or set of files to a new location
- Split a large file into smaller pieces
- Merge related files into one
- Change a function signature and update all call sites
Don't use when: debugging a specific bug (use /systematic-debugging); adding new features (use /marshal or /scaffold); deleting dead code (use /marshal for a targeted cleanup).
Boundary with /organize: /refactor changes code structure within files (extract, inline, split, merge, rename) and moves files as part of those operations. Repository-wide file/directory placement, naming sweeps, and where-does-this-belong decisions are /organize.
Behavior does not change. Tests pass before and after, no new type errors — the refactoring is correct.
Commands
| Command | Behavior |
|---|---|
/refactor rename [old] to [new] |
Rename symbol, file, or module |
/refactor extract [target] from [source] |
Extract function/component/module |
/refactor inline [target] |
Inline a function/module into callers |
/refactor move [source] to [dest] |
Move file(s) with import updates |
/refactor split [file] |
Split a file into logical pieces |
/refactor merge [files...] |
Merge related files into one |
/refactor [freeform description] |
Auto-detect refactoring type from description |
/refactor --dry-run [any above] |
Plan only, show what would change |
Protocol
Phase 1: BASELINE
Run typecheck (via node scripts/run-with-timeout.js 300 npm run typecheck) and tests. Record error/failure counts — pre-existing issues are not your responsibility, but you must not add to them. Warn if there are uncommitted changes in files you plan to modify.
Baseline established:
Typecheck: {pass | N errors (pre-existing)}
Tests: {pass | N failures (pre-existing) | no test suite found}
Git: {clean | M files with uncommitted changes}
Phase 2: PLAN
Analyze the refactoring target and produce a concrete plan.
-
Identify scope: Search the codebase for every reference to the target. Use grep/search for:
- Import statements referencing the target
- Usage sites (function calls, type references, component usage)
- Re-exports from index files
- Test files that reference the target
- Documentation or comments mentioning the target
- Config files (e.g., route definitions, dependency injection)
-
Classify the refactoring type and apply type-specific analysis:
Rename (symbol): all imports + usage sites + string references + dynamic access patterns (
obj[key])Rename (file/module): all import paths + path aliases + dynamic imports + index re-exports
Extract (function/component/module): code to extract, enclosing-scope dependencies, return values back to caller, destination file, interface design
Move (file): every import of old path → compute new relative paths, check alias boundary changes, barrel updates
Split (file): logical groupings, internal cross-references, which group keeps the original path, new files per group, index if needed
Merge (files): duplicates/conflicts, import consolidation, merged file organization
-
Produce the plan — list every file that will change and what changes:
Refactoring Plan: {type} — {description}
Files to modify:
1. {file}: {what changes and why}
2. {file}: {what changes and why}
...
Files to create:
- {file}: {extracted from where, contains what}
Files to delete:
- {file}: {contents moved to where}
Risk assessment:
- {any concerns: dynamic references, string-based lookups, config files}
- If
--dry-runwas specified, output the plan and stop.
Phase 3: EXECUTE
Apply changes in this order to minimize intermediate breakage:
- Create new files first (exports only, not yet imported)
- Update importers to point to new locations/names
- Update the source file (remove extracted code, rename, etc.)
- Delete old files last (only after all importers are updated)
- Update index/barrel files
Read each file before editing. Make the minimal change needed — do not reformat unrelated code.
Phase 4: VERIFY
Run typecheck and tests from Phase 1. Compare against baseline — any NEW errors or failures? Search for import paths referencing old/deleted files.
Verification: PASS
Typecheck: {pass | same N pre-existing errors}
Tests: {pass | same N pre-existing failures}
No new broken imports detected.
Phase 5: FIX (if verification fails)
Two attempts: read errors, identify root cause (missed import update, missing re-export, type mismatch), fix, re-run verification. After 2 failed attempts: REVERT.
Phase 6: REVERT (if fixes fail)
- Use
git checkout -- [files]to restore every modified file - Remove any newly created files
- Verify the revert: typecheck should match baseline exactly
- Report what went wrong
REVERTED — Refactoring could not be completed cleanly.
Root cause: {why the refactoring failed}
Errors encountered:
- {error 1}
- {error 2}
Suggestion: {what the user might do differently}
Fringe Cases
- No test baseline: no test suite found in Phase 1 — output: "No tests found. Refactor proceeds without a safety net — abort or continue? Recommend running /test-gen first." Wait for user confirmation before continuing.
- Baseline typecheck fails: typecheck errors exist before any refactor changes — output: "Baseline typecheck failed. Fix existing type errors before refactoring to establish a clean baseline." Do not proceed.
- Build fails after refactor commit: Phase 4 build regression detected — revert the commit with
git revert HEAD --no-edit, then report which verification step introduced the regression and what the failing error is. - Circular dependency detected: import cycle surfaces during scope analysis — treat as a blocker; output: "Circular dependency detected in [file]. Resolve the cycle before proceeding." Do not modify that file without explicit user decision.
- Target file exceeds 500 lines: output: "Warning: [file] is [N] lines. Refactoring may split this file into multiple pieces. Confirm scope before proceeding." Show the proposed split in the plan and wait for user approval.
Quality Gates
- Zero new type errors — zero NEW ones, not just fewer.
- Zero new test failures — baseline failures accepted, new failures are not.
- All imports resolve — no dangling references to old paths or removed exports.
- Behavior unchanged — adding logic or changing return values is scope creep; stop and do it separately.
- Minimal diff — no reformatting, unrelated cleanups, or whitespace changes in untouched files.
- Plan matches execution — every planned file modified, no unplanned files touched.
Exit Protocol
Report the result:
=== Refactor Report ===
Type: {rename | extract | inline | move | split | merge}
Target: {what was refactored}
Changes:
Modified: {N} files
Created: {N} files
Deleted: {N} files
Verification:
Typecheck: {pass | same baseline errors}
Tests: {pass | same baseline failures | no test suite}
Key decisions:
- {any non-obvious choices made during execution}
---HANDOFF---
- Refactored {target}: {what changed}
- {N} files modified, {N} created, {N} deleted
- Typecheck and tests pass (no regressions)
- {any follow-up suggestions}
- Reversibility: green -- single atomic commit, revert with git revert HEAD
---
04 同仓库更多 Skills
workspace
Multi-repo campaign coordinator. Same lifecycle as fleet -- scope claims, discovery relay, wave-based execution -- but the unit of work is a repo, not a file. Coordinates campaigns across repositories with shared context.
wiki
Markdown-first knowledge base where the LLM acts as librarian. Ingests raw sources, compiles and interlinks topic files, self-maintains an index. No vector DB or embeddings required -- uses LLM-native navigation over structured markdown up to ~400K words.
watch
File sentinel that monitors the working directory for changes and marker comments, then auto-triggers appropriate skills. Poll-based via git diff against the last scan commit. Writes intake items for batch processing and routes marker actions through /do. Use for automatic reactions to file changes; do NOT use for one-off inspection or tasks needing human judgment per file.
verify
Self-test the Citadel hook pipeline from within a live session. Exercises real tool calls (Write, Edit, Bash, Read) and checks that hooks fired, telemetry accumulated, and no errors occurred. Reports HOOK HEALTH: PASS or HOOK HEALTH: FAIL with a per-hook breakdown.
unharness
Remove Citadel from a project. Exports valuable state (campaigns, postmortems, research, backlog, discoveries) to docs/citadel/ as human-readable markdown, then removes all harness files and hooks. The archive is detected by /do setup on re-install and offered for restore.
triage
GitHub issue and PR investigator. Pulls open issues/PRs, classifies them, searches the codebase for root cause or reviews contributed code, proposes fixes with file:line references, and optionally implements fixes. Use for investigating GitHub issues and reviewing PRs; do NOT use for general code review unrelated to GitHub issues.