| name | pipeline-refactor |
| description | Execute a Refactor pipeline: environment check, analysis, refactor execution, test, review, documentation, commit & PR, code review, test verification, review verdict, merge, and retrospective. Invoke with /pipeline-refactor followed by the refactor description.
|
Refactor Pipeline
Run a complete refactoring cycle with analysis, behavior-preserving execution, review, and quality gates.
Usage: /pipeline-refactor <refactor description>
CRITICAL: You MUST execute ALL 13 stages. Do NOT stop after Commit & PR (Stage 8). Stages 9-13 (Code Review, Test Verification, Review Verdict, Merge PR, Retrospective) are mandatory.
Before You Start
- Generate a branch name from the task:
refactor/<short-slug> (e.g., refactor/split-views-module)
- Initialize state file (Step 0): Follow the Step 0: Initialize State File procedure from pipeline-shared. This is the FIRST action — creates
.pipeline-state/<branch-name>.json from templates/refactor-state.json. If it already exists, this is a resume.
- Follow the Configuration Gathering procedure from pipeline-shared to identify project config
- Note the project's pr_target_branch (default:
main)
Stage 1: Environment Check
Follow the Environment Check procedure from pipeline-shared.
Gate: ENV_OK required.
On ENV_FAILED: Retry once. If retry fails → STOP PIPELINE.
Stage 2: Conflict Check
Follow the Conflict Check procedure from pipeline-shared.
Gate: MERGE_CLEAN required.
On MERGE_CONFLICTS_FOUND → STOP PIPELINE.
Stage 3: Analysis
Analyze the code to be refactored.
Instructions
- Read the refactor description and identify the target code
- Understand the current structure and patterns
- Identify code smells and issues motivating the refactor
- Propose a refactoring approach
- List all files that will be affected
- Assess risk: what could break, what tests cover the code
Output
- Current structure and patterns
- Code smells and issues found
- Proposed refactoring approach (step by step)
- Files that will be affected
- Risk assessment
Gate
This stage always passes (informational). The analysis output will be referenced by Refactor Execution and Review.
Stage 4: Refactor Execution
Execute the refactoring based on the analysis from Stage 3.
Instructions
- Apply the refactoring as planned in the analysis
- Preserve all existing behavior — this is a refactor, not a feature change
- Do not add new functionality or change APIs
- Ensure all existing tests continue to pass
- Clean git state: Follow the Clean Git State procedure from pipeline-shared
If the branch already has commits from a previous attempt, build on that work — do NOT redo what's already done.
Gate
Stage passes if refactoring completes without errors. Proceed to testing.
Stage 5: Test Execution
Follow the Test Execution procedure from pipeline-shared.
Gate: TESTS_PASSED required.
On TESTS_FAILED: Go back and fix the issue (behavior must be preserved), then re-run tests (attempt 2 of 2). If tests still fail → STOP PIPELINE.
Stage 6: Review
Review the refactoring changes for quality and behavior preservation.
Instructions
-
Analysis compliance: Cross-reference the Analysis stage output (Stage 3) against the refactoring. Flag any planned changes that were not implemented.
-
Behavior preservation: Verify that all existing behavior is preserved. No functional changes.
-
Code quality: Verify the code is cleaner and more maintainable than before.
-
Dead code: No dead code left behind.
-
Naming consistency: Variable, function, and class names are consistent.
Gate
- Pass:
REVIEW_PASSED
- Fail:
REVIEW_FAILED — followed by list of issues
On REVIEW_FAILED (attempt 1): Fix the issues, then re-check.
On REVIEW_FAILED (attempt 2): Rewind to Stage 3 (Analysis). The original analysis may have missed something. Re-analyze with the review context. Then re-execute from Stage 4 onward. Maximum 1 rewind. If second pass also fails → STOP PIPELINE.
Stage 7: Documentation
Follow the Documentation procedure from pipeline-shared.
Gate: DOCS_UPDATED (always passes).
Stage 8: Commit & PR
Follow the Commit & PR procedure from pipeline-shared.
Use conventional commit format: refactor: <description>
Gate: PR_CREATED, PR_EXISTS, or PR_SKIPPED.
After this stage completes, you MUST continue to Stage 9. The pipeline is NOT done.
Stages 9-13: Review, Verify, Merge, Retrospective
These stages run as subagents to ensure they execute with fresh context.
Stage 9-11: Code Review + Test Verification + Review Verdict
Use the Agent tool to spawn a subagent with this prompt:
You are reviewing PR #<pr_number> for a refactor. The project directory is <project_path>. The PR targets <pr_target_branch>.
Step 1 — Code Review:
- Run
git diff <pr_target_branch>...HEAD to see all changes. Read changed files for full context.
- Check for a project PR checklist at
docs/PULL_REQUEST_CHECKLIST.md or PULL_REQUEST_CHECKLIST.md — if found, use it as the review framework.
- Review for: behavior preservation (refactor MUST NOT change functionality), correctness, security, testing gaps, code quality, documentation. Flag auto-reject triggers.
- Post the review to GitHub:
gh pr review <pr_number> --comment --body '<formatted review with checklist and findings>'
- If the project has a
pr/feedback/ directory, save to pr/feedback/pr-<number>-<short-slug>.md.
Step 2 — Test Verification: Run the project test suite. Report pass/fail.
Step 3 — Review Verdict: Synthesize findings.
- If auto-reject triggers OR tests failed →
gh pr review <pr_number> --request-changes --body '<issues>' and output REQUEST_CHANGES.
- Otherwise → output APPROVE.
- If
APPROVE → proceed to Stage 12
- If
REQUEST_CHANGES → fix issues, re-commit, re-push, re-run subagent. Second failure → STOP PIPELINE.
Stage 12: Merge PR
Use the Agent tool to spawn a subagent:
Approve and merge PR #<pr_number> in <project_path>.
gh pr merge <pr_number> --squash --delete-branch
Do NOT run gh pr review --approve — GitHub blocks self-approval.- Output PR_MERGED or MERGE_FAILED.
- If
PR_MERGED → proceed to Stage 13
- If
MERGE_FAILED → retry once. Still failing → STOP PIPELINE.
Stage 13: Retrospective
Use the Agent tool to spawn a subagent:
You are writing a retrospective for a completed refactor pipeline. Task: <task description>. Project: <project_path>. PR #<pr_number>.
Run git log --oneline <pr_target_branch>..HEAD. Evaluate: quality (1-5), what went well, lessons learned, improvements, IDEA:/TOOL: lines.
You MUST post the retrospective to these two places. This is not optional.
gh pr comment <pr_number> --body "## Pipeline Retrospective\n\n**Quality**: X/5\n\n### What Went Well\n- ...\n\n### Lessons Learned\n- ...\n\n### Suggested Improvements\n- IDEA: ..."- Append to
.pipeline-log.md (create if needed, ensure in .gitignore).
Output RETRO_COMPLETE when both posts are done.
The pipeline is now complete.
Stop Conditions
ENV_FAILED after retryMERGE_CONFLICTS_FOUNDTESTS_FAILED after retry (Stage 5 or 10)REVIEW_FAILED after retry + rewindMERGE_FAILED after retry
Rewind Rules
| Stage | Can Rewind To | Max Rewinds | Trigger |
|---|
| Stage 6 (Review) | Stage 3 (Analysis) | 1 | REVIEW_FAILED after retry |
