prizmkit 1.1.79 → 1.1.80

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -206,35 +206,8 @@ Detect user intent from their message, then follow the corresponding workflow:
    - xhigh — Extensive reasoning (`PRIZMKIT_EFFORT=xhigh`)
    - max — Maximum reasoning, Claude Code only (`PRIZMKIT_EFFORT=max`)
 
-   **Environment variable mapping** (for translating user responses → env vars):
-
-   | Config choice | Environment variable |
-   |-----------|---------------------|
-   | Verbose: On | `VERBOSE=1` |
-   | Verbose: Off | `VERBOSE=0` |
-   | Max retries: N | `MAX_RETRIES=N` |
-   | Strict behavior: On | `STRICT_BEHAVIOR_CHECK=1` |
-   | Strict behavior: Off | `STRICT_BEHAVIOR_CHECK=0` |
-   | Critic: On | `ENABLE_CRITIC=true` |
-   | Timeout: value | `SESSION_TIMEOUT=<seconds>` |
-   | Stop on failure: On | `STOP_ON_FAILURE=1` |
-   | Deploy: Yes | `ENABLE_DEPLOY=1` |
-   | Effort: value | `PRIZMKIT_EFFORT=<value>` |
-
-   **Advanced environment variables** (not exposed in interactive menu, pass via `--env`):
-
-   | Variable | Default | Purpose |
-   |----------|---------|---------|
-   | `MODEL` | (none) | AI model override (e.g. `claude-opus-4.6`) |
-   | `AUTO_PUSH` | `0` | Auto-push to remote after successful refactor (`1` to enable) |
-   | `DEV_BRANCH` | auto-generated | Custom dev branch name (default: `refactor/pipeline-{run_id}`) |
-   | `HEARTBEAT_INTERVAL` | `30` | Heartbeat log interval in seconds |
-   | `HEARTBEAT_STALE_THRESHOLD` | `600` | Max seconds without heartbeat before marking stale |
-   | `LOG_CLEANUP_ENABLED` | `1` | Run periodic log cleanup (`0` to disable) |
-   | `LOG_RETENTION_DAYS` | `14` | Delete logs older than N days |
-   | `LOG_MAX_TOTAL_MB` | `1024` | Keep total logs under N MB via oldest-first cleanup |
-
-   ⚠️ STOP HERE and wait for user response before continuing to step 7.
+   **Environment variable mapping** and **advanced environment variables** tables — read `${SKILL_DIR}/references/configuration.md` for the full translation tables (10 config→env mappings + 8 advanced variables).
+
 
 7. **Show final command**: After user confirms configuration in step 6, assemble the complete command from execution mode + user-confirmed configuration, and present it to the user.
 
@@ -383,22 +356,7 @@ Notes:
 
 ### Error Handling
 
-| Error | Action |
-|-------|--------|
-| `.prizmkit/plans/refactor-list.json` not found | Tell user to run `refactor-planner` skill first |
-| Circular dependencies in refactor list | Fix dependency graph in `.prizmkit/plans/refactor-list.json` before launching |
-| Test baseline failing | Fix failing tests before starting refactoring -- behavior preservation requires a green baseline |
-| `jq` not installed | Suggest: `brew install jq` |
-| `cbc`/`claude` not in PATH | Check AI CLI installation |
-| Refactor pipeline already running | Show status, ask if user wants to stop and restart |
-| PID file stale (process dead) | `launch-refactor-daemon.sh` auto-cleans, retry start |
-| Launch failed (process died immediately) | Show last 20 lines of log: `tail -20 .prizmkit/state/refactor/pipeline-daemon.log` |
-| Refactor stuck/blocked | Use `reset-refactor.sh <R-XXX> --clean --run` for a fresh retry |
-| All refactors blocked/failed | Show status, suggest recovery: `.prizmkit/dev-pipeline/reset-refactor.sh <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
-| `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
-| `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
-| Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/refactor/deploy/<session_id>/logs/session.log`. Retry manually: `/prizmkit-deploy`. |
-| Permission denied on script | Run `chmod +x .prizmkit/dev-pipeline/launch-refactor-daemon.sh .prizmkit/dev-pipeline/run-refactor.sh` |
+Read `${SKILL_DIR}/references/configuration.md` for the full error handling table (14 entries).
 
 ### Integration Notes
 

package/bundled/skills/refactor-pipeline-launcher/references/configuration.md

@@ -0,0 +1,54 @@
+# Configuration Reference — Refactor Pipeline Launcher
+
+Environment variable mappings for the refactor launcher.
+
+## Environment Variable Mapping
+
+Translating user responses to env vars:
+
+| Config choice | Environment variable |
+|-----------|---------------------|
+| Verbose: On | `VERBOSE=1` |
+| Verbose: Off | `VERBOSE=0` |
+| Max retries: N | `MAX_RETRIES=N` |
+| Strict behavior: On | `STRICT_BEHAVIOR_CHECK=1` |
+| Strict behavior: Off | `STRICT_BEHAVIOR_CHECK=0` |
+| Critic: On | `ENABLE_CRITIC=true` |
+| Timeout: value | `SESSION_TIMEOUT=<seconds>` |
+| Stop on failure: On | `STOP_ON_FAILURE=1` |
+| Deploy: Yes | `ENABLE_DEPLOY=1` |
+| Effort: value | `PRIZMKIT_EFFORT=<value>` |
+
+## Advanced Environment Variables
+
+Not exposed in interactive menu, pass via `--env`:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MODEL` | (none) | AI model override (e.g. `claude-opus-4.6`) |
+| `AUTO_PUSH` | `0` | Auto-push to remote after successful refactor (`1` to enable) |
+| `DEV_BRANCH` | auto-generated | Custom dev branch name (default: `refactor/pipeline-{run_id}`) |
+| `HEARTBEAT_INTERVAL` | `30` | Heartbeat log interval in seconds |
+| `HEARTBEAT_STALE_THRESHOLD` | `600` | Max seconds without heartbeat before marking stale |
+| `LOG_CLEANUP_ENABLED` | `1` | Run periodic log cleanup (`0` to disable) |
+| `LOG_RETENTION_DAYS` | `14` | Delete logs older than N days |
+| `LOG_MAX_TOTAL_MB` | `1024` | Keep total logs under N MB via oldest-first cleanup |
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| `.prizmkit/plans/refactor-list.json` not found | Tell user to run `refactor-planner` skill first |
+| Circular dependencies in refactor list | Fix dependency graph in `.prizmkit/plans/refactor-list.json` before launching |
+| Test baseline failing | Fix failing tests before starting refactoring — behavior preservation requires a green baseline |
+| `jq` not installed | Suggest: `brew install jq` |
+| `cbc`/`claude` not in PATH | Check AI CLI installation |
+| Refactor pipeline already running | Show status, ask if user wants to stop and restart |
+| PID file stale (process dead) | `launch-refactor-daemon.sh` auto-cleans, retry start |
+| Launch failed (process died immediately) | Show last 20 lines of log: `tail -20 .prizmkit/state/refactor/pipeline-daemon.log` |
+| Refactor stuck/blocked | Use `reset-refactor.sh <R-XXX> --clean --run` for a fresh retry |
+| All refactors blocked/failed | Show status, suggest recovery: `.prizmkit/dev-pipeline/reset-refactor.sh <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
+| `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
+| `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
+| Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/refactor/deploy/<session_id>/logs/session.log`. Retry manually: `/prizmkit-deploy`. |
+| Permission denied on script | Run `chmod +x .prizmkit/dev-pipeline/launch-refactor-daemon.sh .prizmkit/dev-pipeline/run-refactor.sh` |

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

@@ -220,13 +220,7 @@ Ask: "Based on this analysis, here's how I'd recommend decomposing the refactori
 
 **Goal**: Split refactoring goals into executable, well-ordered items.
 
-Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and dependency ordering rules.
-
-For each refactoring goal:
-1. Identify atomic refactoring operations
-2. Determine inter-item dependencies (safe renames first, structural changes later)
-3. Assess complexity per item (file count, cross-module scope, test coverage)
-4. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
+Read `${SKILL_DIR}/references/planning-phases.md` for the full Phase 4-6 procedures — item decomposition patterns, per-item confirmation loop, and completeness review checklist.
 
 **CHECKPOINT CP-RP-3**: All items decomposed with dependencies and preservation strategies.
 
@@ -234,29 +228,7 @@ For each refactoring goal:
 
 **Goal**: Present each item to the user for confirmation, modification, or rejection.
 
-For each item, display:
-
-```
-Refactor Item R-001:
-  Title: [title]
-  Type: [extract/rename/restructure/simplify/decouple/migrate]
-  Scope: [files list]
-  Priority: [critical/high/medium/low]
-  Complexity: [low/medium/high]
-  Behavior Preservation: [test-gate/snapshot/manual]
-  Acceptance Criteria:
-    - [criterion 1]
-    - [criterion 2]
-  Dependencies: [none / R-002, R-003]
-  
-  Confirm? (Y/modify/skip)
-```
-
-- **Y**: Accept item as-is
-- **modify**: User provides changes, update item, re-display for confirmation
-- **skip**: Remove item from the list
-
-Continue until all items are confirmed or skipped.
+See `${SKILL_DIR}/references/planning-phases.md` for the display template and confirm/modify/skip loop procedure.
 
 **CHECKPOINT CP-RP-4**: All items confirmed by user.
 
@@ -264,28 +236,7 @@ Continue until all items are confirmed or skipped.
 
 **Goal**: Check the full item set for consistency, gaps, and headless execution readiness.
 
-1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Items should be ordered: safe renames -> extract/inline -> structural changes -> migrations
-2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
-3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
-4. **Cross-module impact**: Do any items affect modules outside the declared scope?
-5. **Headless Execution Readiness**: The refactor pipeline runs each item through an autonomous AI session with NO human interaction. For each item, verify:
-   - **Scope clarity**: Are all affected files explicitly listed? The AI must know exactly where to look.
-   - **Refactoring instructions**: Is the description specific enough to execute without ambiguity?
-     - ❌ "Clean up the utils module" — what exactly should change?
-     - ✅ "Extract validation functions (validateEmail, validatePhone, validateUrl) from src/utils/helpers.ts into src/utils/validation.ts. Update all 12 import sites. Preserve existing function signatures."
-   - **Behavior preservation**: Is it clear what tests to run and what behavior must be preserved?
-   - **Dependency context**: If item depends on earlier refactors, does the description reference what changed?
-
-Present review summary:
-```
-Item       | Deps Valid | Preservation | Gaps           | Status
-R-001      | OK         | test-gate    | -              | Ready
-R-002      | OK         | test-gate    | -              | Ready
-R-003      | OK         | manual       | No test coverage| Needs attention
-R-004      | OK         | snapshot     | -              | Ready
-```
-
-If issues found, discuss with user and resolve before proceeding.
+See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review checklist (DAG validation, preservation check, gap detection, cross-module impact, headless readiness criteria) and review summary table format.
 
 **CHECKPOINT CP-RP-5**: Completeness review passed, all issues resolved.
 
@@ -350,118 +301,27 @@ Set default critic fields for each refactor item. The user can override per-item
 
 ## Fast Path
 
-For simple refactoring with minimal scope:
-
-### Eligibility Criteria (ALL must apply)
-- 1-2 refactor items only
-- Complexity: `low` or `medium` for all items
-- No cross-module impact (all items within same module)
-- Well-known refactoring pattern (rename, extract method/class, inline)
-- Existing test coverage for target area
-
-### Fast Path Workflow
-1. Confirm refactoring scope with user
-2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
-
-   ```
-   AskUserQuestion:
-     question: "This qualifies for fast-path (simple refactoring). How would you like to proceed?"
-     header: "Approach"
-     options:
-       - label: "Fast-path"
-         description: "Skip detailed analysis, draft refactor items directly and add to refactor-list.json"
-       - label: "Full workflow"
-         description: "Use the complete planning workflow with detailed code analysis"
-       - label: "Implement directly"
-         description: "Skip the task list entirely and implement the refactoring right now using /prizmkit-plan + /prizmkit-implement"
-   ```
-
-   - **Fast-path** → Continue with fast-path workflow below
-   - **Full workflow** → Exit fast path, use full workflow from Phase 2
-   - **Implement directly** → Invoke `/prizmkit-plan` directly to create spec + plan, then `/prizmkit-implement` to execute. Do NOT add to `.prizmkit/plans/refactor-list.json`
-   
-   **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
-3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
-4. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
-   ```bash
-   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
-   ```
-5. If valid -> summarize and recommend next step
-6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
-
-### When NOT to Use Fast Path
-- More than 2 refactor items
-- Any item with `high` complexity
-- Cross-module impact
-- Architecture migration patterns (Format C goals)
-- No existing test coverage for target area
-
-### Example Fast Path Session
-```
-User: "Rename the auth middleware function from checkAuth to requireAuth everywhere."
-AI: [Detects simple rename, single module]
-AI: [Qualifies for fast path: 1 item, low complexity, no cross-module impact]
-AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow", "Implement directly"]
-User: [Selects "Fast-path"]
-AI: "Drafting R-001..."
-AI: [Validates immediately]
-AI: "Ready to proceed to dev-pipeline."
-```
+For simple refactoring with minimal scope (1-2 items, low/medium complexity, no cross-module impact, existing test coverage). Read `${SKILL_DIR}/references/fast-path.md` for eligibility criteria, full workflow (including AskUserQuestion format), conditions NOT to use, and an example session.
 
 ## Browser Verification
 
-**Browser verification is a feature-pipeline capability only.** Refactors use `behavior_preservation` strategy instead to ensure no external behavior changes:
-
-- `strategy: test-gate` — Rely on existing test suite. Pipeline runs tests before and after refactoring.
-- `strategy: snapshot` — Compare behavior before/after refactoring using executable snapshots (outputs, API responses, side effects)
-- `strategy: manual` — Require human verification that behavior is preserved
-
-For refactors that modify UI code (e.g., component restructuring), the test-gate or snapshot strategy ensures visual appearance is preserved. You can optionally note browser verification needs in your description or acceptance criteria:
-
-Example:
-```
-Refactor Title: Extract UserProfile component from AccountSettings
-Type: extract
-Strategy: snapshot
-Acceptance Criteria:
-  1. UserProfile component renders identically to inline version (compare snapshots)
-  2. All props are correctly forwarded (unit tests pass)
-  3. No visual regression (screenshot comparison)
-  4. Component is reusable in other views
-```
-
-The refactor pipeline AI will use the snapshot strategy to verify external behavior is preserved during refactoring.
+Browser verification is a feature-pipeline capability only. Refactors use `behavior_preservation` strategy instead. Read `${SKILL_DIR}/references/planning-phases.md` for strategy details and UI refactoring examples.
 
 ---
 
 ## Refactoring-Specific Features
 
 ### Behavior Preservation Check
-Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details.
-
-| Strategy | When to Use |
-|----------|-------------|
-| `test-gate` | Target area has good test coverage. Run full test suite after each change. |
-| `snapshot` | Compare output/state before and after. Used when tests are insufficient but behavior is observable. |
-| `manual` | Human verification required. Last resort when neither tests nor snapshots are feasible. |
 
-Flag items using `manual` strategy prominently — they carry the highest risk of behavior regression.
+Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details. See `${SKILL_DIR}/references/planning-phases.md` for the strategy selection table and manual-strategy flagging rules.
 
 ### Dependency Ordering
-Auto-detect inter-item dependencies and enforce safe ordering:
-1. **Safe renames** first (lowest risk, no structural change)
-2. **Extract/inline** operations (moderate risk, changes module boundaries)
-3. **Structural changes** (higher risk, reorganizes architecture)
-4. **Migrations** last (highest risk, changes patterns/paradigms)
+
+Auto-detect inter-item dependencies and enforce safe ordering. Read `${SKILL_DIR}/references/planning-phases.md` for the full dependency ordering rules (safe renames -> extract/inline -> structural -> migrations).
 
 ### Complexity Assessment
-Assess each item's complexity based on:
-- **File count**: 1-2 files = low, 3-5 files = medium, 6+ files = high
-- **Cross-module scope**: same module = low, 2 modules = medium, 3+ modules = high
-- **Test coverage**: high coverage = reduces complexity, low coverage = increases complexity
-- **Pattern familiarity**: well-known pattern = low, novel restructuring = high
 
-Take the highest of these individual assessments as the item's complexity.
+Assess each item's complexity based on file count, cross-module scope, test coverage, and pattern familiarity. Read `${SKILL_DIR}/references/planning-phases.md` for the full complexity assessment criteria and scoring rules.
 
 ## Next-Step Execution Policy (after planning)
 

package/bundled/skills/refactor-planner/references/fast-path.md

@@ -0,0 +1,59 @@
+# Fast Path — Refactor Planner
+
+For simple refactoring with minimal scope.
+
+## Eligibility Criteria (ALL must apply)
+- 1-2 refactor items only
+- Complexity: `low` or `medium` for all items
+- No cross-module impact (all items within same module)
+- Well-known refactoring pattern (rename, extract method/class, inline)
+- Existing test coverage for target area
+
+## Fast Path Workflow
+1. Confirm refactoring scope with user
+2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
+
+   ```
+   AskUserQuestion:
+     question: "This qualifies for fast-path (simple refactoring). How would you like to proceed?"
+     header: "Approach"
+     options:
+       - label: "Fast-path"
+         description: "Skip detailed analysis, draft refactor items directly and add to refactor-list.json"
+       - label: "Full workflow"
+         description: "Use the complete planning workflow with detailed code analysis"
+       - label: "Implement directly"
+         description: "Skip the task list entirely and implement the refactoring right now using /prizmkit-plan + /prizmkit-implement"
+   ```
+
+   - **Fast-path** → Continue with fast-path workflow below
+   - **Full workflow** → Exit fast path, use full workflow from Phase 2
+   - **Implement directly** → Invoke `/prizmkit-plan` directly to create spec + plan, then `/prizmkit-implement` to execute. Do NOT add to `.prizmkit/plans/refactor-list.json`
+
+   **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
+3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
+4. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
+   ```
+5. If valid -> summarize and recommend next step
+6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
+
+## When NOT to Use Fast Path
+- More than 2 refactor items
+- Any item with `high` complexity
+- Cross-module impact
+- Architecture migration patterns (Format C goals)
+- No existing test coverage for target area
+
+## Example Fast Path Session
+```
+User: "Rename the auth middleware function from checkAuth to requireAuth everywhere."
+AI: [Detects simple rename, single module]
+AI: [Qualifies for fast path: 1 item, low complexity, no cross-module impact]
+AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow", "Implement directly"]
+User: [Selects "Fast-path"]
+AI: "Drafting R-001..."
+AI: [Validates immediately]
+AI: "Ready to proceed to dev-pipeline."
+```

package/bundled/skills/refactor-planner/references/planning-phases.md

@@ -0,0 +1,135 @@
+# Planning Phases — Refactor Planner
+
+Detailed procedures for Phases 4-6 of the refactor-planner interactive workflow, plus refactoring-specific assessment rules and browser verification guidance.
+
+---
+
+## Phase 4: Item Decomposition Procedure
+
+Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and dependency ordering rules.
+
+For each refactoring goal:
+1. Identify atomic refactoring operations
+2. Determine inter-item dependencies (safe renames first, structural changes later)
+3. Assess complexity per item (file count, cross-module scope, test coverage)
+4. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
+
+---
+
+## Phase 5: Per-Item Confirmation Loop
+
+For each item, display:
+
+```
+Refactor Item R-001:
+  Title: [title]
+  Type: [extract/rename/restructure/simplify/decouple/migrate]
+  Scope: [files list]
+  Priority: [critical/high/medium/low]
+  Complexity: [low/medium/high]
+  Behavior Preservation: [test-gate/snapshot/manual]
+  Acceptance Criteria:
+    - [criterion 1]
+    - [criterion 2]
+  Dependencies: [none / R-002, R-003]
+  
+  Confirm? (Y/modify/skip)
+```
+
+- **Y**: Accept item as-is
+- **modify**: User provides changes, update item, re-display for confirmation
+- **skip**: Remove item from the list
+
+Continue until all items are confirmed or skipped.
+
+---
+
+## Phase 6: Completeness Review Checklist
+
+1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Items should be ordered: safe renames -> extract/inline -> structural changes -> migrations
+2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
+3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
+4. **Cross-module impact**: Do any items affect modules outside the declared scope?
+5. **Headless Execution Readiness**: The refactor pipeline runs each item through an autonomous AI session with NO human interaction. For each item, verify:
+   - **Scope clarity**: Are all affected files explicitly listed? The AI must know exactly where to look.
+   - **Refactoring instructions**: Is the description specific enough to execute without ambiguity?
+     - ❌ "Clean up the utils module" — what exactly should change?
+     - ✅ "Extract validation functions (validateEmail, validatePhone, validateUrl) from src/utils/helpers.ts into src/utils/validation.ts. Update all 12 import sites. Preserve existing function signatures."
+   - **Behavior preservation**: Is it clear what tests to run and what behavior must be preserved?
+   - **Dependency context**: If item depends on earlier refactors, does the description reference what changed?
+
+### Review Summary Table Format
+
+Present review summary:
+
+```
+Item       | Deps Valid | Preservation | Gaps           | Status
+R-001      | OK         | test-gate    | -              | Ready
+R-002      | OK         | test-gate    | -              | Ready
+R-003      | OK         | manual       | No test coverage| Needs attention
+R-004      | OK         | snapshot     | -              | Ready
+```
+
+If issues found, discuss with user and resolve before proceeding.
+
+---
+
+## Behavior Preservation Check
+
+Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details.
+
+| Strategy | When to Use |
+|----------|-------------|
+| `test-gate` | Target area has good test coverage. Run full test suite after each change. |
+| `snapshot` | Compare output/state before and after. Used when tests are insufficient but behavior is observable. |
+| `manual` | Human verification required. Last resort when neither tests nor snapshots are feasible. |
+
+Flag items using `manual` strategy prominently — they carry the highest risk of behavior regression.
+
+---
+
+## Dependency Ordering
+
+Auto-detect inter-item dependencies and enforce safe ordering:
+1. **Safe renames** first (lowest risk, no structural change)
+2. **Extract/inline** operations (moderate risk, changes module boundaries)
+3. **Structural changes** (higher risk, reorganizes architecture)
+4. **Migrations** last (highest risk, changes patterns/paradigms)
+
+---
+
+## Complexity Assessment
+
+Assess each item's complexity based on:
+- **File count**: 1-2 files = low, 3-5 files = medium, 6+ files = high
+- **Cross-module scope**: same module = low, 2 modules = medium, 3+ modules = high
+- **Test coverage**: high coverage = reduces complexity, low coverage = increases complexity
+- **Pattern familiarity**: well-known pattern = low, novel restructuring = high
+
+Take the highest of these individual assessments as the item's complexity.
+
+---
+
+## Browser Verification
+
+**Browser verification is a feature-pipeline capability only.** Refactors use `behavior_preservation` strategy instead to ensure no external behavior changes:
+
+- `strategy: test-gate` — Rely on existing test suite. Pipeline runs tests before and after refactoring.
+- `strategy: snapshot` — Compare behavior before/after refactoring using executable snapshots (outputs, API responses, side effects)
+- `strategy: manual` — Require human verification that behavior is preserved
+
+For refactors that modify UI code (e.g., component restructuring), the test-gate or snapshot strategy ensures visual appearance is preserved. You can optionally note browser verification needs in your description or acceptance criteria:
+
+Example:
+```
+Refactor Title: Extract UserProfile component from AccountSettings
+Type: extract
+Strategy: snapshot
+Acceptance Criteria:
+  1. UserProfile component renders identically to inline version (compare snapshots)
+  2. All props are correctly forwarded (unit tests pass)
+  3. No visual regression (screenshot comparison)
+  4. Component is reusable in other views
+```
+
+The refactor pipeline AI will use the snapshot strategy to verify external behavior is preserved during refactoring.

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

@@ -139,59 +139,11 @@ Record everything the user provides — these become inputs for Step 1.3.
 
 ### Step 1.3: Parallel Deep Reading
 
-**Goal**: Build comprehensive understanding of the target code and context before discussing plans. Spawn multiple agents in parallel to read all relevant materials simultaneously.
-
-**Parallel reading tasks** (launch concurrently):
-
-| Agent | What to read | Purpose |
-|-------|-------------|---------|
-| Agent A | User-provided code paths — read full source files | Understand current structure, interfaces, dependencies |
-| Agent B | User-provided documents — design docs, proposals, wiki pages | Understand intended direction and constraints |
-| Agent C | `.prizmkit/prizm-docs/` for affected modules — L1/L2 docs, TRAPS, RULES | Understand existing architecture knowledge and known pitfalls |
-| Agent D | Test files for the target area — find and read existing tests | Understand current test coverage and behavior contracts |
-
-**Also gather** (can be included in any agent's task):
-- `.prizmkit/config.json` → tech stack preferences
-- Directory structure of the target area
-- Dependency relationships (imports/exports between target and other modules)
-
-**After all agents complete**: Synthesize findings into a coherent understanding before proceeding to discussion.
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Step 1.3 for the parallel agent dispatch procedure — spawn 4 agents (A: code paths, B: documents, C: prizm-docs, D: test files) to build comprehensive understanding before discussion. Synthesize findings before proceeding.
 
 ### Step 1.4: Discuss Refactoring Plan
 
-**Now** — with deep knowledge of the actual code and documents — discuss the refactoring plan with the user. This discussion is grounded in real code, not abstract questions.
-
-Present what you learned from the parallel reading:
-- Current code structure and its problems (with specific file/function references)
-- Existing test coverage status (which areas are safe, which are risky)
-- Known TRAPS and pitfalls from `.prizmkit/prizm-docs/`
-- Dependencies and potential impact on other modules
-
-Then ask targeted questions based on what you read. **Adapt question depth to the refactoring complexity** — a simple extract-method refactor needs fewer questions than a full module decomposition.
-
-**Code Structure:**
-- "I see the current structure does X — is the target state Y, or something different?"
-- What's the target state? What should the code look like after refactoring?
-- Are there specific code smells you've noticed? (duplication, deep nesting, god classes, tight coupling)
-
-**Scope:**
-- Based on the code I read, these modules are affected: [list]. Anything else in/out of scope?
-- For incremental refactoring: what's the order of priority?
-
-**Behavior Preservation:**
-- "These public APIs/interfaces exist: [list]. Which must remain unchanged?"
-- "I found these tests: [list]. Are they passing currently?"
-- Any undocumented behavior that callers depend on?
-
-**Risk Assessment:**
-- "I found these TRAPS in .prizmkit/prizm-docs/: [list]. Any other known gotchas?"
-- Does this code have external consumers (other teams, published APIs)?
-- Any concurrent development happening in the target area?
-
-**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)
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Step 1.4 for the full discussion framework — code structure, scope, behavior preservation, risk assessment, and constraints. Present what was learned from parallel reading, then ask targeted questions grounded in real code. **Adapt question depth to the refactoring complexity.**
 
 ### Step 1.5: Confirm and Supplement
 
@@ -202,62 +154,11 @@ After the discussion:
 3. **Identify gaps** — if any areas are still unclear, list them explicitly and ask follow-up questions
 4. **Repeat** until the user confirms: "That covers everything" or "Let's proceed"
 
-**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
-
-**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
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Completion Signs for the full checklist of when brainstorming is complete vs when more questions are needed.
 
 ### Step 1.6: Requirements Summary
 
-Once brainstorming is complete, produce a structured goals summary:
-
-```markdown
-## Refactoring Goals Summary
-
-### Target: [Module/area name]
-
-### Refactoring Type: [Incremental / Comprehensive / Targeted]
-
-### Refactoring Objectives
-- [Bullet list of what structural changes are needed and why]
-
-### Current Problems
-- [What's wrong with the current structure — with specific code references]
-
-### Target State
-- [What the code should look like after refactoring]
-
-### Scope
-- **In scope**: [files, modules, directories]
-- **Out of scope**: [explicitly excluded areas]
-
-### Behavior Preservation Contracts
-- [What behavior must remain unchanged]
-- [Key APIs/interfaces that must be preserved]
-- [Existing test coverage status]
-
-### Risk Assessment
-- [Risk]: [Mitigation strategy]
-
-### Reference Materials Reviewed
-- [List of code paths, documents, .prizmkit/prizm-docs/ files that were read]
-
-### Constraints
-- [Timeline, coordination, deployment concerns]
-
-### Confirmed by user: ✓
-```
-
-Present this summary to the user and get explicit confirmation before proceeding.
+Once brainstorming is complete, produce a structured goals summary. Read `${SKILL_DIR}/references/brainstorm-guide.md` §Refactoring Goals Summary Template for the structured output format. Present the summary to the user and get explicit confirmation before proceeding.
 
 **CHECKPOINT CP-RW-0**: Refactoring goals fully clarified and confirmed by user.