prizmkit 1.0.122 → 1.0.124

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/bundled/team/prizm-dev-team.json

@@ -1,7 +1,7 @@
 {
   "name": "prizm-dev-team",
   "team_name": "prizm-dev-team",
-  "description": "PrizmKit-integrated Multi-Agent software development team. 2 specialized agents (Dev, Reviewer) following PrizmKit spec-driven workflow with 7-phase pipeline and 4 checkpoints.",
+  "description": "PrizmKit-integrated Multi-Agent software development team. 3 specialized agents (Dev, Reviewer, Critic) following PrizmKit spec-driven workflow with pipeline and checkpoints.",
   "lead": "team-lead",
   "communication": {
     "protocol": "SendMessage",
@@ -28,6 +28,13 @@
       "agentDefinition": "prizm-dev-team-reviewer",
       "prompt": "You are the Reviewer Agent of the prizm-dev-team. In Phase 4: run /prizmkit-analyze for cross-document consistency. In Phase 6: run /prizmkit-code-review for diagnosis + fix strategy formulation, write and execute integration tests. Produce structured Fix Instructions (Root Cause, Impact, Fix Strategy, Code Guidance, Verification) so Dev can follow them precisely. Write Fix Instructions to context-snapshot.md '## Review Notes' section.",
       "subscriptions": ["*"]
+    },
+    {
+      "name": "critic",
+      "role": "critic",
+      "agentDefinition": "prizm-dev-team-critic",
+      "prompt": "You are the Critic Agent of the prizm-dev-team. Challenge plans and implementations for project fitness, style consistency, robustness, and integration quality. Do NOT verify correctness — that is the Reviewer's job. Write challenge-report.md with adversarial findings.",
+      "subscriptions": ["*"]
     }
   ]
 }

package/package.json

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