From claude-swe-workflows
Executes autonomous deep refactoring workflow: initial tactical cleanup, architectural restructuring, final tactical cleanup. Gathers scope, aggression, and QA input upfront; handles git branch safety.
npx claudepluginhub chrisallenlane/claude-swe-workflows --plugin claude-swe-workflowsThis skill uses the workspace's default tool permissions.
Convenience workflow that runs a full tactical-then-architectural-then-tactical refactoring cycle. Gathers all user input upfront, then executes autonomously.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Convenience workflow that runs a full tactical-then-architectural-then-tactical refactoring cycle. Gathers all user input upfront, then executes autonomously.
Tactical cleanup first, then structural improvement, then tactical cleanup again. The first /refactor pass clears noise so /review-arch can focus on real structural issues. The architectural pass restructures the codebase. The final /refactor pass cleans up anything the restructuring introduced.
Ask once, then execute. All user decisions are gathered in a single upfront conversation. After that, the workflow runs to completion without interruption. The andon cord is the only escalation path.
┌─────────────────────────────────────────────────────┐
│ REFACTOR-DEEP WORKFLOW │
├─────────────────────────────────────────────────────┤
│ 0. Branch safety check │
│ 1. Gather all user input │
│ ├─ Scope │
│ ├─ Refactor aggression ceiling │
│ ├─ Arch review boldness │
│ └─ QA instructions │
│ 2. Phase 1: /refactor (tactical cleanup) │
│ 3. Phase 2: /review-arch (architectural) │
│ 4. Phase 3: /refactor (post-restructuring cleanup) │
│ 5. /review-doc (once, at the end) │
│ 6. Completion summary │
└─────────────────────────────────────────────────────┘
Before gathering any input, verify the current git branch.
If on main or master:
<branch>. This workflow will make many commits. Create a new branch, or proceed on <branch>?"refactor-deep/<date> (e.g., refactor-deep/2026-04-02) and check it out.If on any other branch: Proceed without asking.
Collect everything upfront in a single conversation. After this step, no further user interaction occurs (except andon cord).
Default: Entire codebase.
If user specifies scope: Respect that scope. Pass it to all three phases.
Ask the user: "How aggressive should the tactical refactoring passes be?"
Present these options:
This ceiling applies to both /refactor passes (phases 2 and 4).
Ask the user: "How bold should the architectural restructuring be?"
Present these options:
/think-deliberate for genuinely ambiguous trade-offs./think-deliberate for high-impact items (module dissolution, new modules). Defer anything that seems uncertain.Ask the user: "Are there any special verification steps for the QA agent? For example: visual checks, manual testing commands, specific scenarios to validate."
If provided: Pass these instructions to QA agents across all three phases.
If none provided: QA agents run standard verification (test suite, linters, formatters).
Run the /refactor workflow with:
Override: Suppress /refactor's built-in /review-doc pass (step 7 in /refactor). Documentation will be updated once at the end.
Run the /review-arch workflow with autonomous overrides:
/review-arch Step | Autonomous Override |
|---|---|
| Step 1 (scope) | As specified in step 1a |
| Step 2 (QA instructions) | As specified in step 1d |
| Step 3 (analyze) | Normal operation |
| Step 4 (present analysis) | Orchestrator reviews the analysis. Do not present to user. |
| Step 5 (iterate on plan) | Orchestrator decides based on boldness level (step 1c). See below. |
| Step 6 (how to proceed) | Proceed with implementation of approved items |
| Steps 7-9 (implement + summary) | Normal operation |
| Step 10 (review-doc) | Suppressed. Documentation updated once at the end. |
Boldness-driven decision-making for step 5:
/think-deliberate only when the analysis contains genuinely contradictory recommendations or unclear trade-offs./think-deliberate to reason through trade-offs. Defer items that seem uncertain — note them in the final summary as recommendations.Run the /refactor workflow again with identical parameters to phase 1:
Override: Suppress /refactor's built-in /review-doc pass. Documentation will be updated once at the end.
This pass cleans up anything the architectural restructuring introduced — new DRY opportunities from function moves, dead code exposed by dissolutions, naming inconsistencies from module renames.
Run the /review-doc workflow once. This is the single documentation pass for the entire workflow. All three phases may have renamed functions, moved code, changed APIs, and restructured modules — documentation is updated to reflect the final state.
Present a consolidated summary across all three phases:
## Refactor-Deep Complete
### Phase 1: Tactical Refactoring
- Commits: N
- Net lines changed: -XXX
- Batches completed: N / aborted: N
### Phase 2: Architectural Review
- Commits: N
- Net lines changed: -XXX
- Blueprint items completed: N / skipped: N
### Phase 3: Tactical Refactoring (Post-Restructuring)
- Commits: N
- Net lines changed: -XXX
- Batches completed: N / aborted: N
### Documentation
- Files updated: N
### Totals
- Total commits: N
- Total net lines changed: -XXX
### Deferred Architectural Items (if any)
[Items the orchestrator chose not to implement, with rationale.
These are recommendations for the user to consider.]
### Aborted/Skipped Items (if any)
- [Description]: [reason for failure]
This protocol applies throughout the entire workflow. The andon cord is the escape valve for problems that cannot be resolved autonomously.
Before pulling the andon cord:
/think-deliberate to reason through optionsWhen the andon cord is pulled:
/think-deliberate results)Andon cord triggers:
Phase-level failures do NOT abort the workflow. If phase 1 finds nothing to refactor, proceed to phase 2. If phase 2 finds no architectural improvements, proceed to phase 3. Only abort the entire workflow on andon cord triggers.
Agent failures within phases: Handled by the sub-workflow's own retry/abort logic (3 failures per batch/item, then skip).
This skill is a composition of:
/refactor — tactical code quality improvements within existing architecture/review-arch — strategic architectural analysis and restructuring/review-doc — documentation audit and updatesRelationship to /lead-project:
/lead-project may invoke /refactor-deep during a cleanup phase of its OODA loop, when comprehensive refactoring is warranted after implementation work is completeRelationship to /implement-project:
/implement-project includes a similar quality pipeline (refactor → arch → refactor) as steps 7a-7c/refactor-deep extracts that pipeline as a standalone workflow for use outside of project implementation/refactor-deep when you want comprehensive refactoring without a ticket-driven implementation phaseRelationship to individual skills:
/refactor alone for quick tactical cleanup/review-arch alone for interactive architectural analysis with user collaboration/refactor-deep when you want the full cycle, autonomous, in one shot