prizmkit 1.1.1 → 1.1.3

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

@@ -0,0 +1,436 @@
+---
+name: "refactor-planner"
+description: "Interactive refactoring planner. Understands refactoring intent through dialogue, analyzes current code structure, produces validated refactor-list.json for dev-pipeline execution. Use whenever users discuss refactoring planning, code restructuring scope, or preparing refactor-list.json."
+---
+
+# refactor planner
+
+Plan executable refactoring items for dev-pipeline:
+- **Scope Assessment**: analyze current code structure and identify refactoring targets
+- **Item Decomposition**: break refactoring goals into well-ordered, behavior-preserving items
+
+Always produce a validated `refactor-list.json` that conforms to `dev-pipeline-refactor-list-v1`.
+
+## Invocation Commitment (Hard Rule)
+
+**When the user invokes `/refactor-planner`, you MUST execute the refactor-planner workflow.** You must NEVER:
+- Decide on the user's behalf that the task "doesn't need refactor-planner"
+- Skip refactor-planner to jump directly to refactor-workflow or any other skill
+- Bypass the interactive phases because you judge the task to be "simple" or "obvious"
+
+If you believe the task is better suited for a different workflow (e.g., single-file refactor via `/refactor-workflow`), you MUST:
+1. **Explain why** you think a different path is more appropriate
+2. **Ask the user explicitly** whether they want to switch or continue with refactor-planner
+3. **Only switch if the user confirms** — otherwise proceed with refactor-planner as invoked
+
+The user chose this skill intentionally. Respect that choice.
+
+## Scope Boundary (Hard Rule)
+
+**This skill is PLANNING ONLY.** You must NEVER:
+- Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
+- Execute refactoring operations (rename, move, extract, etc.)
+- Run build/install/test commands
+- Execute any implementation action beyond writing `refactor-list.json`
+
+**Your ONLY writable outputs are:**
+1. `refactor-list.json` (project root)
+2. Draft backups in `.prizmkit/planning/`
+
+**After planning is complete**, you MUST:
+1. Present the summary and recommended next step
+2. **Ask the user explicitly** whether they want to proceed to execution
+3. If the user agrees -> recommend invoking `refactor-pipeline-launcher` or running `run-refactor.sh` (do NOT execute it yourself)
+4. If the user wants to adjust -> continue refining `refactor-list.json`
+5. **NEVER auto-execute** the pipeline, launcher, or any implementation step
+
+## When to Use
+
+Trigger this skill for requests like:
+- "Plan refactoring", "Scope a restructuring"
+- "Prepare refactor-list.json", "Prepare dev-pipeline input for refactoring"
+- "Assess code for refactoring", "Identify refactoring targets"
+- "Plan a code migration", "Decompose a large refactor"
+
+Do NOT use this skill when the user wants to:
+- Execute a single refactor directly (use `refactor-workflow`)
+- Plan new features (use `feature-planner`)
+- Fix bugs (use `bug-planner`)
+
+## Resource Loading Rules (Mandatory)
+
+1. **Read decomposition guide**:
+   - Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and description guidelines
+
+2. **Read scope assessment reference**:
+   - Read `${SKILL_DIR}/references/refactor-scoping-guide.md` for scope classification and risk assessment
+
+3. **Read behavior preservation reference**:
+   - Read `${SKILL_DIR}/references/behavior-preservation.md` for preservation strategy selection
+
+4. **Load on-demand references when triggered**:
+   - Validation errors or interrupted session -> read error recovery patterns (similar to feature-planner)
+
+5. **Always validate output via script**:
+   - Run:
+     ```bash
+     python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input <output-path>
+     ```
+
+6. **Use script output as source of truth**:
+   - If validation fails, **MUST** fix and re-run until pass
+
+## Prerequisites
+
+Before questions, check optional context files (never block if absent):
+- `.prizm-docs/root.prizm` (architecture/project context)
+- `.prizmkit/config.json` (existing stack preferences and detected tech stack)
+- Existing test suite (critical for behavior preservation assessment)
+- Existing `refactor-list.json` (if appending additional items)
+- If `.prizm-docs/root.prizm` is absent and the project has existing source code, scan the 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'
+  ```
+
+**Test suite detection:**
+- Scan for test runner config files (`jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`, `karma.conf.*`)
+- If no test suite detected, WARN: "No test suite found. Behavior preservation will rely on manual verification. Consider writing tests before refactoring."
+- Record test suite status in planning context for downstream use
+
+## Operation Modes
+
+### Mode A: Interactive (default)
+Full Q&A -> code analysis -> item generation. Used when starting from scratch or exploring refactoring scope.
+
+### Mode B: From Analysis
+When an existing analysis report (e.g., `refactor-analysis.md`) is available, skip the analysis phase and proceed directly to item decomposition.
+
+### Mode C: Validate
+Validate an existing `refactor-list.json` without regenerating it:
+```bash
+python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input refactor-list.json
+```
+
+### Mode D: Summary
+Display a human-readable summary of an existing `refactor-list.json`:
+- Item count, dependency graph, complexity distribution, behavior preservation strategies
+
+## Interactive Mode — Core Workflow
+
+Execute the planning workflow in conversation mode with mandatory checkpoints:
+
+### Phase 1: Project Context
+
+**Goal**: Understand the current codebase structure and tech stack.
+
+1. Read `.prizm-docs/root.prizm` and relevant L1 docs
+2. Read `.prizmkit/config.json` for tech stack info
+3. Identify existing test suite and coverage
+4. Summarize project context to the user: "Here's what I found about your project..."
+
+**CHECKPOINT CP-RP-0**: Project context loaded, tech stack and test suite status known.
+
+### Phase 2: Refactor Goal Collection
+
+**Goal**: Through interactive dialogue, understand what the user wants to refactor and why.
+
+Support 4 input formats (users may mix formats):
+
+**Format A — Natural language**:
+> "This module is too large and hard to maintain"
+> "The auth logic is scattered across too many files"
+
+**Format B — Code smell pointer**:
+> "src/api/handler.js is 800 lines"
+> "There are 5 files that all implement similar validation logic"
+
+**Format C — Architecture migration**:
+> "Convert callbacks to async/await"
+> "Migrate from class components to hooks"
+> "Move from monolith to modular architecture"
+
+**Format D — Dependency decoupling**:
+> "There's a circular dependency between auth and user modules"
+> "The database layer is tightly coupled to the HTTP layer"
+
+For each input, ask clarifying questions:
+- What is the specific target (files, modules, patterns)?
+- What is the desired end state?
+- Are there constraints (must preserve API, must not touch certain files)?
+- What is the motivation (maintainability, performance, testability)?
+
+Continue collecting goals until the user says they're done. There is no limit on rounds.
+
+**CHECKPOINT CP-RP-1**: All refactoring goals collected and understood.
+
+### Phase 3: Code Analysis
+
+**Goal**: Analyze the target code to inform item decomposition.
+
+Dispatch **parallel Agent reads** of target files:
+- **Agent A (Structure)**: File inventory, dependency graph, module boundaries, public API surface
+- **Agent B (Quality)**: Code smells, complexity hotspots, duplication, coupling metrics
+- **Agent C (Tests)**: Test coverage of target areas, existing test patterns, behavior contracts
+
+Present consolidated findings:
+```
+## Code Analysis Results
+
+### Structure
+- [file inventory, dependency graph]
+
+### Quality Issues
+- [code smells, complexity hotspots, duplication]
+
+### Test Coverage
+- [test status for target areas]
+- [behavior contracts that must be preserved]
+
+### Recommended Decomposition
+- [suggested refactoring order based on findings]
+```
+
+Ask: "Based on this analysis, here's how I'd recommend decomposing the refactoring. Does this align with your expectations?"
+
+**CHECKPOINT CP-RP-2**: Code analysis complete, user agrees with recommended approach.
+
+### Phase 4: Item Decomposition
+
+**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`)
+
+**CHECKPOINT CP-RP-3**: All items decomposed with dependencies and preservation strategies.
+
+### Phase 5: Per-Item Confirmation
+
+**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.
+
+**CHECKPOINT CP-RP-4**: All items confirmed by user.
+
+### Phase 6: Completeness Review
+
+**Goal**: Check the full item set for consistency and gaps.
+
+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?
+
+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.
+
+**CHECKPOINT CP-RP-5**: Completeness review passed, all issues resolved.
+
+### Phase 7: Generate & Validate
+
+**Goal**: Produce `refactor-list.json` and validate it.
+
+1. Generate `refactor-list.json` at project root
+2. Run validation:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input refactor-list.json
+   ```
+3. If validation fails -> fix issues and re-validate (max 3 attempts)
+4. If validation passes -> present final summary
+
+**CHECKPOINT CP-RP-6**: `refactor-list.json` generated and validated.
+
+## Checkpoints (Mandatory Gates)
+
+| Checkpoint | Artifact/State | Criteria | Phase |
+|-----------|----------------|----------|-------|
+| **CP-RP-0** | Project Context | Tech stack, test suite status, .prizm-docs loaded | 1 |
+| **CP-RP-1** | Goals Collected | All refactoring goals understood, no open ambiguities | 2 |
+| **CP-RP-2** | Code Analyzed | Analysis complete, user agrees with approach | 3 |
+| **CP-RP-3** | Items Decomposed | All items have deps, complexity, preservation strategy | 4 |
+| **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
+| **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
+| **CP-RP-6** | Output Valid | `refactor-list.json` passes validation script | 7 |
+
+**Resume Detection**: If existing artifacts found (partial `refactor-list.json`, draft in `.prizmkit/planning/`), offer to resume from the appropriate checkpoint.
+
+## Output Rules
+
+`refactor-list.json` must satisfy:
+- `$schema` = `dev-pipeline-refactor-list-v1`
+- Non-empty `refactors` array
+- Sequential IDs: `R-001`, `R-002`, ...
+- Valid dependency DAG (no cycles)
+- Each item has a declared `behavior_preservation` strategy: `test-gate`, `snapshot`, or `manual`
+- `priority` must be a string: `"critical"`, `"high"`, `"medium"`, or `"low"`
+- New items default `status: "pending"`
+- English titles for stable slug generation
+- `type` field must be one of: `extract`, `rename`, `restructure`, `simplify`, `decouple`, `migrate`
+- Descriptions minimum 15 words (error). Recommended: 30/50/80 words for low/medium/high complexity (warning).
+- `model` field is optional — omitting it means the pipeline uses $MODEL env or CLI default
+- `scope` array lists target file/directory paths
+
+## 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)** — Tell the user: "This qualifies for fast-path (simple refactoring). Skip detailed analysis and draft directly? Or use full workflow?" Only proceed if user confirms.
+3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
+4. Run validation script immediately
+5. If valid -> summarize and recommend next step
+6. If invalid -> apply fixes, re-validate (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: "This qualifies for fast-path. Skip detailed analysis and draft directly? Or use full workflow?"
+User: "Fast path."
+AI: "Drafting R-001..."
+AI: [Validates immediately]
+AI: "Ready to proceed to dev-pipeline."
+```
+
+## 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.
+
+### 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.
+
+## Next-Step Execution Policy (after planning)
+
+Recommend these three options in this strict order:
+
+1. **Preferred**: invoke `refactor-pipeline-launcher` skill (natural-language handoff)
+2. **Fallback A**: run daemon wrapper
+   ```bash
+   ./dev-pipeline/launch-refactor-daemon.sh start refactor-list.json
+   ./dev-pipeline/launch-refactor-daemon.sh status
+   ```
+3. **Fallback B**: run direct foreground script
+   ```bash
+   ./dev-pipeline/run-refactor.sh run
+   ./dev-pipeline/run-refactor.sh status
+   ```
+
+When launcher is available, do not prioritize raw scripts.
+
+## Error Recovery & Resume
+
+Key behaviors:
+- Warnings only -> proceed with user approval
+- Critical errors -> group by type, auto-fix where possible, max 3 total attempts
+- Interrupted session -> detect checkpoint from existing artifacts, offer resume or restart
+- `refactor-list.json` MUST be written to project root (same level as `package.json` / `.git`)
+
+### Resume Detection
+
+| Artifact Found | Resume From |
+|---------------|------------|
+| Nothing | Phase 1: Project Context |
+| Draft in `.prizmkit/planning/` | Phase matching draft state |
+| Partial `refactor-list.json` | Phase 6: Completeness Review |
+| Valid `refactor-list.json` | Mode D: Summary |
+
+## Session Exit Gate
+
+Prevent accidental session exit without deliverable completion.
+
+### Trigger Conditions
+Activate exit gate when ALL are true:
+- User invoked `/refactor-planner` (not just mentioned refactoring)
+- Current phase < Phase 7 (validation not yet passed)
+- No valid `refactor-list.json` has been written in this session
+
+### Gate Behavior
+When the session appears to be ending:
+1. **Remind**: "You set out to produce `refactor-list.json` but we haven't completed it yet."
+2. **Offer 3 options**:
+   - **(a) Continue to completion** — resume from current phase
+   - **(b) Save draft & exit** — write current progress as draft, exit session
+   - **(c) Abandon** — exit without saving
+3. **If (b)**: Write draft and remind: "This is a draft, not validated. Run `/refactor-planner` again to resume."
+4. **If (c)**: Accept without further prompting.
+
+## Handoff Message Template
+
+After successful validation, report:
+1. Output file path
+2. Total refactor items
+3. Dependency ordering highlights (which items must run first)
+4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
+5. Recommended next action: `refactor-pipeline-launcher`