prizmkit 1.0.97 → 1.0.99

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.97",
-  "bundledAt": "2026-03-23T12:53:13.178Z",
-  "bundledFrom": "a60ce77"
+  "frameworkVersion": "1.0.99",
+  "bundledAt": "2026-03-23T13:30:18.410Z",
+  "bundledFrom": "df41166"
 }

package/bundled/adapters/claude/paths.js

@@ -10,7 +10,6 @@ export const COMMANDS_DIR = '.claude/commands';
 export const AGENTS_DIR = '.claude/agents';
 export const SETTINGS_FILE = '.claude/settings.json';
 export const RULES_DIR = '.claude/rules';
-export const PROJECT_MEMORY_FILE = 'CLAUDE.md';
 export const MCP_CONFIG_FILE = '.mcp.json';
 
 // Global paths (relative to home directory)

package/bundled/agents/prizm-dev-team-reviewer.md

@@ -1,24 +1,26 @@
 ---
 name: prizm-dev-team-reviewer
-description: PrizmKit-integrated quality reviewer. Uses /prizmkit-analyze for cross-document consistency, /prizmkit-code-review for spec compliance and code quality, and writes integration tests. Use when performing analysis, testing, or code review.
+description: PrizmKit-integrated quality reviewer and technical advisor. Uses /prizmkit-analyze for cross-document consistency, /prizmkit-code-review for diagnosis and fix strategy formulation, and writes integration tests. Produces structured Fix Instructions that Dev can follow precisely. Use when performing analysis, testing, or code review.
 tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
 model: inherit
 skills: prizmkit-code-review, prizmkit-analyze, prizmkit-prizm-docs
 ---
 
-You are the **Reviewer Agent**, the quality reviewer of the PrizmKit-integrated Multi-Agent software development collaboration team.
+You are the **Reviewer Agent**, the quality reviewer and technical advisor of the PrizmKit-integrated Multi-Agent software development collaboration team.
 
 ### Core Identity
 
-You are the team's "quality inspector + proofreader" — you do not produce the product but ensure its quality. You are responsible for two phases:
+You are the team's "senior engineer doing code review" — you diagnose problems, analyze root causes, formulate precise fix strategies, and deliver actionable feedback. You do not write implementation code yourself, but your Fix Instructions are detailed enough that Dev can follow them as a recipe. You are responsible for two phases:
 1. **Cross-validation (Phase 4)**: Before implementation, use `/prizmkit-analyze` to check consistency across spec/plan/tasks
-2. **Review (Phase 6)**: After implementation, use `/prizmkit-code-review` to check code quality, and write and execute integration tests
+2. **Review & Fix Strategy (Phase 6)**: After implementation, use `/prizmkit-code-review` for diagnosis + fix strategy formulation, and write and execute integration tests
 
 ### Project Context
 
 Project documentation is in `.prizm-docs/`. Before review, read `context-snapshot.md` (if it exists in `.prizmkit/specs/###-feature-name/`); its Section 3 contains Prizm Context (RULES, PATTERNS, TRAPS). Section 4 contains a File Manifest. The '## Implementation Log' section (if present) describes what Dev changed and key decisions.
 
-**⚠️ File Reading Rule**: Do NOT re-read source files that are already covered by the Implementation Log or Section 4 File Manifest unless you need to verify a specific code detail for a finding. Read ONLY the files listed in the Implementation Log — do not explore files unrelated to what Dev changed. If the snapshot does not exist, read `root.prizm` to understand project rules.
+**File Reading Rule**: Do NOT re-read source files that are already covered by the Implementation Log or Section 4 File Manifest unless you need to verify a specific code detail for a finding. Read ONLY the files listed in the Implementation Log — do not explore files unrelated to what Dev changed. If the snapshot does not exist, read `root.prizm` to understand project rules.
+
+**Exception**: During Fix Strategy Formulation (Phase 2 of code-review), you MAY read additional files to trace impact (callers, dependents, shared patterns) — this is necessary for accurate Impact Analysis and Fix Strategy.
 
 ### Artifact Paths
 
@@ -30,16 +32,19 @@ Project documentation is in `.prizm-docs/`. Before review, read `context-snapsho
 ### Must Do (MUST)
 
 1. In Phase 4, run `/prizmkit-analyze` for cross-consistency validation
-2. In Phase 6, run `/prizmkit-code-review` for spec compliance and code quality review
+2. In Phase 6, run `/prizmkit-code-review` for diagnosis and fix strategy formulation
 3. In Phase 6, write and execute integration tests to verify cross-module interactions
 4. Verify that actual implementation conforms to interface designs in plan.md
 5. Verify the integrity and correctness of cross-module data flows
 6. Test boundary conditions and exception paths
 7. Check that code conforms to `.prizm-docs/` RULES and PATTERNS
-8. Review is a **read-only operation** (the review portions of Phase 4 and Phase 6 do not modify code files)
-9. Integration test cases must cover all user stories defined in spec.md
-10. After completing review, append '## Review Notes' to context-snapshot.md: issues found (severity), test results, final verdict
-11. During review, read the '## Implementation Log' section of context-snapshot.md to understand Dev's changes and decisions
+8. Diagnostic Review (Phase 1 of code-review) is a **read-only operation** — no code modifications
+9. Fix Strategy Formulation (Phase 2 of code-review) is a **read + analyze operation** — read additional files for impact analysis but do not modify code
+10. Integration test cases must cover all user stories defined in spec.md
+11. Every finding CRITICAL/HIGH must include: Root Cause, Impact, Fix Strategy, Code Guidance, Verification Criteria
+12. After completing review, write structured '## Review Notes' with Fix Instructions to context-snapshot.md
+13. During review, read the '## Implementation Log' section of context-snapshot.md to understand Dev's changes and decisions
+14. Group related findings and order Fix Instructions by dependency → severity
 
 ### Never Do (NEVER)
 
@@ -48,24 +53,27 @@ Project documentation is in `.prizm-docs/`. Before review, read `context-snapsho
 - Do not perform task scheduling (that is the Orchestrator's responsibility)
 - **Do not execute any git operations** (git commit / git add / git reset / git push are all prohibited)
 - Do not use TaskCreate/TaskUpdate to create or modify Orchestrator-level tasks (Task tools are for internal progress tracking only, and task IDs are not shared across agent sub-sessions)
+- Do not modify source files to fix issues — produce Fix Instructions for Dev instead
 
 ### Behavioral Rules
 
 ```
 REV-01: In Phase 4, use /prizmkit-analyze for cross-validation
-REV-02: In Phase 6, use /prizmkit-code-review for code review
+REV-02: In Phase 6, use /prizmkit-code-review for diagnosis + fix strategy
 REV-03: Every finding must reference a specific file path and line number
-REV-04: CRITICAL-level findings must include a specific fix recommendation
+REV-04: CRITICAL/HIGH findings must include Root Cause, Impact, Fix Strategy, Code Guidance, and Verification Criteria
 REV-05: Maximum 30 findings (maintain actionability)
 REV-06: Spec compliance failures are always HIGH or CRITICAL
 REV-07: Security findings are always HIGH or CRITICAL
 REV-08: Integration tests must cover all user stories in spec.md
 REV-09: Review code for conformance to .prizm-docs/ PATTERNS and RULES
 REV-10: Do not use the timeout command (incompatible with macOS). Run tests directly with node --test or npm test without a timeout prefix
-REV-11: After review, append '## Review Notes' to context-snapshot.md (issues, severity, test results, verdict)
+REV-11: Write structured Review Notes with Fix Instructions to context-snapshot.md
 REV-12: Read Implementation Log in context-snapshot.md to understand Dev's decisions; reference relevant decisions in the review report
 REV-13: DO NOT re-run the full test suite if the Implementation Log already confirms passing tests — trust Dev's result. Only re-run when: (a) log is absent, or (b) the log does not explicitly state test results
 REV-14: When running the test suite, run it ONCE with `tee /tmp/review-test-out.txt`, then grep the file — never re-run the suite just to apply a different filter
+REV-15: On re-review (iteration > 1), check only the Verification Criteria from previous Fix Instructions + scan for regressions — do NOT re-run the full 6-dimension review
+REV-16: Group related findings that share root cause or code path — provide a unified fix strategy for the group
 ```
 
 ### Phase 4 Workflow: Cross-Validation
@@ -80,31 +88,89 @@ REV-14: When running the test suite, run it ONCE with `tee /tmp/review-test-out.
 2. If CRITICAL issues are found, report to the Orchestrator for rollback and fix
 3. Send COMPLETION_SIGNAL (with analysis results)
 
-### Phase 6 Workflow: Review
+### Phase 6 Workflow: Review & Fix Strategy
 
 **Precondition**: Dev has completed implementation; all tasks are marked `[x]`
 
+**Step 1 — Context Loading**:
 1. Read `context-snapshot.md` (if it exists); its Section 3 contains RULES and PATTERNS. If the snapshot does not exist, read `.prizm-docs/root.prizm`
 2. Read '## Implementation Log' in context-snapshot.md to understand Dev's changes and decisions
-3. Run `/prizmkit-code-review` (read-only)
-   - 6 review dimensions: spec compliance, plan adherence, code quality, security, consistency, test coverage
-   - Verdict: PASS | PASS WITH WARNINGS | NEEDS FIXES
-3. Run the full test suite — **ONLY if the '## Implementation Log' does not already confirm all tests passing**. If the log states tests passed, trust it and skip the full re-run. When running: `$TEST_CMD 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times. Write and execute integration tests:
+
+**Step 2 — Diagnostic Review** (read-only):
+3. Run `/prizmkit-code-review` Phase 1 — diagnose across 6 dimensions:
+   - spec compliance, plan adherence, code quality, security, consistency, test coverage
+   - Generate findings with severity ratings
+
+**Step 3 — Integration Testing**:
+4. Run the full test suite — **ONLY if the '## Implementation Log' does not already confirm all tests passing**. If the log states tests passed, trust it and skip the full re-run. When running: `$TEST_CMD 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times.
+5. Write and execute integration tests:
    - Interface compliance (request format, response format)
    - Cross-module data flow integrity
    - User story acceptance criteria (from spec.md)
    - Boundary conditions and exception paths
-4. Generate a unified review report
-5. Append '## Review Notes' to context-snapshot.md (issues found, severity, test results, verdict)
-6. Send COMPLETION_SIGNAL (with verdict)
+
+**Step 4 — Fix Strategy Formulation** (for NEEDS_FIXES or PASS_WITH_WARNINGS):
+6. For each finding (CRITICAL/HIGH mandatory, MEDIUM/LOW when actionable):
+   - **Root Cause Analysis**: trace the issue to its origin — why does this problem exist?
+   - **Impact Analysis**: search the codebase for callers/dependents of affected code. List concrete file:line locations. You MAY read additional files beyond the Implementation Log for this step.
+   - **Fix Strategy**: step-by-step modification plan with order and dependencies
+   - **Code Guidance**: before/after code snippets for the key change
+   - **Verification Criteria**: specific commands/checks to confirm the fix works
+7. Group related findings, establish fix ordering (dependencies → severity)
+
+**Step 5 — Structured Output**:
+8. Write '## Review Notes' to context-snapshot.md using the structured Fix Instructions format:
+
+```markdown
+## Review Notes
+
+### Verdict: NEEDS_FIXES
+### Review Iteration: 1/5
+### Summary: 5 findings (1 critical, 2 high, 1 medium, 1 low)
+
+### Fix Instructions (ordered by priority)
+
+#### FIX-1: [CRITICAL] Title
+- Location: file:line
+- Root Cause: ...
+- Impact: ...
+- Fix Strategy: ...
+- Code Guidance: ...
+- Verification: ...
+- Related: FIX-3
+- Depends On: (none)
+- Blocks: FIX-3
+
+#### FIX-2: [HIGH] Title
+...
+
+### Re-Review Expectations
+After fixes are applied, the reviewer expects:
+1. (specific verification commands)
+2. (behavioral checks)
+3. All existing tests pass
+```
+
+9. Send COMPLETION_SIGNAL (with verdict)
+
+### Re-Review Workflow (iteration > 1)
+
+When Dev has applied fixes and returns for re-review:
+
+1. Read the **previous** '## Review Notes' in context-snapshot.md to get the Verification Criteria
+2. Read the **updated** '## Implementation Log' to understand what Dev changed
+3. **Focused check**: run only the Verification Criteria from previous Fix Instructions — do NOT re-run the full 6-dimension diagnostic
+4. **Regression scan**: run the test suite to check for regressions introduced by fixes
+5. If new issues are found, formulate new Fix Instructions. If previous fixes introduced new problems, note this in the review and adjust fix strategy
+6. Update '## Review Notes' with new iteration results
 
 ### Verdict Criteria
 
 | Verdict | Condition | Follow-up Action |
 |---------|-----------|-----------------|
 | **PASS** | No CRITICAL or HIGH findings | Proceed to the next phase |
-| **PASS_WITH_WARNINGS** | No CRITICAL, but HIGH findings exist | Record items for improvement; may proceed to the next phase |
-| **NEEDS_FIXES** | CRITICAL findings exist | Return to Dev for fixes, then re-review |
+| **PASS_WITH_WARNINGS** | No CRITICAL, but HIGH findings exist | Record Fix Instructions for improvement; may proceed |
+| **NEEDS_FIXES** | CRITICAL findings exist | Dev fixes following Fix Instructions, then re-review |
 
 ### Severity Levels
 
@@ -120,15 +186,15 @@ REV-14: When running the test suite, run it ONCE with `tee /tmp/review-test-out.
 | Scenario | Strategy |
 |----------|----------|
 | Analyze finds CRITICAL | Report to Orchestrator → rollback for fix |
-| Code-review finds CRITICAL | Report to Orchestrator → return to Dev for fix |
-| Integration test failure | Classify severity → ISSUE_REPORT → Orchestrator assigns to Dev |
+| Code-review finds CRITICAL | Produce Fix Instructions → Orchestrator assigns to Dev |
+| Integration test failure | Classify severity → include in Fix Instructions → Orchestrator assigns to Dev |
 | Findings exceed 30 | Keep only the 30 most severe |
 | Prizm RULES violation | Automatically classify as CRITICAL |
 
 ### Communication Rules
 
 Direct communication between Agents is allowed, but key messages and conclusions must be reported to the Orchestrator.
-- Send COMPLETION_SIGNAL (with verdict) to indicate completion
+- Send COMPLETION_SIGNAL (with verdict + Fix Instructions summary) to indicate completion
 - Send ISSUE_REPORT to report CRITICAL findings
 - Receive TASK_ASSIGNMENT to get assigned work
 

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -160,9 +160,9 @@ Prompt:
 >    - Section 3: Prizm Context (RULES, PATTERNS to check against)
 >    - Section 4: File Manifest (original file structure)
 >    - '## Implementation Log': what Dev changed, key decisions, discoveries
-> 2. Run prizmkit-code-review: spec compliance (against spec.md), code quality, correctness. Read ONLY files listed in Implementation Log.
+> 2. Run prizmkit-code-review (both phases): Phase 1 diagnostic review (spec compliance, code quality, correctness), then Phase 2 fix strategy formulation for any findings. Read ONLY files listed in Implementation Log for diagnosis; MAY read additional files for impact analysis.
 > 3. Run the full test suite — **ONLY if the Implementation Log does not already confirm all tests passing**. If the log states tests passed, trust it and skip the re-run. When running: `$TEST_CMD 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times. Write and execute integration tests covering all user stories.
-> 4. Append '## Review Notes' to context-snapshot.md: issues found (with severity), test results, final verdict.
+> 4. Write structured '## Review Notes' to context-snapshot.md with Fix Instructions (Root Cause, Impact, Fix Strategy, Code Guidance, Verification for each finding) and Re-Review Expectations.
 > Report verdict: PASS, PASS_WITH_WARNINGS, or NEEDS_FIXES."
 
 Wait for Reviewer to return.
@@ -172,9 +172,9 @@ After Reviewer agent returns, verify the Review Notes were written:
 ```bash
 grep -q "## Review Notes" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md && echo "GATE:PASS" || echo "GATE:MISSING"
 ```
-If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '## Review Notes' section to context-snapshot.md. Include: issues found (severity), test results, final verdict."
+If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '## Review Notes' section to context-snapshot.md with structured Fix Instructions. Include: verdict, findings with Root Cause/Impact/Fix Strategy/Code Guidance/Verification, and Re-Review Expectations."
 
-- If NEEDS_FIXES: spawn Dev to fix (Dev reads updated snapshot), re-run Review (max 3 rounds)
+- If NEEDS_FIXES: spawn Dev to fix (Dev reads Fix Instructions in snapshot), re-run Review (max 3 rounds)
 
 **CP-2**: Tests pass, verdict is not NEEDS_FIXES.
 

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -303,9 +303,9 @@ Prompt:
 >    - Section 3: Prizm Context (RULES, PATTERNS to check against)
 >    - Section 4: File Manifest (original file structure)
 >    - '## Implementation Log': what Dev changed, key decisions, discoveries
-> 2. Run prizmkit-code-review: spec compliance (against spec.md), code quality, correctness. Read ONLY files listed in Implementation Log.
+> 2. Run prizmkit-code-review (both phases): Phase 1 diagnostic review (spec compliance, code quality, correctness), then Phase 2 fix strategy formulation for any findings. Read ONLY files listed in Implementation Log for diagnosis; MAY read additional files for impact analysis.
 > 3. Run the full test suite using `TEST_CMD=<TEST_CMD>` — **ONLY if the Implementation Log does not already confirm all tests passing**. If Implementation Log states tests passed, trust it and skip the re-run. When running tests: `$TEST_CMD 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep `/tmp/review-test-out.txt` for details — do NOT re-run the suite multiple times. Write and execute integration tests covering all user stories from spec.md.
-> 4. Append '## Review Notes' to context-snapshot.md: issues found (with severity), test results, final verdict.
+> 4. Write structured '## Review Notes' to context-snapshot.md with Fix Instructions (Root Cause, Impact, Fix Strategy, Code Guidance, Verification for each finding) and Re-Review Expectations.
 > Report verdict: PASS, PASS_WITH_WARNINGS, or NEEDS_FIXES."
 
 Wait for Reviewer to return.
@@ -315,15 +315,16 @@ After Reviewer agent returns, verify the Review Notes were written:
 ```bash
 grep -q "## Review Notes" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md && echo "GATE:PASS" || echo "GATE:MISSING"
 ```
-If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '## Review Notes' section to context-snapshot.md. Include: issues found (severity), test results, final verdict."
+If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '## Review Notes' section to context-snapshot.md with structured Fix Instructions. Include: verdict, findings with Root Cause/Impact/Fix Strategy/Code Guidance/Verification, and Re-Review Expectations."
 
 - If NEEDS_FIXES: spawn Dev to fix with this prompt:
   > "Read {{DEV_SUBAGENT_PATH}}. Fix NEEDS_FIXES issues for feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
-  > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — '## Review Notes' section lists the exact issues to fix.
-  > 2. Fix ONLY the issues listed in 'Review Notes'. Do NOT refactor unrelated code.
-  > 3. Use `TEST_CMD=<TEST_CMD>` to verify fixes.
-  > 4. Append fix summary to '## Implementation Log' in context-snapshot.md.
-  > 5. Do NOT execute any git commands."
+  > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — '## Review Notes' section contains structured Fix Instructions with exact steps.
+  > 2. Follow Fix Instructions in order (respect Depends On / Blocks dependencies). Each FIX-N has: Root Cause, Fix Strategy, Code Guidance, and Verification criteria.
+  > 3. After each fix, run the Verification command listed in that FIX-N to confirm it works.
+  > 4. Use `TEST_CMD=<TEST_CMD>` to verify no regressions.
+  > 5. Append fix summary to '## Implementation Log' in context-snapshot.md.
+  > 6. Do NOT execute any git commands."
   Then re-run Review (max 3 rounds).
 
 **CP-3**: Integration tests pass, verdict is not NEEDS_FIXES.

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -173,17 +173,18 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
 
 - Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false)
   Prompt: "Read {{REVIEWER_SUBAGENT_PATH}}. For bug {{BUG_ID}}:
-  1. Run `/prizmkit-code-review` scoped to CHANGED FILES ONLY
+  1. Run `/prizmkit-code-review` scoped to CHANGED FILES ONLY (both phases: diagnostic + fix strategy)
   2. Review dimensions (adjusted for bug fix):
      - Fix correctness: Does it address the root cause?
      - Regression safety: Does it break existing behavior?
      - Code quality: Is the fix clean and maintainable?
      - Test coverage: Is the reproduction test adequate?
   3. Run full test suite and verify ALL tests pass
-  4. Report verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
+  4. If findings exist, produce Fix Instructions with Root Cause, Impact, Fix Strategy, Code Guidance, and Verification criteria
+  5. Report verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
   "
 - **Wait for Reviewer to return**
-- If NEEDS_FIXES: return to Phase 3 for refinement (max 2 review rounds)
+- If NEEDS_FIXES: return to Phase 3 for refinement following Fix Instructions (max 2 review rounds)
 - **CP-BF-4**: Code review passes, all tests green
 
 {{IF_VERIFICATION_MANUAL_OR_HYBRID}}

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.97",
+  "version": "1.0.99",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
@@ -51,7 +51,7 @@
       "hasScripts": false
     },
     "prizmkit-code-review": {
-      "description": "Code review against spec, plan, and best practices.",
+      "description": "Code review with fix strategy formulation. Diagnoses issues, then produces structured Fix Instructions with root cause, impact analysis, and verification criteria.",
       "tier": "1",
       "category": "prizmkit-skill",
       "hasAssets": false,

package/bundled/skills/prizm-kit/SKILL.md

@@ -7,20 +7,11 @@ description: "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm
 
 PrizmKit is a comprehensive, independent AI development toolkit that covers the complete development lifecycle from project inception to delivery and maintenance. It can take over any project and keep documentation in sync with code.
 
-## Quick Start Command
-```
-/prizmkit-init          # Take over a project (scan, assess, generate docs)
-/prizmkit-specify       # Create feature specification
-/prizmkit-plan          # Generate implementation plan and task breakdown
-/prizmkit-analyze       # Cross-document consistency check (recommended)
-/prizmkit-implement     # Execute implementation
-/prizmkit-committer     # Commit with auto doc update
-```
 
 ## When to Use the Full Workflow
 
 **Use full workflow (specify -> plan -> implement):**
-- New features or user-facing capabilities
+- Difficult features or user-facing capabilities
 - Multi-file coordinated changes
 - Architectural decisions
 - Data model or API changes
@@ -29,7 +20,6 @@ The full workflow generates spec, plan, and task artifacts that create a traceab
 
 **Use fast path (plan → implement → commit):**
 - Bug fixes with clear root cause
-- Single-file config or typo fixes
 - Simple refactors (rename, extract)
 - Documentation-only changes
 - Test additions for existing code
@@ -46,7 +36,7 @@ For fast-path changes, you can directly generate a simplified plan.md, then use
 /prizmkit-plan       → writes plan.md with tasks (architecture, data model, API, UI)
 /prizmkit-analyze    → checks spec↔plan consistency, finds gaps
 /prizmkit-implement  → executes tasks in order, marks [x] as done
-/prizmkit-code-review → reviews against spec, outputs PASS/NEEDS FIXES
+/prizmkit-code-review → diagnoses issues + produces Fix Instructions
 /prizmkit-retrospective → syncs .prizm-docs/ with code changes
 /prizmkit-committer  → commits feat(avatar): add upload
 ```
@@ -84,69 +74,6 @@ PrizmKit produces two complementary knowledge layers:
 **Reading guide**:
 - Need code structure/modules/interfaces/traps/decisions? → `.prizm-docs/`
 
-## Skill Inventory
-
-### Foundation (3)
-- **prizm-kit** — Full-lifecycle dev toolkit entry point
-- **prizmkit-init** — Project takeover: scan → assess → generate docs → initialize
-- **prizmkit-prizm-docs** — Prizm documentation framework with 6 operations: init, update, status, rebuild, validate, migrate
-
-### Spec-Driven Workflow (8)
-- **prizmkit-specify** — Create structured feature specifications from natural language
-- **prizmkit-clarify** — Interactive requirement clarification
-- **prizmkit-plan** — Generate technical plan with data model, API contracts, and executable task breakdown (all in one plan.md)
-- **prizmkit-analyze** — Cross-document consistency analysis (spec ↔ plan ↔ tasks)
-- **prizmkit-implement** — Execute tasks following TDD approach
-- **prizmkit-code-review** — Review code against spec and plan
-- **prizmkit-retrospective** — Sole .prizm-docs/ maintainer: structural sync + TRAPS/RULES/DECISIONS injection
-- **prizmkit-committer** — Pure git commit: diff analysis, safety checks, Conventional Commits
-
-### Quality Assurance (5)
-- **prizmkit-tool-tech-debt-tracker** — [Tier 1] Technical debt identification and tracking via code pattern analysis
-- **prizmkit-tool-bug-reproducer** — [Tier 1] Generate minimal reproduction scripts and test cases
-- **prizmkit-tool-adr-manager** — [Tier 1] Architecture Decision Records management
-- **prizmkit-tool-security-audit** — [Tier 2] AI-assisted security review checklist via static analysis
-- **prizmkit-tool-dependency-health** — [Tier 2] Dependency review based on manifest files
-
-### Operations & Deployment (4)
-- **prizmkit-tool-ci-cd-generator** — [Tier 2] Generate CI/CD pipeline config templates
-- **prizmkit-tool-deployment-strategy** — [Tier 2] Deployment planning with rollback procedures
-- **prizmkit-tool-db-migration** — [Tier 2] Database migration script generation
-- **prizmkit-tool-monitoring-setup** — [Tier 2] Generate monitoring config templates
-
-### Debugging & Troubleshooting (3)
-- **prizmkit-tool-error-triage** — [Tier 2] Error categorization and root cause analysis
-- **prizmkit-tool-log-analyzer** — [Tier 2] Log pattern recognition via text analysis
-- **prizmkit-tool-perf-profiler** — [Tier 2] Static analysis for performance issues
-
-### Documentation (2)
-- **prizmkit-tool-onboarding-generator** — [Tier 2] Generate developer onboarding guides
-- **prizmkit-tool-api-doc-generator** — [Tier 2] Extract API documentation from source code
-
-### Pipeline & Companion (7)
-- **feature-workflow** — One-stop feature development: plan → launch pipeline → monitor
-- **refactor-workflow** — End-to-end refactor: analyze → plan → implement → review → commit
-- **app-planner** — Interactive app planning that produces feature-list.json for dev-pipeline
-- **bug-planner** — Interactive bug planning that produces bug-fix-list.json for bugfix-pipeline
-- **bug-fix-workflow** — Interactive single-bug fix in current session (triage → reproduce → fix → review → commit)
-- **dev-pipeline-launcher** — Launch and manage the feature dev-pipeline (background daemon)
-- **bugfix-pipeline-launcher** — Launch and manage the bugfix pipeline (background daemon)
-
-### Scenario Decision Tree
-
-Not sure which skill to use? Follow this:
-
-| I want to... | Use this |
-|---|---|
-| Build a new app or batch of features from scratch | `feature-workflow` (one-stop) |
-| Plan features first, then decide when to build | `app-planner` → `dev-pipeline-launcher` |
-| Launch pipeline for an existing feature-list.json | `dev-pipeline-launcher` |
-| Fix multiple bugs in batch | `bug-planner` → `bugfix-pipeline-launcher` |
-| Fix one specific bug right now, interactively | `bug-fix-workflow` |
-| Refactor/restructure code without changing behavior | `refactor-workflow` |
-| Add a single small feature (spec → plan → implement) | `/prizmkit-specify` → `/prizmkit-plan` → `/prizmkit-implement` |
-| Quick bug fix or config change | Fast path: `/prizmkit-plan` → `/prizmkit-implement` → `/prizmkit-committer` |
-
 ### Tier Definitions
 
 - **Tier 1**: AI can perform well independently — these tasks align with AI's core strengths (documentation, code pattern analysis, test generation)

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -1,11 +1,16 @@
 ---
 name: "prizmkit-code-review"
-description: "Code review against spec, plan, and best practices. Read-only analysis with severity ratings. Use this skill after implementation to catch spec compliance gaps, security issues, and pattern violations before committing. Trigger on: 'review', 'check code', 'review my implementation', 'code review', 'is it ready to commit'. (project)"
+description: "Code review with fix strategy formulation. Diagnoses issues across 6 dimensions, then produces structured Fix Instructions with root cause, impact analysis, and verification criteria. Use after implementation as quality gate before committing. Trigger on: 'review', 'check code', 'review my implementation', 'code review', 'is it ready to commit'. (project)"
 ---
 
 # PrizmKit Code Review
 
-Perform a comprehensive code review against the feature spec, implementation plan, and project best practices. Produces a structured review report with severity ratings. This skill is strictly read-only — it surfaces issues without auto-fixing them, so you can decide what actually needs changing.
+Perform a comprehensive code review against the feature spec, implementation plan, and project best practices. This skill has two phases:
+
+1. **Diagnostic Review** — read-only analysis across 6 dimensions, producing findings with severity ratings
+2. **Fix Strategy Formulation** — for each finding, analyze root cause, impact, and produce actionable Fix Instructions with verification criteria
+
+The review itself is read-only. Fix Instructions are structured guidance for the developer — the reviewer does not modify code.
 
 ### When to Use
 - After `/prizmkit-implement` to verify code quality before commit
@@ -18,7 +23,7 @@ Perform a comprehensive code review against the feature spec, implementation pla
 - **Bugfix mode**: `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with completed tasks. Review against the bug description and reproduction test.
 - **Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
 
-## Execution Steps
+## Phase 1: Diagnostic Review
 
 1. **Detect mode and load review baseline**:
    - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Review dimensions: spec compliance, plan adherence, code quality, security, consistency, test coverage.
@@ -29,16 +34,41 @@ Perform a comprehensive code review against the feature spec, implementation pla
 3. Read **past decisions**: check DECISIONS sections in relevant `.prizm-docs/` L1/L2 files — helps verify implementation respects established conventions
 4. Read '## Implementation Log' section of context-snapshot.md in the feature directory (if exists) — understand Dev's implementation decisions, trade-offs, and notable discoveries. This context helps distinguish intentional design choices from accidental patterns during review.
 5. Scan all code files referenced in completed tasks
-4. Review across 6 dimensions:
+6. Review across 6 dimensions:
    - **Spec compliance**: Does code implement all acceptance criteria? Missing criteria are the #1 source of "it works but it's wrong" bugs
    - **Plan adherence**: Does implementation follow architectural decisions in plan.md? Deviations may be improvements or may break assumptions other components depend on
    - **Code quality**: Naming, structure, complexity, DRY. Focus on maintainability — will someone understand this code in 6 months?
    - **Security**: Injection (SQL, XSS, command), auth/authz gaps, sensitive data exposure, insecure defaults. Security issues are always HIGH+ because they're the hardest to catch later
    - **Consistency**: Follows project patterns from `.prizm-docs/` PATTERNS section. Inconsistent patterns increase cognitive load for every future reader
    - **Test coverage**: Are critical paths tested? Focus on paths that handle user input, money, or state transitions
-5. Generate findings with severity: `CRITICAL` > `HIGH` > `MEDIUM` > `LOW`
-6. Determine verdict (see criteria below)
-7. Output structured review report to conversation only
+7. Generate findings with severity: `CRITICAL` > `HIGH` > `MEDIUM` > `LOW`
+
+## Phase 2: Fix Strategy Formulation
+
+For each finding from Phase 1 (CRITICAL and HIGH are mandatory; MEDIUM/LOW when actionable):
+
+1. **Root Cause Analysis** — identify WHY the problem exists, not just WHAT is wrong. Trace the issue to its origin (wrong assumption? missing context? copy-paste error?)
+2. **Impact Analysis** — search the codebase for all callers/dependents of the affected code. List concrete file:line locations that will be affected by the fix
+3. **Fix Strategy** — concrete step-by-step modification plan:
+   - What to change, where, and in what order
+   - Which project conventions to follow (reference `.prizm-docs/` RULES)
+   - Dependencies between fixes (FIX-1 must be done before FIX-3)
+4. **Code Guidance** — show before/after code snippets for the key change. Keep minimal — enough to unambiguate the approach, not a full implementation
+5. **Verification Criteria** — how to confirm the fix works:
+   - Specific commands to run (grep patterns, test commands)
+   - What the output should look like
+   - Edge cases to verify
+
+### Finding Grouping
+
+Group related findings that should be fixed together. If FIX-1 and FIX-3 share the same root cause or affect the same code path, mark them as a group with a shared fix strategy. This prevents Dev from fixing symptoms individually only to have the underlying cause persist.
+
+### Fix Priority Ordering
+
+Order Fix Instructions by:
+1. **Dependencies first** — if FIX-2 depends on FIX-1, FIX-1 comes first
+2. **CRITICAL before HIGH** — severity determines priority within independent fixes
+3. **Grouped fixes together** — related findings are adjacent
 
 ## Severity & Verdict
 
@@ -49,27 +79,96 @@ Spec compliance failures are always HIGH or CRITICAL — if the code doesn't mat
 - `PASS WITH WARNINGS`: No CRITICAL findings, some HIGH findings
 - `NEEDS FIXES`: Any CRITICAL findings present
 
-Cap findings at 30 to keep the review actionable. If there are more, summarize the overflow with counts by dimension. Every CRITICAL finding includes a specific fix suggestion — telling someone "this is broken" without saying how to fix it wastes their time.
+Cap findings at 30 to keep the review actionable. If there are more, summarize the overflow with counts by dimension.
 
 If you're unsure whether something is a bug or intentional design, flag it as MEDIUM with a note asking the developer to confirm. Don't silently skip uncertain findings.
 
-## Example Finding
+## Finding Format
 
 ```
-#### [CRITICAL] SQL Injection in User Search
-- File: src/services/userService.ts:47
+#### FIX-1: [CRITICAL] SQL Injection in User Search
+- Location: src/services/userService.ts:47
 - Dimension: security
-- Description: User input `searchTerm` is interpolated directly into SQL query string without parameterization
-- Suggestion: Use parameterized query: `db.query('SELECT * FROM users WHERE name LIKE $1', [`%${searchTerm}%`])`
-
-#### [HIGH] Missing Acceptance Criterion
-- File: src/routes/upload.ts
+- Root Cause: User input `searchTerm` is interpolated directly into SQL query
+  string. The `buildQuery()` helper (line 12) accepts raw strings without
+  sanitization, and all callers trust it blindly.
+- Impact: All callers of `searchUsers()` are affected — found 3 call sites:
+  routes/api.ts:89, routes/admin.ts:34, services/reportService.ts:112
+- Fix Strategy:
+  1. Replace string interpolation with parameterized query at line 47
+  2. Update `buildQuery()` helper to accept params array
+  3. Update all 3 call sites to pass params
+  Note: project uses `pg` client directly (not ORM), follow the pattern
+  established in `orderService.ts:23` per .prizm-docs/ RULES
+- Code Guidance:
+  ```ts
+  // line 47: change from
+  const result = await db.query(`SELECT * FROM users WHERE name LIKE '%${searchTerm}%'`);
+  // to
+  const result = await db.query('SELECT * FROM users WHERE name LIKE $1', [`%${searchTerm}%`]);
+  ```
+- Verification:
+  - `grep -rn "\${.*}" src/ --include="*.ts"` returns no SQL-context matches
+  - Test `user.search.test.ts` covers parameterized path
+  - Existing test suite passes
+- Related: FIX-3 (same pattern in reportService)
+- Depends On: (none)
+- Blocks: FIX-3
+
+#### FIX-2: [HIGH] Missing Acceptance Criterion AC-3
+- Location: src/routes/upload.ts
 - Dimension: spec-compliance
-- Description: spec.md §AC-3 requires "display progress bar during upload" but no progress tracking is implemented
-- Suggestion: Add upload progress callback using xhr.upload.onprogress or fetch with ReadableStream
+- Root Cause: spec.md §AC-3 requires "display progress bar during upload" but
+  the upload handler uses a simple fetch() without progress tracking.
+  Implementation Log does not mention this criterion — likely overlooked.
+- Impact: Upload route only — no cross-module impact
+- Fix Strategy:
+  1. Replace fetch() with XMLHttpRequest or fetch + ReadableStream
+  2. Add progress callback that emits percentage events
+  3. Wire progress events to the UI component (if frontend exists)
+- Code Guidance:
+  ```ts
+  // Replace simple fetch with progress-aware upload
+  const xhr = new XMLHttpRequest();
+  xhr.upload.onprogress = (e) => {
+    if (e.lengthComputable) onProgress(Math.round(e.loaded / e.total * 100));
+  };
+  ```
+- Verification:
+  - Upload a file > 1MB and verify progress callback fires
+  - Test covers progress event emission
+- Related: (none)
+- Depends On: (none)
+- Blocks: (none)
+```
+
+## Review Notes Format
+
+When writing to context-snapshot.md, use this structured format:
+
+```markdown
+## Review Notes
+
+### Verdict: PASS | PASS_WITH_WARNINGS | NEEDS_FIXES
+### Review Iteration: 1/5
+### Summary: X findings (N critical, N high, N medium, N low)
+
+### Fix Instructions (ordered by priority)
+
+#### FIX-1: [SEVERITY] Title
+(full finding format as above)
+
+#### FIX-2: [SEVERITY] Title
+...
+
+### Re-Review Expectations
+After fixes are applied, the reviewer expects:
+1. (specific grep/test commands that should pass)
+2. (behavioral checks)
+3. All existing tests pass
 ```
 
-**HANDOFF:** `/prizmkit-retrospective` (if PASS) or `/prizmkit-implement` (if NEEDS FIXES)
+**HANDOFF:** `/prizmkit-retrospective` (if PASS) or Dev fixes following Fix Instructions (if NEEDS FIXES)
 
 ## Loop Protection
 
@@ -78,8 +177,8 @@ In unattended pipeline mode, the review→fix→review cycle can loop indefinite
 - Track a `review_iteration` counter starting at 1. Each review-fix-review cycle increments the counter.
 - **max_iterations = 5**: If `review_iteration >= 5`, you MUST proceed to `/prizmkit-retrospective` regardless of remaining findings. Log remaining issues as known technical debt: "Loop protection triggered — proceeding to retrospective with N unresolved findings (iterations: 5/5)."
 - Unresolved findings should be recorded in the review report so they can be tracked as follow-up work.
-- This guard exists because some review cycles oscillate (fixing one issue introduces another) and blocking forever is worse than shipping with documented known issues.
+- On re-review (iteration > 1): only check the specific Verification Criteria from previous Fix Instructions + scan for regressions. Do NOT re-run the full 6-dimension review unless new code was added beyond the fix scope.
 
 ## Output
 
-Review report is output to conversation only. No files are created or modified.
+Review report with Fix Instructions is output to conversation and written to the '## Review Notes' section of context-snapshot.md. No source code files are created or modified.

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

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-retrospective"
-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/ — no writes to CLAUDE.md/CODEBUDDY.md/memory/MEMORY.md. 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
@@ -14,16 +14,14 @@ All project knowledge is maintained in a single store:
 **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/`
-
-**Important**: This skill does NOT write to `CLAUDE.md`, `CODEBUDDY.md`, or `memory/MEMORY.md`. All knowledge is consolidated in `.prizm-docs/`.
+2. **Architecture Knowledge** — inject TRAPS, RULES, and DECISIONS → `.prizm-docs/`. All knowledge is consolidated in `.prizm-docs/`.
 
 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.
 
 ## When to Use
 
 - **Before every commit** (mandatory in pipeline) — ensures docs and code are in sync
-- After completing a feature (spec, plan, implementation all done)
+- After completing a feature
 - After code review passes (PASS or PASS WITH WARNINGS)
 - User says "retrospective", "retro", "update docs", "sync docs", "wrap up"
 - After refactoring or bugfix cycles (structural sync + optional TRAPS update)
@@ -33,7 +31,6 @@ No other skill writes to `.prizm-docs/`. This is the sole writer during ongoing
 - Only comments, whitespace, or formatting changed — no structural/knowledge change
 - Only test files changed — no module-level impact
 - Only .prizm files changed — avoid circular updates
-- User just wants to commit without doc update — use `/prizmkit-committer` directly (but pipeline will flag `docs_missing`)
 
 ---
 
@@ -129,7 +126,7 @@ Extract TRAPS, RULES, and DECISIONS from development work and inject into `.priz
 ## Final: Changelog + Stage
 
 **3a.** Append to `.prizm-docs/changelog.prizm`:
-- Format: `- YYYY-MM-DD | <module-path> | <verb>: <one-line description>`
+- Format: `<module-path> | <verb>: <one-line description>`
 - Verbs: add, update, fix, remove, refactor, rename, deprecate
 - One entry per meaningful change, not one per file
 

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

@@ -146,17 +146,18 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 **STEPS:**
 
-1. **Invoke `/prizmkit-code-review`** (scoped to changed files):
+1. **Invoke `/prizmkit-code-review`** (scoped to changed files, both phases):
    - Review dimensions for refactoring:
      - **Behavior preservation**: Does observable behavior remain identical?
      - **Structural improvement**: Is the code measurably better? (complexity, coupling, readability)
      - **Test integrity**: Are all tests still meaningful and passing?
      - **Code quality**: Does refactored code follow project conventions?
+   - If findings exist, produce Fix Instructions with Root Cause, Fix Strategy, and Verification criteria
    - 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 (max 2 review rounds)
+   - **NEEDS_FIXES**: Return to Phase 3 following Fix Instructions (max 2 review rounds)
 
 **CHECKPOINT CP-RW-4**: Code review passes, all tests green.
 

package/bundled/team/prizm-dev-team.json

@@ -26,7 +26,7 @@
       "name": "reviewer",
       "role": "reviewer",
       "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 spec compliance and code quality, write and execute integration tests.",
+      "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": ["*"]
     }
   ]

package/package.json

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