prizmkit 1.1.79 → 1.1.81

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

@@ -26,39 +26,12 @@ User says:
 
 ## Overview
 
-```
-refactor-workflow <target / goals>
-   │
-   ├── Phase 1: Brainstorm → clarify type → collect materials → parallel deep read → discuss plan
-   │
-   ├── Phase 2: Plan → refactor-planner → .prizmkit/plans/refactor-list.json
-   │
-   ├── Phase 3: Launch → refactor-pipeline-launcher → pipeline execution
-   │
-   └── Phase 4: Monitor → track progress → report results
-```
-
-### What This Skill Does
-
-| Phase | Action | Result |
-|-------|--------|--------|
-| 1 | **Brainstorm** — clarify type, collect reference materials, parallel deep read code & docs, discuss plan grounded in real code | Fully clarified refactoring goals |
-| 2 | Call `refactor-planner` with clarified goals | `.prizmkit/plans/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 |
-
-### Why This Skill Exists
-
-Without this skill, users must:
-1. Figure out all refactoring goals and scope themselves
-2. Invoke `refactor-planner` → wait for .prizmkit/plans/refactor-list.json
-3. Invoke `refactor-pipeline-launcher` → wait for pipeline start
-4. Manually check progress
+Four phases take a rough refactoring idea to verified, behavior-preserving code so the user doesn't have to manually chain planner → launcher → monitoring:
 
-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
+1. **Brainstorm** — clarify type, collect reference materials, parallel deep read code & docs, discuss plan grounded in real code → fully clarified refactoring goals
+2. **Plan** — call `refactor-planner` → `.prizmkit/plans/refactor-list.json` with N refactor items
+3. **Launch** — call `refactor-pipeline-launcher` → pipeline started (execution mode chosen by user via launcher)
+4. **Monitor** — track progress → status updates, completion report
 
 ### Branch Management
 
@@ -80,21 +53,9 @@ Natural language description of the refactoring goals. Can be:
 
 Flow: brainstorm → refactor-planner → refactor-pipeline-launcher → monitor
 
-**Mode B: From existing .prizmkit/plans/refactor-list.json**
+**Mode B: From existing `.prizmkit/plans/refactor-list.json`** — user says "run pipeline from existing file", or the file already exists. Skip ahead per the [Resume table](#resume--interruption-recovery).
 
-When user says "run pipeline from existing file" or .prizmkit/plans/refactor-list.json already exists:
-- Skip brainstorm and `refactor-planner` (file already exists)
-- Invoke `refactor-pipeline-launcher` directly
-- Monitor and report progress
-
-**Mode C: Incremental (add to existing refactor plan)**
-
-When user says "add more refactors" or the project already has a .prizmkit/plans/refactor-list.json:
-- Brainstorm new refactoring goals with the user
-- Invoke `refactor-planner` in incremental mode (reads existing .prizmkit/plans/refactor-list.json)
-- Append new refactor items to existing list
-- Invoke `refactor-pipeline-launcher`
-- Monitor and report progress
+**Mode C: Incremental (add to existing refactor plan)** — user says "add more refactors". Brainstorm new goals, then invoke `refactor-planner` in incremental mode (appends to existing list) → launch → monitor.
 
 ---
 
@@ -139,59 +100,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 +115,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.
 
@@ -275,28 +137,6 @@ After confirming refactoring goals, assess whether this refactor needs the full
 - Existing tests fully cover the affected code paths
 - No risk of behavior change
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
-
-```
-AskUserQuestion:
-  question: "This refactoring appears straightforward. How would you like to proceed?"
-  header: "Approach"
-  options:
-    - label: "Refactor now (fast path)"
-      description: "Plan and refactor directly in this session using /prizmkit-plan + /prizmkit-implement"
-    - label: "Add to refactor list (pipeline)"
-      description: "Generate .prizmkit/plans/refactor-list.json via refactor-planner, then launch pipeline for autonomous execution"
-```
-
-- **Refactor now** → Fast Path Workflow:
-  1. Invoke `/prizmkit-plan` with the refactoring goals → generates `spec.md` + `plan.md`
-  2. Invoke `/prizmkit-implement` to execute the plan (behavior preservation verified by tests)
-  3. After implementation, run `/prizmkit-code-review` for quality check
-  4. Commit via `/prizmkit-committer` with `refactor(<scope>):` prefix
-  5. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/`
-  6. **End workflow** — skip Phase 2/3/4
-- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline)
-
 **Complex refactor → Planning Path** (ANY is true):
 - Cross-module impact (>2 modules affected)
 - Public API or interface changes required
@@ -305,21 +145,21 @@ AskUserQuestion:
 - Insufficient test coverage in target area (risk of hidden behavior changes)
 - Requires coordination with other ongoing work
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
+**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment ("This refactoring appears straightforward…" for simple, "This refactoring is complex and will benefit from structured planning…" for complex), but the two options are always the same:
 
 ```
 AskUserQuestion:
-  question: "This refactoring is complex and will benefit from structured planning. How would you like to proceed?"
+  question: <tailored to simple vs complex assessment>
   header: "Approach"
   options:
-    - label: "Plan and refactor now"
-      description: "Create a plan and refactor in this session using /prizmkit-plan + /prizmkit-implement"
+    - label: "Refactor now (fast path)"
+      description: "Plan and refactor directly in this session using /prizmkit-plan + /prizmkit-implement"
     - label: "Add to refactor list (pipeline)"
       description: "Generate .prizmkit/plans/refactor-list.json via refactor-planner, then launch pipeline for autonomous execution"
 ```
 
-- **Plan and refactor now** → Invoke `/prizmkit-plan` with goals → `/prizmkit-implement` → `/prizmkit-code-review` → `/prizmkit-committer` → `/prizmkit-retrospective`. **End workflow** — skip Phase 2/3/4.
-- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline)
+- **Refactor now** → Fast Path: `/prizmkit-plan` (goals → `spec.md` + `plan.md`) → `/prizmkit-implement` (behavior preservation verified by tests) → `/prizmkit-code-review` → `/prizmkit-committer` (`refactor(<scope>):` prefix) → `/prizmkit-retrospective` (sync `.prizmkit/prizm-docs/`). **End workflow** — skip Phase 2/3/4.
+- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline).
 
 **NEVER proceed without explicit user confirmation via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 
@@ -350,7 +190,7 @@ AskUserQuestion:
 
 **CHECKPOINT CP-RW-1**: `.prizmkit/plans/refactor-list.json` generated and validated.
 
-**If user says `--from <file>`**: Skip Phase 1 and Phase 2 entirely.
+**If `.prizmkit/plans/refactor-list.json` already exists or user says `--from <file>`**: skip ahead per the [Resume table](#resume--interruption-recovery).
 
 ---
 

package/bundled/skills/refactor-workflow/references/brainstorm-guide.md

@@ -0,0 +1,116 @@
+# Brainstorm Guide — Refactoring Context
+
+Procedural details for deep code analysis and discussion during refactor-workflow Phase 1.
+
+## 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.
+
+## 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)
+
+## Completion Signs
+
+**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
+
+## Refactoring Goals Summary Template
+
+Once brainstorming is complete, produce a structured goals summary using this template:
+
+```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: ✓
+```