prizmkit 1.0.121 → 1.0.123

package/bundled/skills/prizmkit-retrospective/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-retrospective"
-description: "Incremental .prizm-docs/ maintainer + deploy guide generator. Performs three jobs: (1) structural sync — update .prizm-docs/ KEY_FILES/INTERFACES/DEPENDENCIES, (2) architecture knowledge — inject TRAPS/RULES/DECISIONS into .prizm-docs/, (3) deploy guide — detect new frameworks/tools and record setup instructions to deploy_guide.md. All project knowledge lives in .prizm-docs/ . Run after code review passes and before committing. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
+description: "Incremental .prizm-docs/ maintainer. Performs two jobs: (1) structural sync — update .prizm-docs/ KEY_FILES/INTERFACES/DEPENDENCIES, (2) architecture knowledge — inject TRAPS/RULES/DECISIONS into .prizm-docs/. All project knowledge lives in .prizm-docs/ . Run after code review passes and before committing. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
 ---
 
 # PrizmKit Retrospective
@@ -11,11 +11,10 @@ All project knowledge is maintained in a single store:
 |-------|----------|---------|---------|
 | **Architecture Index** | `.prizm-docs/` | MODULE, FILES, INTERFACES, DEPENDENCIES, TRAPS, RULES, DECISIONS | AI quickly locates code structure, interfaces, known pitfalls, and key design decisions |
 
-**This skill performs three jobs in one pass:**
+**This skill performs two jobs in one pass:**
 
 1. **Structural Sync** — reflect what changed in code → `.prizm-docs/` (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
 2. **Architecture Knowledge** — inject TRAPS, RULES, and DECISIONS → `.prizm-docs/`. All knowledge is consolidated in `.prizm-docs/`.
-3. **Deploy Guide** — detect new frameworks/tools and record setup instructions → `deploy_guide.md`
 
 No other skill writes to `.prizm-docs/`. This is the sole writer during ongoing development. For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` instead.
 
@@ -151,132 +150,6 @@ When writing TRAPS:
 
 ---
 
-## Job 3: Deploy Guide Maintenance (`deploy_guide.md`)
-
-When new frameworks or tools that require **manual setup steps** are introduced, record them in `deploy_guide.md` at the project root. This ensures installation, configuration, and deployment knowledge is systematically documented for the team.
-
-### When to Run Job 3
-
-Run this job **only when new frameworks/tools are detected** in the current changeset. Skip entirely if no new framework was introduced.
-
-### Step 3-1: Detect New Frameworks
-
-From the `git diff --cached` (or `git diff`) output already collected in Job 1, check for newly added entries in dependency manifest files:
-
-```bash
-# Check for newly added dependencies in common manifest files
-git diff --cached -U0 -- package.json requirements*.txt Pipfile pyproject.toml go.mod Cargo.toml pom.xml build.gradle Gemfile composer.json docker-compose*.yml Dockerfile .tool-versions 2>/dev/null | grep '^\+' | grep -v '^\+\+\+' | head -30
-```
-
-**Trigger conditions** (ANY match → proceed to Step 3-2):
-- New dependency added to `package.json` (dependencies/devDependencies)
-- New package in `requirements.txt`, `pyproject.toml`, `Pipfile`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `Gemfile`, `composer.json`
-- New service in `docker-compose*.yml` (e.g., database, cache, message queue)
-- New `Dockerfile` created or base image changed
-- New system tool in `.tool-versions`, `.nvmrc`, `.python-version`
-- New CI/CD configuration file added (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`)
-
-**Filter out** (do NOT record):
-- Patch version bumps of existing dependencies (e.g., `1.2.3` → `1.2.4`)
-- Dev-only tools that need no manual setup (linters, formatters, type checkers)
-- Transitive dependencies (lock file changes without manifest changes)
-
-### Step 3-2: Record Framework Info
-
-For each detected new framework/tool, gather the following information from the code changes and dependency files:
-
-| Field | Description | Source |
-|-------|-------------|--------|
-| **Name** | Framework/tool name | Package name from manifest |
-| **Version** | Installed version or constraint | Version spec from manifest |
-| **Purpose** | Why it was introduced | Infer from code usage, feature context, or commit message |
-| **Install Command** | How to install locally | Standard install command for the ecosystem |
-| **Key Config** | Config files or env vars needed | Scan for new config files, `.env` entries, or env references in code |
-| **Notes** | Setup gotchas, required services, manual steps | Infer from Dockerfile, docker-compose, README references, or TRAPS |
-
-### Step 3-3: Update `deploy_guide.md`
-
-Write or append to `deploy_guide.md` at the project root using this template:
-
-```markdown
-# Deploy Guide
-
-> Auto-maintained by PrizmKit retrospective. Manual edits are preserved.
-> Last updated: YYYY-MM-DD
-
-## Frameworks & Tools
-
-### <Framework Name>
-
-- **Version**: <version constraint>
-- **Purpose**: <why this framework is used>
-- **Install**:
-  ```bash
-  <install command>
-  ```
-- **Key Config**:
-  - `<config file or env var>`: <description>
-- **Notes**:
-  - <any setup gotchas, required external services, manual steps>
-```
-
-**Update rules**:
-- If `deploy_guide.md` does not exist → create it with the header and first framework entry
-- If `deploy_guide.md` exists → check if the framework already has a section (match by `### <Name>` heading). If yes, update version and any changed config. If no, append a new section.
-- Preserve any manually added content (sections not matching the template are left untouched)
-- Keep entries sorted alphabetically by framework name within `## Frameworks & Tools`
-
-**Stage the file**:
-```bash
-git add deploy_guide.md
-```
-
-### Example
-
-After adding PostgreSQL via docker-compose and Prisma ORM to a Node.js project:
-
-```markdown
-# Deploy Guide
-
-> Auto-maintained by PrizmKit retrospective. Manual edits are preserved.
-> Last updated: 2026-03-27
-
-## Frameworks & Tools
-
-### PostgreSQL
-
-- **Version**: 16
-- **Purpose**: Primary relational database for user data, orders, and product catalog
-- **Install**:
-  ```bash
-  docker compose up -d postgres
-  ```
-- **Key Config**:
-  - `DATABASE_URL` (env): PostgreSQL connection string, format `postgresql://user:pass@host:5432/dbname`
-  - `docker-compose.yml`: Service `postgres` with volume `pgdata`
-- **Notes**:
-  - Requires Docker running locally
-  - Run `npx prisma migrate deploy` after first start to initialize schema
-
-### Prisma
-
-- **Version**: ^5.20.0
-- **Purpose**: ORM for type-safe database access and schema migrations
-- **Install**:
-  ```bash
-  npm install prisma @prisma/client
-  npx prisma generate
-  ```
-- **Key Config**:
-  - `prisma/schema.prisma`: Database schema definition
-  - `DATABASE_URL` (env): Shared with PostgreSQL connection
-- **Notes**:
-  - After schema changes: `npx prisma migrate dev --name <description>`
-  - Generate client after pull: `npx prisma generate`
-```
-
----
-
 ## Final: Changelog + Stage
 
 **3a.** Append to `.prizm-docs/changelog.prizm`:
@@ -287,8 +160,6 @@ After adding PostgreSQL via docker-compose and Prisma ORM to a Node.js project:
 **3b.** Stage all doc changes:
 ```bash
 git add .prizm-docs/
-# Stage deploy guide if it was created/updated
-git add deploy_guide.md 2>/dev/null || true
 ```
 
 **3c.** Handoff:
@@ -318,5 +189,4 @@ The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show change
 
 - `.prizm-docs/*.prizm` — Structurally synced + TRAPS/RULES/DECISIONS enriched
 - `.prizm-docs/changelog.prizm` — Appended entries
-- `deploy_guide.md` — New framework/tool setup instructions (only when new frameworks detected)
-- All `.prizm-docs/` changes and `deploy_guide.md` staged via `git add`
+- All `.prizm-docs/` changes staged via `git add`

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

@@ -1,12 +1,12 @@
 ---
 name: "refactor-workflow"
 tier: 1
-description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 6-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
+description: "End-to-end refactor workflow: deep requirement Q&A → analyze → plan → implement → review → commit. 7-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
 ---
 
 # PrizmKit Refactor Workflow
 
-End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 6-phase behavior-preserving pipeline with mandatory test gates after each task.
+End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 7-phase behavior-preserving pipeline with mandatory test gates after each task.
 
 ### When to Use
 - User says "refactor", "clean up code", "restructure", "extract module", "code refactoring", "optimize code structure"
@@ -24,11 +24,12 @@ End-to-end orchestration skill for code refactoring and optimization. Chains exi
 ```
 refactor-workflow
   → Phase 0: Branch    → refactor/<slug> branch
-  → Phase 1: Analyze   → refactor-analysis.md
-  → Phase 2: Plan      → plan.md (including Tasks section)
-  → Phase 3: Implement → (code)
-  → Phase 4: Review    → (review report)
-  → Phase 5: Verify & Commit → git commit + merge decision
+  → Phase 1: Understand → deep interactive Q&A with user
+  → Phase 2: Analyze   → refactor-analysis.md
+  → Phase 3: Plan      → plan.md (including Tasks section)
+  → Phase 4: Implement → (code)
+  → Phase 5: Review    → (review report)
+  → Phase 6: Verify & Commit → git commit + merge decision
 ```
 
 ### Pipeline Phases
@@ -36,16 +37,18 @@ refactor-workflow
 | Phase | Name | Skill Used | Artifact |
 |-------|------|-----------|----------|
 | 0 | Branch Setup | git | → `refactor/<slug>` branch |
-| 1 | Analyze (Code Analysis) | Built-in code analysis + code reading | → `refactor-analysis.md` |
-| 2 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
-| 3 | Implement | `/prizmkit-implement` | (code changes) |
-| 4 | Code Review | `/prizmkit-code-review` | (review report) |
-| 5 | Verify & Commit | `/prizmkit-committer` | git commit + merge |
+| 1 | Understand (Deep Q&A) | Interactive clarification | → Refactoring requirements confirmed |
+| 2 | Analyze (Code Analysis) | Built-in code analysis + code reading | → `refactor-analysis.md` |
+| 3 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
+| 4 | Implement | `/prizmkit-implement` | (code changes) |
+| 5 | Code Review | `/prizmkit-code-review` | (review report) |
+| 6 | Verify & Commit | `/prizmkit-committer` | git commit + merge |
 
 ### Key Principles
 
 | Principle | Description |
 |-----------|-------------|
+| **Deep understanding first** | Before analyzing code, fully understand the user's motivation, goals, and constraints. Refactoring without clear goals leads to churn. |
 | **Behavior preservation** | Refactoring changes structure, not behavior. If tests pass before and after, behavior is preserved. Acceptance criteria = "behavior unchanged + structure improved". |
 | **Test gates** | Full test suite runs after every task — not just at checkpoints. A refactoring that breaks tests mid-way is much harder to debug than catching it immediately. |
 | **Structural sync only** | Refactoring triggers `/prizmkit-retrospective` Job 1 (structural sync) — update `.prizm-docs/` to reflect file/interface changes. Skip knowledge injection unless a genuinely new pitfall was discovered during refactoring. |
@@ -53,8 +56,8 @@ refactor-workflow
 
 ### Artifacts
 Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
-- **`refactor-analysis.md`** — Code analysis (Phase 1)
-- **`plan.md`** — Refactoring plan with Tasks section (Phase 2)
+- **`refactor-analysis.md`** — Code analysis (Phase 2)
+- **`plan.md`** — Refactoring plan with Tasks section (Phase 3)
 
 **PRECONDITION:**
 
@@ -91,7 +94,62 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 1: Analyze — Code Analysis
+## Phase 1: Understand — Deep Refactoring Q&A
+
+**Goal**: Fully understand the user's refactoring motivation, goals, constraints, and expectations before analyzing code. Refactoring without clear goals leads to aimless restructuring.
+
+**CRITICAL RULE**: Ask as many questions as needed until the refactoring scope and goals are crystal clear. Do NOT jump into code analysis. A misunderstood refactoring goal leads to wasted effort or, worse, breaking the architecture in an unintended direction.
+
+### Step 1.1: Motivation and Goals
+
+Ask the user to explain why they want to refactor:
+
+- **What's the pain point?** What specific problem does the current code cause? (Hard to add features? Hard to test? Confusing to read? Performance issues?)
+- **What's the desired outcome?** What should the code look like after refactoring? (Better separation of concerns? Reduced coupling? Clearer interfaces?)
+- **What triggered this?** Did a recent feature attempt expose the debt? Is it proactive cleanup?
+
+### Step 1.2: Scope and Boundaries
+
+Establish clear boundaries for what will and won't change:
+
+- **Which modules/files are in scope?** (specific paths, or "everything under src/auth/")
+- **What is explicitly OUT of scope?** (e.g., "don't touch the API layer", "leave the database schema as-is")
+- **Are there any behavior changes allowed?** (Usually no for refactoring, but sometimes the user wants to combine refactoring with a minor behavior change — clarify this upfront)
+- **Should the public API/interface stay the same?** (Or is renaming/restructuring the API acceptable?)
+
+### Step 1.3: Constraints and Risks
+
+Understand what the user is concerned about:
+
+- **Which behaviors absolutely must NOT change?** (critical paths, user-facing behavior, external integrations)
+- **Are there performance requirements?** (e.g., "the refactored code must not be slower")
+- **Are there any code areas that are particularly fragile?** (known tricky sections, undocumented behavior)
+- **Is there a deadline or time constraint?** (affects how aggressive the refactoring can be)
+- **If database/schema changes are involved**: read existing schema files first and confirm scope with user
+  ```bash
+  find . -maxdepth 4 -type f \( -name "*.prisma" -o -name "*.sql" -o -path "*/migrations/*" -o -path "*/models/*" -o -name "schema.*" -o -name "*.entity.*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' | head -20
+  ```
+
+### Step 1.4: Confirmation
+
+Summarize the refactoring scope:
+
+```
+Refactoring Scope:
+- Target: [modules/files in scope]
+- Goal: [desired structural improvement]
+- Out of scope: [what won't change]
+- Behavior contract: [what must remain unchanged]
+- Constraints: [performance, API stability, etc.]
+```
+
+Ask the user: "Is this scope accurate? Anything to adjust?"
+
+**CHECKPOINT CP-RW-1**: Refactoring scope and goals confirmed by user.
+
+---
+
+## Phase 2: Analyze — Code Analysis
 
 **Goal**: Assess current code state, identify refactoring targets, establish baseline.
 
@@ -114,16 +172,16 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 4. **Generate `refactor-analysis.md`** at `.prizmkit/refactor/<refactor-slug>/refactor-analysis.md`:
    Required sections:
    - **Current State**: module overview, file inventory, dependency graph, complexity metrics
-   - **Refactoring Goals**: what structural improvements are targeted, why (debt items, complexity, maintainability)
+   - **Refactoring Goals**: what structural improvements are targeted, why (debt items, complexity, maintainability) — aligned with user's confirmed goals from Phase 1
    - **Risk Assessment**: what could break, cross-module impact, data migration needs
    - **Baseline Tests**: test suite status (total, passing, failing), coverage estimate, behavior contracts to preserve
-   - **Scope Boundary**: what IS in scope, what is explicitly OUT of scope
+   - **Scope Boundary**: what IS in scope, what is explicitly OUT of scope — carried from Phase 1 confirmation
 
-**CHECKPOINT CP-RW-1**: `refactor-analysis.md` exists with baseline test results.
+**CHECKPOINT CP-RW-2**: `refactor-analysis.md` exists with baseline test results.
 
 ---
 
-## Phase 2: Plan — Refactor Plan & Tasks
+## Phase 3: Plan — Refactor Plan & Tasks
 
 **Goal**: Generate technical refactoring plan that preserves behavior, including task breakdown.
 
@@ -135,17 +193,17 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
    - plan.md Tasks section: each task is independently testable and preserves all tests (green → green) — this ensures any failure is immediately traceable to the task that caused it
    - Artifact path: `.prizmkit/refactor/<refactor-slug>/plan.md`
 3. **Verify plan constraints**:
-   - All public API contracts preserved
+   - All public API contracts preserved (unless explicitly agreed in Phase 1 to change)
    - Test strategy: how to verify behavior unchanged at each step
    - Rollback strategy: how to revert if behavior breaks
    - Tasks ordered to minimize risk (safe renames first, structural changes later)
    - Every task ends with "run full test suite"
 
-**CHECKPOINT CP-RW-2**: `plan.md` exists with behavior preservation strategy and Tasks section.
+**CHECKPOINT CP-RW-3**: `plan.md` exists with behavior preservation strategy and Tasks section.
 
 ---
 
-## Phase 3: Implement
+## Phase 4: Implement
 
 **Goal**: Execute refactoring tasks with mandatory test verification after each task.
 
@@ -160,9 +218,9 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
    - Mark tasks complete in plan.md Tasks section as they finish
    - Record test results after each task
 
-**CHECKPOINT CP-RW-3**: All tasks complete, full test suite green.
+**CHECKPOINT CP-RW-4**: All tasks complete, full test suite green.
 
-**Important constraints for Phase 3:**
+**Important constraints for Phase 4:**
 - Never skip the test gate between tasks — a broken intermediate state compounds into much harder debugging later
 - Never allow temporary test failures ("we'll fix it in the next task") — this assumption is almost always wrong in refactoring
 - If a task cannot be completed without breaking tests → split it into smaller tasks
@@ -170,7 +228,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 4: Code Review
+## Phase 5: Code Review
 
 **Goal**: Verify refactoring quality and behavior preservation.
 
@@ -186,14 +244,14 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
    - Verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
 2. **Run full test suite one final time**: All tests must pass
 3. **Handle review results**:
-   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 5
-   - **NEEDS_FIXES**: Return to Phase 3 following Fix Instructions (max 2 review rounds)
+   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 6
+   - **NEEDS_FIXES**: Return to Phase 4 following Fix Instructions (max 2 review rounds)
 
-**CHECKPOINT CP-RW-4**: Code review passes, all tests green.
+**CHECKPOINT CP-RW-5**: Code review passes, all tests green.
 
 ---
 
-## Phase 5: Verify, Commit & Merge
+## Phase 6: Verify, Commit & Merge
 
 **Goal**: Let user verify, commit with refactor convention, and merge back.
 
@@ -204,7 +262,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
      - **(a) Run the app** — Start dev server for manual verification
      - **(b) Run a specific command** — Specify a test or script
      - **(c) Skip** — Proceed to commit (tests already pass)
-   - If user reports issues: return to Phase 3
+   - If user reports issues: return to Phase 4
 2. **Invoke `/prizmkit-retrospective`** (Job 1: structural sync only):
    - Update KEY_FILES/INTERFACES/DEPENDENCIES in affected `.prizm-docs/` files
    - Skip knowledge injection unless refactoring revealed a genuinely new pitfall (e.g. a non-obvious coupling)
@@ -230,7 +288,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
    ```
 6. **If (b)**: Inform user: "Branch `refactor/<slug>` retained. Create a PR when ready."
 
-**CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix. Merge decision made.
+**CHECKPOINT CP-RW-6**: Commit recorded with `refactor()` prefix. Merge decision made.
 
 ---
 
@@ -239,10 +297,10 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 For single-file refactoring (rename, extract method, <30 lines changed):
 
 ```
-Phase 0 (Branch) → Phase 1 (Analyze) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit & Merge)
+Phase 0 (Branch) → Phase 1 (Simplified Q&A) → Phase 2 (Analyze) → Phase 3 (Simplified Plan) → Phase 4 (Implement) → Phase 5 (Review) → Phase 6 (Commit & Merge)
 ```
 
-Skip Phase 2's detailed planning process, but still generate a lightweight `plan.md` with a simplified Tasks section (typically 1-2 tasks).
+Phase 1 is simplified to 2-3 quick confirmation questions instead of deep dive. Skip Phase 3's detailed planning process, but still generate a lightweight `plan.md` with a simplified Tasks section (typically 1-2 tasks).
 
 **CRITERIA** (ALL must be true):
 - Single file change
@@ -252,12 +310,14 @@ Skip Phase 2's detailed planning process, but still generate a lightweight `plan
 - No dependency changes
 
 **Fast Path implementation differs from full path:**
-- Phase 2 is simplified: generate a lightweight plan.md with 1-2 tasks directly from refactor-analysis.md, without deep architecture research
-- Phase 3 still reads plan.md Tasks as normal, marks tasks `[x]` on completion
+- Phase 1 is simplified: confirm goal and scope in 2-3 questions
+- Phase 3 is simplified: generate a lightweight plan.md with 1-2 tasks directly from refactor-analysis.md, without deep architecture research
+- Phase 4 still reads plan.md Tasks as normal, marks tasks `[x]` on completion
 - Single-task refactors typically have just one task in plan.md
 
 **Fast Path still requires:**
 - Refactor branch (Phase 0)
+- Scope confirmation (Phase 1, simplified)
 - refactor-analysis.md (lightweight version with baseline)
 - plan.md (simplified, 1-2 tasks)
 - Full test suite run after implementation
@@ -276,11 +336,12 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Artifact Found | Resume From |
 |---------------|------------|
 | (nothing) | Phase 0: Branch Setup |
-| On `refactor/<slug>` branch, no artifacts | Phase 1: Analyze |
-| `refactor-analysis.md` only | Phase 2: Plan |
-| `refactor-analysis.md` + `plan.md` | Phase 3: Implement |
-| All docs + code changes exist | Phase 4: Review |
-| All docs + review passed | Phase 5: Verify & Commit |
+| On `refactor/<slug>` branch, no artifacts | Phase 1: Understand |
+| Scope confirmed, no analysis | Phase 2: Analyze |
+| `refactor-analysis.md` only | Phase 3: Plan |
+| `refactor-analysis.md` + `plan.md` | Phase 4: Implement |
+| All docs + code changes exist | Phase 5: Review |
+| All docs + review passed | Phase 6: Verify & Commit |
 
 **Resume**: If `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
 
@@ -291,6 +352,7 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Scenario | Action |
 |----------|--------|
 | Cannot identify target module | Ask user for clarification |
+| User's refactoring goal is unclear | Ask systematic clarification questions (Phase 1) |
 | No tests exist for target module | WARN user, recommend writing tests first |
 | Baseline tests already failing | Isolate failures, document, proceed with caution |
 | Test fails after a refactoring task | Revert task, investigate, retry or split |
@@ -305,13 +367,13 @@ The pipeline supports resuming from the last completed phase by detecting existi
 ## Relationship to Other Skills
 
 | Skill | Role in Refactor Workflow |
-|-------|--------------------------|
-| (built-in code analysis) | Phase 1: identify debt and complexity |
-| `/prizmkit-plan` | Phase 2: refactoring plan + task generation |
-| `/prizmkit-implement` | Phase 3: execute refactoring tasks |
-| `/prizmkit-code-review` | Phase 4: review quality and behavior preservation |
-| `/prizmkit-committer` | Phase 5: commit with `refactor()` convention |
-| `/prizmkit-retrospective` | Phase 5: structural sync before commit (Job 1 only, skip knowledge injection unless new pitfall) |
+|-------|-----------------------------|
+| (built-in code analysis) | Phase 2: identify debt and complexity |
+| `/prizmkit-plan` | Phase 3: refactoring plan + task generation |
+| `/prizmkit-implement` | Phase 4: execute refactoring tasks |
+| `/prizmkit-code-review` | Phase 5: review quality and behavior preservation |
+| `/prizmkit-committer` | Phase 6: commit with `refactor()` convention |
+| `/prizmkit-retrospective` | Phase 6: structural sync before commit (Job 1 only, skip knowledge injection unless new pitfall) |
 | `feature-workflow` | Handoff target when new behavior is needed |
 | `/prizmkit-specify` | NOT used (no user stories for refactoring) |
 | `/prizmkit-analyze` | NOT used (no spec <-> plan consistency needed) |
@@ -323,21 +385,22 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Dimension | Feature Workflow | Refactor Workflow | Bug Fix Workflow |
 |-----------|-----------------|-------------------|------------------|
 | Input | Natural language requirement | Module/code target | Bug description |
+| Deep Q&A | Yes (brainstorm) | Yes (scope & goals) | Yes (diagnosis) |
 | Branch | Pipeline manages per-feature | `refactor/<slug>` | `fix/<BUG_ID>-*` |
-| Pipeline Phases | 3 (plan → launch → monitor) | 6 (branch → analyze → plan → implement → review → commit) | 7 (branch → triage → reproduce → fix → review → verify → commit) |
-| Phase 1 | Plan (app-planner) | Analyze (refactor-analysis.md) | Triage (fix-plan.md) |
+| Pipeline Phases | 4 (brainstorm → plan → launch → monitor) | 7 (branch → understand → analyze → plan → implement → review → commit) | 8 (branch → diagnose → triage → reproduce → fix → review → verify → commit) |
+| Phase 1 | Brainstorm (requirements Q&A) | Understand (scope & goals Q&A) | Deep Bug Diagnosis (symptom Q&A) |
 | Artifact Path | `.prizmkit/specs/<slug>/` | `.prizmkit/refactor/<slug>/` | `.prizmkit/bugfix/<id>/` |
 | Commit Prefix | `feat(<scope>):` | `refactor(<scope>):` | `fix(<scope>):` |
 | Test Strategy | TDD per task | Full suite after EVERY task | Reproduction test |
 | Scope Guard | N/A | Enforced | N/A |
 | Behavior Change | Expected | Forbidden | Fix behavior |
-| User Verification | No (pipeline) | Yes (Phase 5) | Yes (Phase 5) |
+| User Verification | Yes (brainstorm confirmation) | Yes (Phase 6) | Yes (Phase 6) |
 
 ## Output
 
-- `refactor-analysis.md` (Phase 1 artifact)
-- `plan.md` with Tasks section (Phase 2 artifact)
-- Refactored implementation code (Phase 3)
-- Code review report (Phase 4, conversation only)
-- Git commit with `refactor(<scope>):` prefix on dedicated refactor branch (Phase 5)
+- `refactor-analysis.md` (Phase 2 artifact)
+- `plan.md` with Tasks section (Phase 3 artifact)
+- Refactored implementation code (Phase 4)
+- Code review report (Phase 5, conversation only)
+- Git commit with `refactor(<scope>):` prefix on dedicated refactor branch (Phase 6)
 - Updated `.prizm-docs/` (if applicable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.121",
+  "version": "1.0.123",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {