prizmkit 1.1.0 → 1.1.3

package/bundled/skills/refactor-workflow/SKILL.md

@@ -1,424 +1,404 @@
 ---
 name: "refactor-workflow"
-tier: 1
-description: "End-to-end refactor workflow: structured scoping → parallel code & doc analysis → collaborative planning → implement → review → commit. 6-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
+tier: companion
+description: "One-stop entry point for code refactoring. Brainstorms refactoring goals with the user until fully clarified, then orchestrates refactor-planner → refactor-pipeline-launcher → execution. Handles multi-refactor batch development from a single request. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring', 'batch refactor'. (project)"
 ---
 
-# PrizmKit Refactor Workflow
+# Refactor Workflow
 
-End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 6-phase behavior-preserving pipeline with mandatory test gates after each task.
+One-stop entry point for code refactoring. Covers the complete journey from a rough refactoring idea to verified, behavior-preserving code changes: deep goal clarification → structured planning → autonomous pipeline execution.
 
-### When to Use
-- User says "refactor", "clean up code", "restructure", "extract module", "code refactoring", "optimize code structure"
+## When to Use
+
+User says:
+- "Refactor the auth module", "Clean up this code", "Restructure the payment service"
+- "Extract shared logic into a separate module", "Optimize code structure"
+- "Batch refactor these modules", "Code refactoring across multiple files"
 - Code has accumulated tech debt that needs structural improvement
 - Module needs to be split, merged, or reorganized
-- When behavior must remain unchanged but internal quality needs improvement
 
-**Do NOT use when:**
-- User wants to add new features (use `feature-workflow`)
+**Do NOT use this skill when:**
+- User only wants to plan refactoring (use `refactor-planner` directly)
+- User only wants to launch pipeline for existing refactor-list.json (use `refactor-pipeline-launcher`)
+- User wants to add features (use `feature-workflow`)
 - User wants to fix bugs (use `bug-planner` + `bugfix-pipeline-launcher`)
-- Change is trivial (single rename, <5 lines) — just do it directly
+
+---
 
 ## Overview
 
 ```
-refactor-workflow
-  → Phase 0: Branch              → refactor/<slug> branch
-  → Phase 1: Understand & Analyze → structured scoping + parallel Agent reading + collaborative planning
-  → Phase 2: Plan                → plan.md (including Tasks section)
-  → Phase 3: Implement           → (code)
-  → Phase 4: Review              → (review report)
-  → Phase 5: Verify & Commit     → git commit + merge decision
+refactor-workflow <target / goals>
+   │
+   ├── Phase 1: Brainstorm → interactive Q&A until refactoring goals are clear
+   │
+   ├── Phase 2: Plan → refactor-planner → refactor-list.json
+   │
+   ├── Phase 3: Launch → refactor-pipeline-launcher → pipeline execution
+   │
+   └── Phase 4: Monitor → track progress → report results
 ```
 
-### Pipeline Phases
-
-| Phase | Name | Skill Used | Artifact |
-|-------|------|-----------|----------|
-| 0 | Branch Setup | git | → `refactor/<slug>` branch |
-| 1 | Understand & Analyze | Interactive scoping + parallel Agent reading + code analysis | → Refactoring scope confirmed + `refactor-analysis.md` |
-| 2 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
-| 3 | Implement | `/prizmkit-implement` | (code changes) |
-| 4 | Code Review | `/prizmkit-code-review` | (review report) |
-| 5 | Verify & Commit | `/prizmkit-committer` | git commit + merge |
-
-### Key Principles
-
-| Principle | Description |
-|-----------|-------------|
-| **Structured scoping first** | Use structured choices (not open-ended Q&A) to quickly establish refactoring type, scope, and reference materials. |
-| **Parallel understanding** | Dispatch multiple Agents concurrently to read code, docs, and knowledge files — don't read sequentially. |
-| **Show findings, then collaborate** | Present what the Agents discovered, then work with the user to shape the refactoring plan — don't just ask questions without context. |
-| **Behavior preservation** | Refactoring changes structure, not behavior. If tests pass before and after, behavior is preserved. |
-| **Test gates** | Full test suite runs after every task — not just at checkpoints. |
-| **Structural sync only** | Refactoring triggers `/prizmkit-retrospective` Job 1 (structural sync) — update `.prizm-docs/` to reflect file/interface changes. Skip knowledge injection unless a genuinely new pitfall was discovered. |
-| **Incremental safety** | Each task preserves all tests (green → green). If tests fail → stop and revert. |
-
-### Artifacts
-Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
-- **`refactor-analysis.md`** — Scoping + code analysis (Phase 1)
-- **`plan.md`** — Refactoring plan with Tasks section (Phase 2)
-
-**PRECONDITION:**
-
-| Required | Check | If Missing |
-|---|---|---|
-| Refactoring target (module path, file path, or natural language description) | User provides target in request | Ask: "What module or code do you want to refactor?" |
-| Test suite exists for target module | Tests can be located and run | WARN user, recommend writing tests first before refactoring |
-| No uncommitted changes on current branch | `git status` is clean | Ask user to commit or stash changes first |
-
-**INPUT**: Target description. Can be:
-- Module or file path (e.g., "src/auth/")
-- Natural language description (e.g., "refactor the auth module, extract shared logic")
-- Specific refactoring goal (e.g., "extract payment processing into separate service")
+### What This Skill Does
 
----
+| Phase | Action | Result |
+|-------|--------|--------|
+| 1 | **Brainstorm** — interactive Q&A with user | Fully clarified refactoring goals |
+| 2 | Call `refactor-planner` with clarified goals | `refactor-list.json` with N refactor items |
+| 3 | Call `refactor-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
+| 4 | Monitor progress | Status updates, completion report |
 
-## Phase 0: Branch Setup
+### Why This Skill Exists
 
-**Goal**: Create an isolated working branch to keep main clean.
+Without this skill, users must:
+1. Figure out all refactoring goals and scope themselves
+2. Invoke `refactor-planner` → wait for refactor-list.json
+3. Invoke `refactor-pipeline-launcher` → wait for pipeline start
+4. Manually check progress
 
-1. **Check current branch**:
-   ```bash
-   git branch --show-current
-   ```
-2. **If on `main` or a shared branch**: Create and switch to refactor branch:
-   ```bash
-   git checkout -b refactor/<refactor-slug>
-   ```
-   Example: `git checkout -b refactor/extract-auth-middleware`
-3. **If already on a refactor branch**: Confirm with user: "Continue on current branch `<branch-name>`, or create a new one?"
-4. **Record the original branch name** for later merge.
+With this skill, users can:
+1. Say "Refactor the auth module to extract shared middleware" with a rough idea
+2. The skill brainstorms to fill in all gaps (scope, risks, behavior contracts)
+3. All planning + execution happens automatically
+
+### Branch Management
 
-**CHECKPOINT CP-RW-0**: On a dedicated refactor branch, not main/shared branch.
+The dev-pipeline handles branch management per-refactor automatically:
+- Each refactor item is implemented on its own branch by the pipeline
+- Branches are created, committed, and managed by the pipeline session
+- This workflow does NOT create a top-level branch — the pipeline manages granular per-refactor branches
 
 ---
 
-## Phase 1: Understand & Analyze
+## Input Modes
 
-**Goal**: Through structured choices, parallel Agent reading, and collaborative discussion, fully understand the refactoring scope and produce a code analysis — all in one integrated phase.
+**Mode A: From natural language description** (default)
 
-**CRITICAL RULE**: This phase has 5 steps executed in order. Do NOT skip to planning without completing all steps, especially the parallel reading and collaborative discussion.
+Natural language description of the refactoring goals. Can be:
+- A module target: "Refactor the auth module — extract shared middleware, simplify the token flow"
+- A batch of refactors: "Clean up the payment service, decouple the notification module, and extract common utilities"
+- An incremental request: "Also refactor the logging layer to use structured logging"
 
-### Step 1.1: Refactoring Type Selection
+Flow: brainstorm → refactor-planner → refactor-pipeline-launcher → monitor
 
-Present the user with a structured choice to establish the refactoring approach:
+**Mode B: From existing refactor-list.json**
 
-Ask the user to choose:
-- **(a) Incremental refactoring** — Gradual, low-risk improvements. Refactor piece by piece, each step independently deployable.
-- **(b) Full refactoring** — Comprehensive restructuring of the entire target area. Higher risk, bigger payoff.
-- **(c) Targeted refactoring** — Focus on a specific part or concern (e.g., extract one module, decouple one dependency, simplify one flow).
+When user says "run pipeline from existing file" or refactor-list.json already exists:
+- Skip brainstorm and `refactor-planner` (file already exists)
+- Invoke `refactor-pipeline-launcher` directly
+- Monitor and report progress
 
-Follow up based on choice:
-- If **(a)**: Ask which area to start with, and what the incremental milestones should be
-- If **(b)**: Confirm the full scope boundary — what's included and what's explicitly excluded
-- If **(c)**: Confirm the specific target and the expected outcome
+**Mode C: Incremental (add to existing refactor plan)**
 
-### Step 1.2: Reference Materials Collection
+When user says "add more refactors" or the project already has a refactor-list.json:
+- Brainstorm new refactoring goals with the user
+- Invoke `refactor-planner` in incremental mode (reads existing refactor-list.json)
+- Append new refactor items to existing list
+- Invoke `refactor-pipeline-launcher`
+- Monitor and report progress
 
-Ask the user if they have supplementary materials that can inform the refactoring:
+---
 
-Present as a multi-select checklist:
-- **Code paths** — Specific files or directories to focus on (e.g., `src/auth/`, `lib/payment.js`)
-- **Refactoring-related documents** — Design docs, RFCs, architecture proposals, migration guides
-- **Existing knowledge docs** — `.prizm-docs/`, ADRs, inline documentation, wiki pages, or team notes about the target area
-- **None** — No additional materials, rely on code reading
+## Phase 1: Brainstorm — Deep Refactoring Goal Clarification
 
-For each item the user provides, record the path or description for the next step.
+**Goal**: Through interactive Q&A, transform the user's rough refactoring idea into fully clarified, implementation-ready refactoring goals. This phase is the foundation for safe, behavior-preserving code changes — vague goals produce risky refactors.
 
-### Step 1.3: Parallel Agent Reading
+**CRITICAL RULE**: The number of questions is **unlimited**. Do NOT rush through this phase. Ask as many rounds as needed until every aspect is clear. Refactoring is inherently risky — thorough understanding prevents broken behavior.
 
-Based on the user's selections in Steps 1.1 and 1.2, dispatch **multiple Agents in parallel** to read and analyze:
+### Step 1.1: Understand the User's Refactoring Goals
 
-**Agent allocation strategy:**
-- **Agent A (Code Structure)**: Read the target code files — understand architecture, dependencies (incoming/outgoing), module boundaries, public API surface
-- **Agent B (Documentation)**: Read any user-provided docs + relevant `.prizm-docs/` (TRAPS, PATTERNS, RULES) + TODO/FIXME/HACK comments in target code
-- **Agent C (Test Baseline)**: Locate and run test suites for the target area — record pass/fail counts, identify pre-existing failures, assess coverage
+Ask the user to describe what they want to refactor. Listen for:
+- **What** code needs restructuring (modules, files, patterns)
+- **Why** it needs refactoring (tech debt, coupling, complexity, readability, performance structure)
+- **What outcome** they want (target architecture, desired structure, quality goals)
 
-If the user provided no docs (chose "None" in Step 1.2), Agent B focuses entirely on `.prizm-docs/` and inline code comments.
+### Step 1.2: Context Gathering
 
-**Each Agent produces a structured summary:**
-- Agent A: file inventory, dependency graph, complexity hotspots, code smells
-- Agent B: known traps, architectural decisions, existing knowledge about the target
-- Agent C: test suite status (total/passing/failing), coverage estimate, behavior contracts
+Before asking detailed questions, gather existing project context:
+- If `.prizm-docs/root.prizm` exists → read it to understand existing architecture, tech stack, patterns
+- If `.prizmkit/config.json` exists → read tech stack preferences
+- If existing source code exists → scan directory structure:
+  ```bash
+  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+  ```
+- Check test suite existence and coverage for the target area:
+  ```bash
+  find . -maxdepth 4 -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -path "*/tests/*" -o -path "*/__tests__/*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' | head -20
+  ```
 
-### Step 1.4: Present Findings & Collaborative Planning
+This context informs better questions — e.g., if the target module has no tests, the conversation must address test coverage before refactoring.
 
-After all Agents complete, **present a consolidated findings report** to the user:
+### Step 1.3: Adaptive Deep-Dive Questioning
 
-```
-## Refactoring Findings
-
-### Code Structure (Agent A)
-- [file inventory, dependency graph, complexity metrics]
-- [identified code smells: long functions, deep nesting, duplication, coupling]
-
-### Existing Knowledge (Agent B)
-- [known traps and risks from docs]
-- [relevant architectural decisions]
-- [user-provided doc insights]
-
-### Test Baseline (Agent C)
-- [test suite status: X total, Y passing, Z failing]
-- [coverage estimate]
-- [behavior contracts to preserve]
-
-### Recommended Refactoring Approach
-- [based on findings, propose concrete refactoring strategy]
-- [identify highest-impact opportunities]
-- [flag risks and cross-module impacts]
-```
+Based on the user's description, ask questions across these dimensions. **Adapt question depth to the refactoring complexity** — a simple extract-method refactor needs fewer questions than a full module decomposition.
 
-Then engage the user in **collaborative discussion**:
-- "Based on these findings, here's what I recommend for the refactoring approach. What do you think?"
-- Discuss priorities: which improvements matter most?
-- Discuss constraints: any areas that are off-limits?
-- Discuss risks: how to handle fragile or undocumented areas?
-- If the scope needs adjustment based on findings, negotiate with the user
+**Code Structure:**
+- What's wrong with the current structure? What specific pain points exist?
+- What's the target state? What should the code look like after refactoring?
+- Are there specific code smells? (duplication, deep nesting, god classes, tight coupling)
+- What are the dependency relationships between the target and other modules?
 
-### Step 1.5: Confirm & Generate Analysis
+**Scope:**
+- Which files/modules are in scope? Which are explicitly out of scope?
+- Is this a single-module refactor or does it span multiple modules?
+- Should the refactoring be incremental (piece by piece) or comprehensive?
 
-After the collaborative discussion concludes:
+**Behavior Preservation:**
+- What behavior must stay identical? Are there contracts/APIs that must not change?
+- What tests exist for the target area? Are they passing currently?
+- Are there integration tests or end-to-end tests that cover this area?
+- Any undocumented behavior that callers depend on?
 
-1. **Ask the user**: "Is there anything else you'd like to add or adjust before we finalize the refactoring scope?"
-2. **If yes**: Incorporate feedback, revisit relevant points
-3. **If no**: Generate `refactor-analysis.md` at `.prizmkit/refactor/<refactor-slug>/refactor-analysis.md`
+**Risk Assessment:**
+- What could break? Are there fragile or undocumented areas?
+- Are there known gotchas or traps in this code? (check `.prizm-docs/` TRAPS)
+- Does this code have external consumers (other teams, published APIs)?
+- Any concurrent development happening in the target area?
 
-**`refactor-analysis.md` required sections:**
-- **Refactoring Type**: Incremental / Full / Targeted (from Step 1.1)
-- **Current State**: module overview, file inventory, dependency graph, complexity metrics (from Agent A)
-- **Refactoring Goals**: what structural improvements are targeted, why — aligned with collaborative discussion
-- **Risk Assessment**: what could break, cross-module impact, fragile areas (from Agent B + discussion)
-- **Baseline Tests**: test suite status, coverage estimate, behavior contracts to preserve (from Agent C)
-- **Scope Boundary**: what IS in scope, what is explicitly OUT of scope — confirmed with user
-- **Reference Materials**: list of docs/paths the user provided and key insights from each
+**Constraints:**
+- Timeline or urgency? (affects whether to do incremental vs comprehensive)
+- Team coordination needed? (other developers working in the same area)
+- Deployment concerns? (feature flags, backward compatibility, migration)
 
-**CHECKPOINT CP-RW-1**: `refactor-analysis.md` exists with confirmed scope, baseline test results, and user agreement.
+### Step 1.4: Iterative Clarification Loop
 
----
+After the initial deep-dive:
 
-## Phase 2: Plan — Refactor Plan & Tasks
+1. **Summarize** what you've understood so far — present it back to the user
+2. **Identify gaps** — explicitly list any areas that are still unclear or ambiguous
+3. **Ask follow-up questions** for each gap
+4. **Repeat** until the user confirms: "Yes, that covers everything" or "That's clear enough"
 
-**Goal**: Generate technical refactoring plan that preserves behavior, including task breakdown.
+**Signs that brainstorming is complete:**
+- All refactoring goals have concrete target state descriptions
+- Scope boundaries are clearly defined (in/out)
+- Behavior preservation contracts are identified
+- Risk areas are acknowledged and mitigation is discussed
+- The user has confirmed the summary is accurate
 
-**STEPS:**
+**Signs that more questions are needed:**
+- User's answers contain vague terms ("clean it up", "make it better", "fix the structure")
+- Scope is undefined ("refactor everything" without specifics)
+- No awareness of test coverage for the target area
+- Risk areas are handwaved ("it should be fine")
+- User says "I'm not sure" — help them think through it with concrete options
 
-1. **Read context**: refactor-analysis.md, `.prizm-docs/` (PATTERNS, RULES, TRAPS)
-2. **Invoke `/prizmkit-plan`** with refactor-analysis.md as input (in place of spec.md):
-   - Plan specifies: what changes, what stays the same, how behavior is preserved
-   - plan.md Tasks section: each task is independently testable and preserves all tests (green → green) — this ensures any failure is immediately traceable to the task that caused it
-   - Artifact path: `.prizmkit/refactor/<refactor-slug>/plan.md`
-3. **Verify plan constraints**:
-   - All public API contracts preserved (unless explicitly agreed in Phase 1 to change)
-   - Test strategy: how to verify behavior unchanged at each step
-   - Rollback strategy: how to revert if behavior breaks
-   - Tasks ordered to minimize risk (safe renames first, structural changes later)
-   - Every task ends with "run full test suite"
+### Step 1.5: Requirements Summary
 
-**CHECKPOINT CP-RW-2**: `plan.md` exists with behavior preservation strategy and Tasks section.
+Once brainstorming is complete, produce a structured goals summary:
 
----
+```markdown
+## Refactoring Goals Summary
+
+### Target: [Module/area name]
+
+### Refactoring Objectives
+- [Bullet list of what structural changes are needed and why]
+
+### Current Problems
+- [What's wrong with the current structure]
+
+### Target State
+- [What the code should look like after refactoring]
+
+### Scope
+- **In scope**: [files, modules, directories]
+- **Out of scope**: [explicitly excluded areas]
 
-## Phase 3: Implement
+### Behavior Preservation Contracts
+- [What behavior must remain unchanged]
+- [Key APIs/interfaces that must be preserved]
+- [Existing test coverage status]
 
-**Goal**: Execute refactoring tasks with mandatory test verification after each task.
+### Risk Assessment
+- [Risk]: [Mitigation strategy]
 
-**STEPS:**
+### Constraints
+- [Timeline, coordination, deployment concerns]
 
-1. **For EACH task in plan.md Tasks section**:
-   a. Implement the refactoring change
-   b. **Run FULL test suite** (not just affected tests) — refactoring can have surprising cross-module effects that targeted tests miss
-   c. Verify: all previously-passing tests still pass
-   d. If any test fails → stop, revert task, investigate
-2. **Progress tracking**:
-   - Mark tasks complete in plan.md Tasks section as they finish
-   - Record test results after each task
+### Confirmed by user: ✓
+```
 
-**CHECKPOINT CP-RW-3**: All tasks complete, full test suite green.
+Present this summary to the user and get explicit confirmation before proceeding to Phase 2.
 
-**Important constraints for Phase 3:**
-- Never skip the test gate between tasks — a broken intermediate state compounds into much harder debugging later
-- Never allow temporary test failures ("we'll fix it in the next task") — this assumption is almost always wrong in refactoring
-- If a task cannot be completed without breaking tests → split it into smaller tasks
-- Max 3 attempts per task before escalating to user
+**CHECKPOINT CP-RW-0**: Refactoring goals fully clarified and confirmed by user.
 
 ---
 
-## Phase 4: Code Review
+## Phase 2: Plan
+
+**Goal**: Generate structured refactor-list.json from the clarified refactoring goals.
+
+**STEPS**:
 
-**Goal**: Verify refactoring quality and behavior preservation.
+1. **Invoke `refactor-planner` skill** with the full goals summary from Phase 1:
+   - Pass the structured goals summary as input — NOT the raw user conversation
+   - For new refactoring: standard planning mode
+   - For existing projects with `--incremental`: incremental planning mode
 
-**STEPS:**
+2. **Interactive planning** (if refactor-planner requires clarification):
+   - Because Phase 1 was thorough, refactor-planner should need minimal clarification
+   - If questions arise, answer from the Phase 1 context or pass through to user
 
-1. **Invoke `/prizmkit-code-review`** (scoped to changed files, both phases):
-   - Review dimensions for refactoring:
-     - **Behavior preservation**: Does observable behavior remain identical?
-     - **Structural improvement**: Is the code measurably better? (complexity, coupling, readability)
-     - **Test integrity**: Are all tests still meaningful and passing?
-     - **Code quality**: Does refactored code follow project conventions?
-   - If findings exist, produce Fix Instructions with Root Cause, Fix Strategy, and Verification criteria
-   - Verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
-2. **Run full test suite one final time**: All tests must pass
-3. **Handle review results**:
-   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 5
-   - **NEEDS_FIXES**: Return to Phase 3 following Fix Instructions (max 2 review rounds)
+3. **Validate output**:
+   - Confirm `refactor-list.json` exists
+   - Show summary: total refactor items, complexity distribution, dependencies
 
-**CHECKPOINT CP-RW-4**: Code review passes, all tests green.
+**CHECKPOINT CP-RW-1**: `refactor-list.json` generated and validated.
+
+**If user says `--from <file>`**: Skip Phase 1 and Phase 2 entirely.
 
 ---
 
-## Phase 5: Verify, Commit & Merge
-
-**Goal**: Let user verify, commit with refactor convention, and merge back.
-
-**STEPS:**
-
-1. **User verification** (optional):
-   - Ask user: "Refactoring complete and all tests pass. Would you like to verify before committing?"
-     - **(a) Run the app** — Start dev server for manual verification
-     - **(b) Run a specific command** — Specify a test or script
-     - **(c) Skip** — Proceed to commit (tests already pass)
-   - If user reports issues: return to Phase 3
-2. **Invoke `/prizmkit-retrospective`** (Job 1: structural sync only):
-   - Update KEY_FILES/INTERFACES/DEPENDENCIES in affected `.prizm-docs/` files
-   - Skip knowledge injection unless refactoring revealed a genuinely new pitfall (e.g. a non-obvious coupling)
-   - If structural changes are significant (module split/merge), update L1 doc
-   - Stage doc changes: `git add .prizm-docs/`
-3. **Invoke `/prizmkit-committer`**:
-   - Commit message: `refactor(<scope>): <description>`
-   - Include all refactored code + any test updates
-   - Do NOT push
-4. **Ask merge preference**:
+## Phase 3: Launch
+
+**Goal**: Start the refactoring pipeline.
+
+**STEPS**:
+
+1. **Show refactor summary** before launching:
    ```
-   Refactoring committed on branch `refactor/<slug>`.
-   What would you like to do?
-   (a) Merge to <original-branch> and delete refactor branch
-   (b) Keep refactor branch (for PR review workflow)
-   (c) Decide later
+   Ready to launch pipeline with N refactor items:
+     R-001: Extract auth middleware (medium complexity)
+     R-002: Decouple notification service (high complexity)
+     R-003: Simplify token flow (low complexity)
+
+   Proceed? (Y/n)
    ```
-5. **If (a)**:
+
+2. **Invoke `refactor-pipeline-launcher` skill**:
+   - The launcher handles all prerequisites checks
+   - The launcher presents execution mode choices to the user (foreground/background/manual)
+   - Do NOT duplicate execution mode selection here — let the launcher handle it
+   - Returns PID/status and log file location
+
+3. **Verify launch success**:
+   - Confirm pipeline is running
+   - Record PID and log path for Phase 4
+
+**CHECKPOINT CP-RW-2**: Pipeline launched successfully.
+
+---
+
+## Phase 4: Monitor
+
+**Goal**: Track pipeline progress and report to user.
+
+**STEPS**:
+
+1. **Initial status check**:
    ```bash
-   git checkout <original-branch>
-   git merge refactor/<slug>
-   git branch -d refactor/<slug>
+   dev-pipeline/launch-refactor-daemon.sh status
    ```
-6. **If (b)**: Inform user: "Branch `refactor/<slug>` retained. Create a PR when ready."
 
-**CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix. Merge decision made.
+2. **Offer monitoring options**:
+   - "I'll check progress periodically. Say 'status' anytime for an update."
+   - "Say 'logs' to see recent activity."
+   - "Say 'stop' to pause the pipeline."
 
----
+3. **Periodic progress reports** (when user asks):
+   ```bash
+   python3 dev-pipeline/scripts/update-refactor-status.py \
+     --refactor-list refactor-list.json \
+     --state-dir dev-pipeline/refactor-state \
+     --action status
+   ```
 
-## Fast Path
+4. **Completion report** (when pipeline finishes all refactor items):
+   ```
+   Pipeline completed: 3/3 refactor items
 
-For single-file refactoring (rename, extract method, <30 lines changed):
+   Summary:
+   - R-001: Extract auth middleware → COMMITTED (refactor(auth): extract shared middleware)
+   - R-002: Decouple notification service → COMMITTED (refactor(notifications): decouple from core)
+   - R-003: Simplify token flow → COMMITTED (refactor(auth): simplify token refresh)
 
-```
-Phase 0 (Branch) → Phase 1 (Simplified) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit & Merge)
-```
+   Next steps:
+   - Review changes: git log --oneline -5
+   - Run tests: npm test
+   - Push when ready: git push
+   ```
 
-Phase 1 is simplified: skip parallel Agents, use a quick 2-3 question confirmation instead. Skip detailed doc collection. Still generate a lightweight `refactor-analysis.md`.
-
-**CRITERIA** (ALL must be true):
-- Single file change
-- Estimated change < 30 lines
-- Well-known refactoring pattern (rename, extract method/class, inline, move)
-- No cross-module impact
-- No dependency changes
-
-**Fast Path implementation differs from full path:**
-- Phase 1 Steps 1.2-1.3 are skipped (no doc collection, no parallel Agents)
-- Step 1.1 simplified to quick confirmation of refactoring goal
-- Step 1.4 simplified to brief scope confirmation
-- Phase 2 is simplified: generate a lightweight plan.md with 1-2 tasks directly from refactor-analysis.md
-- Phase 3 still reads plan.md Tasks as normal, marks tasks `[x]` on completion
-- Single-task refactors typically have just one task in plan.md
-
-**Fast Path still requires:**
-- Refactor branch (Phase 0)
-- Scope confirmation (Phase 1, simplified)
-- refactor-analysis.md (lightweight version with baseline)
-- plan.md (simplified, 1-2 tasks)
-- Full test suite run after implementation
-- Code review
-- `refactor(<scope>):` commit convention
-- Merge decision
+**CHECKPOINT CP-RW-3**: All refactor items completed or user stopped pipeline.
 
 ---
 
 ## Resume — Interruption Recovery
 
-The pipeline supports resuming from the last completed phase by detecting existing artifacts.
+The workflow supports resuming by detecting existing state:
+
+| State Found | Resume From |
+|-------------|------------|
+| No `refactor-list.json` | Phase 1: Brainstorm |
+| `refactor-list.json` exists, no pipeline state | Phase 3: Launch |
+| `refactor-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
+| All refactors completed | Report completion, suggest next steps |
 
-**Detection logic**: Check `.prizmkit/refactor/<slug>/` and git branch state:
+**Resume**: If `refactor-list.json` exists, ask user: "Existing refactor plan found with N items. Resume pipeline or re-plan?"
 
-| Artifact Found | Resume From |
-|---------------|------------|
-| (nothing) | Phase 0: Branch Setup |
-| On `refactor/<slug>` branch, no artifacts | Phase 1: Understand & Analyze |
-| `refactor-analysis.md` only | Phase 2: Plan |
-| `refactor-analysis.md` + `plan.md` | Phase 3: Implement |
-| All docs + code changes exist | Phase 4: Review |
-| All docs + review passed | Phase 5: Verify & Commit |
+---
+
+## Interaction During Pipeline
+
+While the pipeline runs, the user can continue the conversation:
 
-**Resume**: If `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
+| User says | Action |
+|-----------|--------|
+| "status" / "progress" | Show current progress |
+| "logs" | Show recent log activity |
+| "stop" | Stop the pipeline (state preserved) |
+| "show R-002 logs" | Show specific refactor item's session log |
 
 ---
 
 ## Error Handling
 
-| Scenario | Action |
-|----------|--------|
-| Cannot identify target module | Ask user for clarification |
-| User's refactoring goal is unclear | Use Step 1.1 structured choices to narrow down |
-| No tests exist for target module | WARN user, recommend writing tests first |
-| Baseline tests already failing | Isolate failures, document, proceed with caution |
-| Parallel Agent fails to read a file | Log warning, continue with available results, notify user |
-| Test fails after a refactoring task | Revert task, investigate, retry or split |
-| Implementation fails after 3 rounds | Escalate to user with analysis |
-| Review fails after 2 rounds | Escalate with review findings |
-| Refactoring creates circular dependency | STOP, revise plan |
-| Performance regression detected | STOP, investigate, revise approach |
-| Branch conflict during merge | Show conflict, ask user to resolve or keep branch |
+| Error | Action |
+|-------|--------|
+| User's refactoring goal is too vague | Ask for more context: "Can you describe what's wrong with the current code structure?" |
+| Brainstorming stalls | Offer concrete options: "Would you prefer incremental or comprehensive refactoring?" |
+| No tests exist for target module | WARN user, recommend writing tests first before refactoring |
+| `refactor-planner` cannot parse goals | Refine the goals summary and retry |
+| `refactor-list.json` generation failed | Show error, retry with refined input |
+| Pipeline launch failed | Show daemon log, suggest manual start |
+| All refactor items blocked/failed | Show status, suggest retrying specific items |
+| User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
+| Behavior regression detected during pipeline | Pipeline handles per-item — failed items are retried or reported |
 
 ---
 
 ## Relationship to Other Skills
 
-| Skill | Role in Refactor Workflow |
-|-------|-----------------------------|
-| (parallel Agents) | Phase 1: concurrent code & doc reading |
-| `/prizmkit-plan` | Phase 2: refactoring plan + task generation |
-| `/prizmkit-implement` | Phase 3: execute refactoring tasks |
-| `/prizmkit-code-review` | Phase 4: review quality and behavior preservation |
-| `/prizmkit-committer` | Phase 5: commit with `refactor()` convention |
-| `/prizmkit-retrospective` | Phase 5: structural sync before commit (Job 1 only, skip knowledge injection unless new pitfall) |
-| `feature-workflow` | Handoff target when new behavior is needed |
-| `/prizmkit-plan` | NOT used (no user stories for refactoring) |
-| `/prizmkit-analyze` | NOT used (no spec <-> plan consistency needed) |
+| Skill | Relationship |
+|-------|-------------|
+| `refactor-planner` | **Called by Phase 2** — generates refactor-list.json from clarified goals |
+| `refactor-pipeline-launcher` | **Called by Phase 3** — starts pipeline (handles execution mode selection) |
+| `feature-workflow` | **Alternative** — for new feature development |
+| `bug-fix-workflow` | **Alternative** — for bug fix workflows |
 
 ---
 
-## Comparison with Feature and Bug Fix Pipelines
-
-| Dimension | Feature Workflow | Refactor Workflow | Bug Fix Workflow |
-|-----------|-----------------|-------------------|------------------|
-| Input | Natural language requirement | Module/code target | Bug description |
-| Deep Q&A | Yes (brainstorm) | Yes (structured scoping + parallel analysis) | Yes (diagnosis) |
-| Branch | Pipeline manages per-feature | `refactor/<slug>` | `fix/<BUG_ID>-*` |
-| Pipeline Phases | 4 (brainstorm → plan → launch → monitor) | 6 (branch → understand & analyze → plan → implement → review → commit) | 8 (branch → diagnose → triage → reproduce → fix → review → verify → commit) |
-| Phase 1 | Brainstorm (requirements Q&A) | Understand & Analyze (structured scoping + parallel reading + collaborative planning) | Deep Bug Diagnosis (symptom Q&A) |
-| Artifact Path | `.prizmkit/specs/<slug>/` | `.prizmkit/refactor/<slug>/` | `.prizmkit/bugfix/<id>/` |
-| Commit Prefix | `feat(<scope>):` | `refactor(<scope>):` | `fix(<scope>):` |
-| Test Strategy | TDD per task | Full suite after EVERY task | Reproduction test |
-| Scope Guard | N/A | Enforced | N/A |
-| Behavior Change | Expected | Forbidden | Fix behavior |
-| User Verification | Yes (brainstorm confirmation) | Yes (Phase 5) | Yes (Phase 6) |
+## Comparison with Alternative Workflows
+
+| Dimension | refactor-workflow | feature-workflow | bug-fix-workflow |
+|-----------|-------------------|-----------------|------------------|
+| **Purpose** | Code restructuring (batch) | New features (batch) | Single bug fix (interactive) |
+| **Brainstorming** | Yes — deep interactive Q&A on refactoring goals | Yes — deep interactive Q&A on requirements | No (bug report is input) |
+| **Planning Skill** | `refactor-planner` | `feature-planner` | None (triage built-in) |
+| **Branch** | Pipeline manages per-refactor | Pipeline manages per-feature | `fix/<BUG_ID>-*` |
+| **Execution** | Foreground or background daemon | Foreground or background daemon | In-session, interactive |
+| **Input** | Rough refactoring idea or target | Rough idea or requirements | Bug report / stack trace |
+| **Output** | Multiple `refactor()` commits | Multiple `feat()` commits | Single `fix()` commit |
+| **Behavior Change** | Forbidden (structure only) | Expected (new functionality) | Fix behavior |
+| **Batch alternative** | (this is the batch flow) | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` |
+
+---
 
 ## Output
 
-- `refactor-analysis.md` (Phase 1 artifact)
-- `plan.md` with Tasks section (Phase 2 artifact)
-- Refactored implementation code (Phase 3)
-- Code review report (Phase 4, conversation only)
-- Git commit with `refactor(<scope>):` prefix on dedicated refactor branch (Phase 5)
-- Updated `.prizm-docs/` (if applicable)
+- Structured refactoring goals summary (Phase 1 artifact)
+- `refactor-list.json` (Phase 2 artifact)
+- Pipeline execution (Phase 3)
+- Progress updates (Phase 4)
+- Multiple git commits with `refactor(<scope>):` prefix
+- Updated `.prizm-docs/` (via prizmkit-retrospective per refactor item)