prizmkit 1.1.1 → 1.1.3

package/bundled/skills/refactor-planner/assets/planning-guide.md

@@ -0,0 +1,292 @@
+# Refactor Planning Reference Guide
+
+This guide provides structured patterns, decision matrices, and templates for decomposing refactoring goals into well-scoped, executable items. It is intended as a practical reference for the AI during interactive refactor planning sessions.
+
+---
+
+## 1. Identifying Refactoring Boundaries
+
+Refactoring boundaries define where one refactor item ends and another begins. Good boundaries produce items that are independently executable and independently verifiable.
+
+### Boundary Heuristics
+
+| Signal | Boundary Type | Example |
+|--------|--------------|---------|
+| Different files/modules | Module boundary | "Extract auth logic" vs "Extract validation logic" |
+| Different refactoring operations | Operation boundary | "Rename function" vs "Extract class" |
+| Different risk levels | Risk boundary | "Safe rename" vs "Restructure module internals" |
+| Different test suites affected | Test boundary | "Changes unit tests only" vs "Changes integration tests" |
+| Sequential dependency | Dependency boundary | "Rename X" must complete before "Move X to new module" |
+
+### Rules for Setting Boundaries
+
+1. **One operation type per item.** Don't mix a rename with a structural extraction in the same item.
+2. **One module scope per item** (unless the refactoring specifically targets cross-module concerns like decoupling).
+3. **Each item should be independently testable.** After completing item R-001, all tests should pass before starting R-002.
+4. **If an item requires more than 3 files to change simultaneously**, consider splitting it.
+5. **If behavior preservation requires different strategies for different parts**, split into separate items with appropriate strategies.
+
+---
+
+## 2. Description Writing Guide
+
+Refactor item descriptions are the primary input for autonomous pipeline sessions. A thin description forces the AI to guess about scope and safety constraints.
+
+### Minimum Word Counts
+
+| Complexity | Minimum Words | Warning Threshold |
+|------------|---------------|-------------------|
+| low        | 15            | 30                |
+| medium     | 15            | 50                |
+| high       | 15            | 80                |
+
+Below 15 words is a validation error. Below the threshold triggers a warning.
+
+### What to Include
+
+Every refactor description should cover:
+
+1. **What to change** — specific files, functions, classes, or patterns being refactored
+2. **How to change it** — the refactoring operation (extract, rename, move, inline, simplify)
+3. **Why** — the motivation (reduce complexity, improve testability, remove duplication)
+4. **Constraints** — what must NOT change (public API, behavior contracts, external interfaces)
+5. **Verification** — how to confirm the refactoring succeeded without breaking behavior
+
+### Good vs Bad Examples
+
+**Bad** (12 words — too thin):
+```
+"Extract the validation logic from the handler into a separate module."
+```
+
+**Good** (55 words — implementation-ready):
+```
+"Extract all input validation functions from src/api/handler.js (validateEmail, validatePassword, validateUsername) into a new src/utils/validators.js module. Update all imports in handler.js and any other files that import these functions directly. Preserve the exact function signatures and return types. The handler.js file should import from the new location. All existing tests must continue to pass without modification."
+```
+
+**Bad** (14 words):
+```
+"Convert the user service from callbacks to async/await pattern throughout."
+```
+
+**Good** (72 words — implementation-ready):
+```
+"Convert src/services/user-service.js from callback-based functions to async/await. Target functions: createUser, findUserById, updateUser, deleteUser (4 functions total). Each function currently accepts a callback as the last parameter and calls it with (err, result). Convert to return Promises and use async/await internally. Update all callers in src/routes/user-routes.js to use await instead of passing callbacks. Preserve all error handling behavior — errors that were passed to callbacks should now be thrown."
+```
+
+---
+
+## 3. Common Refactoring Patterns
+
+Use these patterns as starting points when decomposing refactoring goals.
+
+### Pattern A: Extract Method/Function
+
+**When**: A function is too long, has multiple responsibilities, or contains duplicated logic.
+
+```
+R-001: Extract [specific logic] from [source function] into [new function name]
+  Type: extract
+  Scope: [source file]
+  Complexity: low
+  Preservation: test-gate
+```
+
+### Pattern B: Extract Class/Module
+
+**When**: A file/class is too large, a group of functions share a common concern, or a module has multiple responsibilities.
+
+```
+R-001: Create new module [name] with extracted [concern] logic
+  Type: extract
+  Scope: [source file, new file]
+  Complexity: medium
+  Preservation: test-gate
+
+R-002: Update imports to use new [name] module (deps: R-001)
+  Type: restructure
+  Scope: [all importing files]
+  Complexity: low
+  Preservation: test-gate
+```
+
+### Pattern C: Move Module/File
+
+**When**: A file is in the wrong directory, module organization needs restructuring.
+
+```
+R-001: Move [file] from [old path] to [new path]
+  Type: restructure
+  Scope: [file, all importers]
+  Complexity: low-medium (depends on import count)
+  Preservation: test-gate
+```
+
+### Pattern D: Inline (Reverse of Extract)
+
+**When**: An abstraction is unnecessary, a wrapper adds no value, or indirection hurts readability.
+
+```
+R-001: Inline [function/module] into [target]
+  Type: simplify
+  Scope: [source file, target file]
+  Complexity: low
+  Preservation: test-gate
+```
+
+### Pattern E: Rename (Variable, Function, Class, File)
+
+**When**: Names are misleading, inconsistent, or don't follow conventions.
+
+```
+R-001: Rename [old name] to [new name] across codebase
+  Type: rename
+  Scope: [all files containing the name]
+  Complexity: low
+  Preservation: test-gate
+```
+
+### Pattern F: Decouple Dependencies
+
+**When**: Circular dependencies, tight coupling between modules, or difficulty testing in isolation.
+
+```
+R-001: Define interface/contract for [dependency] (deps: none)
+  Type: decouple
+  Scope: [new interface file]
+  Complexity: medium
+  Preservation: test-gate
+
+R-002: Implement [dependency] behind new interface (deps: R-001)
+  Type: decouple
+  Scope: [implementation file]
+  Complexity: medium
+  Preservation: test-gate
+
+R-003: Update consumers to use interface instead of concrete (deps: R-002)
+  Type: decouple
+  Scope: [all consumer files]
+  Complexity: medium
+  Preservation: test-gate
+```
+
+### Pattern G: Architecture Migration
+
+**When**: Converting between paradigms (callbacks to promises, classes to functions, monolith to modules).
+
+```
+R-001: Add new [pattern] alongside old [pattern] (deps: none)
+  Type: migrate
+  Scope: [target files]
+  Complexity: medium-high
+  Preservation: test-gate or snapshot
+
+R-002: Migrate [specific area] to new pattern (deps: R-001)
+  Type: migrate
+  Scope: [area files]
+  Complexity: medium
+  Preservation: test-gate
+
+R-003: Remove old [pattern] code (deps: R-002)
+  Type: simplify
+  Scope: [cleaned files]
+  Complexity: low
+  Preservation: test-gate
+```
+
+---
+
+## 4. Dependency Ordering Rules
+
+Correct ordering minimizes risk and ensures each step is independently verifiable.
+
+### Ordering Priority (execute in this order)
+
+1. **Safe renames** — Lowest risk. Pure name changes with no structural impact. Can be reverted trivially.
+2. **Extract/inline** — Moderate risk. Changes module boundaries but doesn't reorganize architecture.
+3. **Structural changes** — Higher risk. Reorganizes file layout, module hierarchy, or dependency graph.
+4. **Migrations** — Highest risk. Changes programming patterns or paradigms.
+
+### Dependency Rules
+
+1. **No circular dependencies.** Dependencies MUST form a directed acyclic graph (DAG).
+2. **Minimal dependency sets.** Each item should depend only on items it directly needs.
+3. **Rename before restructure.** If you're renaming something AND moving it, rename first (easier to track).
+4. **Create before consume.** If item A creates a new module and item B uses it, B depends on A.
+5. **Interface before implementation.** If decoupling, define the interface before implementing behind it.
+6. **Preserve before remove.** If migrating, ensure new code works before removing old code.
+
+### Validation Checklist
+
+- [ ] No item depends on itself
+- [ ] No circular dependency chains exist
+- [ ] Every item ID referenced in a dependency list is defined in the plan
+- [ ] The graph can be topologically sorted
+- [ ] Renames appear before structural changes that reference the renamed entities
+
+---
+
+## 5. Acceptance Criteria for Refactoring
+
+Refactoring acceptance criteria focus on structural improvement AND behavior preservation. They differ from feature acceptance criteria.
+
+### Standard Criteria Templates
+
+**For extract operations:**
+- [ ] New module/function exists at [target path]
+- [ ] Original location imports from new location (no duplication)
+- [ ] All existing tests pass without modification
+- [ ] No new circular dependencies introduced
+
+**For rename operations:**
+- [ ] Old name does not appear anywhere in codebase (except git history)
+- [ ] All references updated to new name
+- [ ] All existing tests pass without modification
+
+**For restructure operations:**
+- [ ] Files are in their new locations
+- [ ] All import paths updated
+- [ ] Module boundary is clean (no reaching into internal paths)
+- [ ] All existing tests pass without modification
+
+**For decouple operations:**
+- [ ] Interface/contract defined and documented
+- [ ] Implementation satisfies interface
+- [ ] Consumers depend on interface, not implementation
+- [ ] No circular dependencies remain
+- [ ] All existing tests pass without modification
+
+**For migrate operations:**
+- [ ] New pattern is used in target area
+- [ ] Old pattern code is removed (no dead code)
+- [ ] All existing tests pass (may need test updates to use new pattern)
+- [ ] Behavior is identical (verified via test-gate or snapshot)
+
+### Writing Principles
+
+1. **Always include "all existing tests pass"** — this is the fundamental refactoring invariant.
+2. **Be specific about structural outcomes** — "files are organized by feature" is vague; "auth files are in src/features/auth/" is concrete.
+3. **Include negative criteria** — "no circular dependencies", "no dead code", "no duplicated logic".
+4. **Keep count manageable** — 3-5 criteria per item. More than 6 suggests the item should be split.
+
+---
+
+## 6. Complexity Estimation for Refactoring
+
+| Factor | Low | Medium | High |
+|--------|-----|--------|------|
+| File count | 1-2 files | 3-5 files | 6+ files |
+| Cross-module scope | Same module | 2 modules | 3+ modules |
+| Test coverage | High (>80%) | Moderate (40-80%) | Low (<40%) |
+| Pattern familiarity | Well-known (rename, extract) | Common (restructure) | Novel (custom migration) |
+| Dependency changes | None | Minor (1-2 imports) | Significant (module graph changes) |
+
+**Rule**: Take the highest individual factor as the overall complexity. When in doubt, estimate higher.
+
+### Complexity Red Flags (Consider Splitting)
+
+- Item touches more than 5 files
+- Item requires changes to both test files and source files in non-trivial ways
+- Item involves both structural change AND pattern migration
+- Item has more than 6 acceptance criteria
+- Item's description exceeds 100 words (suggests multiple operations combined)

package/bundled/skills/refactor-planner/references/behavior-preservation.md

@@ -0,0 +1,301 @@
+# Behavior Preservation Guide
+
+This guide covers strategies for ensuring that refactoring changes structure without changing behavior. Every refactor item must declare a behavior preservation strategy.
+
+---
+
+## 1. Preservation Strategies
+
+### Strategy: test-gate
+
+**Definition**: Run the full test suite after each refactoring change. All previously-passing tests must continue to pass.
+
+**How it works**:
+1. Run the full test suite before starting the refactor item (establish baseline)
+2. Implement the refactoring change
+3. Run the full test suite again
+4. Compare: all tests that passed before must still pass
+5. If any test fails -> revert the change, investigate, and retry
+
+**When to use**:
+- Target area has good test coverage (>60%)
+- Tests are reliable (no flaky tests in the target area)
+- Test suite runs in reasonable time (<5 minutes for the relevant subset)
+- Tests cover the behavior contracts you need to preserve
+
+**Strengths**:
+- Most reliable automated strategy
+- Catches regressions immediately
+- Well-understood and widely practiced
+- Works with any test framework
+
+**Limitations**:
+- Only as good as test coverage — untested behavior can still break
+- Slow test suites may bottleneck iteration speed
+- Flaky tests create false negatives
+
+**Configuration in refactor-list.json**:
+```json
+{
+  "behavior_preservation": "test-gate",
+  "test_command": "npm test"
+}
+```
+
+---
+
+### Strategy: snapshot
+
+**Definition**: Capture the observable output/state of the target code before and after refactoring, then compare.
+
+**How it works**:
+1. Identify observable outputs of the target code (API responses, rendered UI, log output, file output)
+2. Capture a "before" snapshot by exercising the code with representative inputs
+3. Implement the refactoring change
+4. Capture an "after" snapshot with the same inputs
+5. Compare: snapshots must match (or differ only in acceptable ways like formatting)
+
+**When to use**:
+- Test coverage is insufficient but behavior is observable
+- The code produces deterministic output for given inputs
+- You can identify representative inputs that exercise the key behavior paths
+- API endpoints, CLI tools, data processing pipelines
+
+**Strengths**:
+- Works even when formal tests are missing
+- Captures real behavior rather than test assertions
+- Can detect subtle regressions that tests might miss
+
+**Limitations**:
+- Requires deterministic behavior (non-deterministic outputs need normalization)
+- May miss edge cases if representative inputs are incomplete
+- Snapshot comparison tools may need configuration for acceptable differences
+- More manual setup than test-gate
+
+**Configuration in refactor-list.json**:
+```json
+{
+  "behavior_preservation": "snapshot",
+  "snapshot_targets": ["API responses for /api/users/*", "CLI output for --help flag"]
+}
+```
+
+---
+
+### Strategy: manual
+
+**Definition**: Human verification is required to confirm behavior is preserved. Used as a last resort.
+
+**When to use**:
+- No test coverage AND no easily observable deterministic output
+- UI-heavy changes where visual regression is the primary concern
+- Legacy code with unknown behavior contracts
+- Code that interacts with external services in non-reproducible ways
+
+**How it works**:
+1. Document the current behavior (screenshots, recordings, written descriptions)
+2. Implement the refactoring change
+3. Human manually verifies the behavior matches the documentation
+4. Human signs off on the change
+
+**Strengths**:
+- Works for any situation
+- Humans can assess subjective quality (UI layout, user experience)
+- Can catch issues that automated tools miss
+
+**Limitations**:
+- Slowest strategy — blocks on human availability
+- Error-prone — humans miss regressions, especially subtle ones
+- Not scalable — each item needs separate human attention
+- Not repeatable — different humans may verify differently
+
+**Configuration in refactor-list.json**:
+```json
+{
+  "behavior_preservation": "manual",
+  "verification_notes": "Manually verify login flow works: email login, social login, password reset"
+}
+```
+
+---
+
+## 2. Choosing the Right Strategy
+
+Use this decision tree to select the appropriate strategy for each refactor item:
+
+```
+Does the target area have test coverage >60%?
+├── YES: Are the tests reliable (no flaky tests)?
+│   ├── YES → test-gate
+│   └── NO: Fix flaky tests first, then → test-gate
+│         (or if fixing is out of scope → snapshot)
+└── NO: Does the code produce deterministic, observable output?
+    ├── YES → snapshot
+    └── NO → manual (flag as high-risk)
+```
+
+### Strategy Selection Table
+
+| Test Coverage | Output Observable | Recommended Strategy | Risk Level |
+|--------------|-------------------|---------------------|------------|
+| High (>60%) | Yes | test-gate | Low |
+| High (>60%) | No | test-gate | Low |
+| Medium (30-60%) | Yes | test-gate + snapshot | Medium |
+| Medium (30-60%) | No | test-gate (acknowledge gaps) | Medium |
+| Low (<30%) | Yes | snapshot | Medium-High |
+| Low (<30%) | No | manual | High |
+| None (0%) | Yes | snapshot | High |
+| None (0%) | No | manual | Very High |
+
+### Mixed Strategies
+
+For complex items, you can combine strategies:
+- **test-gate + snapshot**: Run tests AND compare output snapshots. Provides defense in depth.
+- **test-gate + manual**: Run tests AND have a human verify UI/UX aspects.
+- Use the primary strategy in the `behavior_preservation` field and note the secondary in `verification_notes`.
+
+---
+
+## 3. Common Behavior-Breaking Pitfalls
+
+These are patterns that frequently cause unintended behavior changes during refactoring. Check for each one when planning.
+
+### 3.1 Side Effect Ordering
+
+**Pitfall**: Reordering function calls or module initialization can change side effects.
+
+**Example**: Moving `initLogger()` after `loadConfig()` when the logger depends on config.
+
+**Prevention**: Map side effects and their dependencies before restructuring. Document execution order constraints.
+
+### 3.2 Error Handling Changes
+
+**Pitfall**: Extracting code into a new function changes which errors are caught and where.
+
+**Example**: A try/catch block that previously caught errors from inline code no longer catches them when the code is extracted to a separate function with its own error handling.
+
+**Prevention**: Trace error propagation paths before and after. Ensure the same errors reach the same handlers.
+
+### 3.3 Closure and Scope Changes
+
+**Pitfall**: Moving code changes what variables are in scope, especially with closures.
+
+**Example**: Extracting a closure that captures `this` into a standalone function loses the `this` binding.
+
+**Prevention**: Identify all captured variables. Ensure they are passed as parameters or the binding is preserved.
+
+### 3.4 Import Order Side Effects
+
+**Pitfall**: In some languages/frameworks, import order matters (module initialization, polyfills, monkey-patching).
+
+**Example**: Moving an import of a polyfill to a different position causes it to load after the code that needs it.
+
+**Prevention**: Identify imports with side effects. Document order constraints. Test module initialization explicitly.
+
+### 3.5 Default Parameter Changes
+
+**Pitfall**: Extracting a function and adding default parameters changes behavior for callers that relied on the old defaults.
+
+**Example**: Original: `function process(data, format) { format = format || 'json'; ... }` — Refactored: `function process(data, format = 'json') { ... }` — These behave differently for `process(data, '')` (empty string).
+
+**Prevention**: Audit all default value logic. Use identical defaulting behavior in the refactored version.
+
+### 3.6 Async/Await Conversion Gotchas
+
+**Pitfall**: Converting callbacks to async/await can change error propagation, timing, and concurrency.
+
+**Example**: Callback errors that were silently swallowed now throw unhandled promise rejections.
+
+**Prevention**: Map all error paths in the callback version. Ensure async version handles every path. Test with error scenarios.
+
+### 3.7 Type Coercion Changes
+
+**Pitfall**: Moving code between contexts can change implicit type coercion behavior.
+
+**Example**: `==` comparisons that relied on type coercion break when types change due to new module boundaries.
+
+**Prevention**: Prefer strict equality. Audit type assumptions at module boundaries.
+
+### 3.8 Timing and Race Conditions
+
+**Pitfall**: Restructuring async code can change execution timing, revealing or creating race conditions.
+
+**Example**: Splitting a synchronous operation into two async steps creates a window where state is inconsistent.
+
+**Prevention**: Identify shared mutable state. Ensure atomicity is preserved. Test concurrent scenarios.
+
+---
+
+## 4. Test Coverage Assessment
+
+Before refactoring, assess the test coverage of the target area to select the appropriate preservation strategy.
+
+### Quick Coverage Assessment
+
+If a formal coverage tool is available:
+```bash
+# JavaScript (Istanbul/nyc)
+npx nyc --reporter=text -- npm test -- --grep "target-module"
+
+# Python (pytest-cov)
+pytest --cov=target_module --cov-report=term-missing
+
+# Go
+go test -coverprofile=coverage.out ./target-package/...
+```
+
+### Manual Coverage Assessment
+
+When coverage tools aren't available, assess manually:
+
+1. **List all public functions/methods** in the target area
+2. **Search for test files** that import or reference the target
+3. **Check test assertions** — do they test behavior or just structure?
+4. **Identify untested paths** — error handling, edge cases, default behavior
+
+### Coverage-Based Planning Decisions
+
+| Coverage Level | Planning Decision |
+|---------------|-------------------|
+| >80% | Proceed with test-gate. High confidence in behavior preservation. |
+| 60-80% | Proceed with test-gate. Note gaps in refactor item descriptions for the pipeline to be cautious about. |
+| 30-60% | Consider writing additional tests before refactoring (as a prerequisite R-000 item). Or use snapshot strategy for low-coverage areas. |
+| <30% | Strongly recommend writing tests first. If user declines, use snapshot or manual strategy and flag as high risk. |
+| 0% | WARN user explicitly. Recommend writing tests as a prerequisite. If user insists on proceeding, use manual strategy and document all known behaviors. |
+
+### Adding Tests as a Prerequisite Item
+
+When test coverage is insufficient, add a prerequisite refactor item:
+
+```
+Refactor Item R-000:
+  Title: Add test coverage for [target area] before refactoring
+  Type: restructure
+  Scope: [test files]
+  Priority: critical
+  Complexity: medium
+  Behavior Preservation: manual (no existing tests to gate against)
+  Acceptance Criteria:
+    - Test coverage for [target area] reaches >60%
+    - Tests cover: [list key behavior contracts]
+    - All new tests pass
+  Dependencies: none
+```
+
+This item runs first, establishing the test baseline that all subsequent items use for their test-gate strategy.
+
+---
+
+## 5. Behavior Verification Checklist
+
+Before marking a refactor item as complete, verify:
+
+- [ ] All previously-passing tests still pass
+- [ ] No new warnings or deprecation notices in test output
+- [ ] No new lint errors introduced
+- [ ] Public API surface is unchanged (same exports, same function signatures)
+- [ ] Error messages and error codes are unchanged (consumers may depend on these)
+- [ ] Logging output is unchanged (monitoring/alerting may depend on log patterns)
+- [ ] Configuration interface is unchanged (env vars, config files, CLI flags)
+- [ ] Performance characteristics are within acceptable bounds (no regression >10%)
+- [ ] No dead code left behind (unused imports, unreachable functions)