prizmkit 1.0.45 → 1.0.58

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

@@ -1,79 +1,156 @@
 ---
 name: "prizmkit-retrospective"
-description: "Post-feature retrospective. Extracts lessons from completed features, updates Prizm docs TRAPS and RULES. Invoke after feature completion. (project)"
+description: "The SOLE maintainer of .prizm-docs/ project memory. Performs two jobs: (1) structural sync — update KEY_FILES/INTERFACES/DEPENDENCIES to reflect code changes, and (2) knowledge injection — extract TRAPS/RULES/DECISIONS from completed work. Update project documentation after code changes. Run after code review passes and before committing. Must be run before /prizmkit-committer. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete', 'update project documentation'. (project)"
 ---
 
 # PrizmKit Retrospective
 
-Post-feature retrospective analysis that extracts lessons learned, updates Prizm documentation with discovered traps and rules, and documents improvements for future reference.
+**The sole maintainer of `.prizm-docs/` project memory.** No other skill writes to `.prizm-docs/`. This skill performs two distinct jobs in one pass:
 
-### When to Use
-- After completing a feature (spec, plan, tasks, implementation all done)
-- User says "retrospective", "retro", "lessons learned", "what did we learn"
-- Before starting a new major feature (to apply lessons from the last one)
+1. **Structural Sync** — reflect what changed in code (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
+2. **Knowledge Injection** — extract what was learned (TRAPS, RULES, DECISIONS)
 
-### prizmkit.retrospective
+Both jobs are necessary because `.prizm-docs/` exists to help AI understand the project. Structural accuracy tells AI *what exists*; knowledge tells AI *why it exists and what to watch out for*.
 
-PRECONDITION: Completed feature with spec.md, plan.md, tasks.md in .prizmkit/specs/
+## 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 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)
+
+## When NOT to Use
+
+- 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`)
+
+---
+
+## Job 1: Structural Sync
+
+Reflect code changes in `.prizm-docs/` so the project map stays accurate.
+
+### Steps
+
+**1a.** Get changed files:
+```bash
+git diff --cached --name-status
+```
+If nothing staged, fallback:
+```bash
+git diff --name-status
+```
+
+**1b.** Read `.prizm-docs/root.prizm` to get MODULE_INDEX. Map each changed file to its module.
+
+**1c.** Classify changes:
+- `A` (added) → add to KEY_FILES, check for new INTERFACES
+- `D` (deleted) → remove from KEY_FILES, update FILE count
+- `M` (modified) → check if public interfaces or dependencies changed
+- `R` (renamed) → update all path references
+
+**1d.** Update affected docs (bottom-up: L2 → L1 → L0):
+
+- **L2** (if exists): Update KEY_FILES, INTERFACES, DEPENDENCIES, CHANGELOG, UPDATED timestamp
+- **L1**: Update FILES count, KEY_FILES (if major files added/removed), INTERFACES (if public API changed), UPDATED timestamp
+- **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update UPDATED only if structural change (module added/removed).
+
+**1e.** If new directory with 3+ source files matches no existing module: create L1 doc immediately, add to MODULE_INDEX, defer L2.
+
+**1f.** Enforce size limits:
+- L0 > 4KB → consolidate MODULE_INDEX
+- L1 > 3KB → move details to L2
+- L2 > 5KB → archive old CHANGELOG entries
+
+**SKIP structural sync if**: only internal implementation changed (no interface/dependency impact), only comments/whitespace, only test files, only .prizm files, bug fixes with no interface change.
+
+---
+
+## Job 2: Knowledge Injection
+
+Extract what was learned and inject it into the modules where AI will read it. This job has value **only when real development work was done** — not for trivial changes.
+
+### When to run Job 2
+
+- Feature completion (spec + plan + implementation done)
+- Bugfix with a genuinely new pitfall discovered
+- Refactor that revealed structural insights
+- **Skip for**: trivial fixes, config changes, dependency bumps
 
 ### Steps
 
-#### Step 1: Gather Feature Artifacts
-Read all feature artifacts from .prizmkit/specs/###-feature-name/:
-- spec.md (original requirements and acceptance criteria)
-- plan.md (architecture decisions and implementation plan)
-- tasks.md (task breakdown and status)
-- data-model.md (if exists)
-- contracts/ directory (if exists)
-
-#### Step 2: Analyze Implementation
-Compare planned vs actual:
-- Tasks completed vs skipped — why were tasks skipped?
-- Architecture deviations from plan — what changed and why?
-- Unexpected challenges encountered — what surprised us?
-- Time-intensive areas — what took longer than expected?
-
-#### Step 3: Extract Lessons
-Categorize findings:
-- **What went well** (reinforce these patterns)
-- **What went wrong** (create anti-patterns to avoid)
-- **What was surprising** (new patterns to document)
-- **What would you do differently** (improvement candidates)
-
-NOTE: If bug fixes were performed during this feature's implementation, they are refinements of the feature itself (completing its intended behavior), NOT separate features. Do not create separate documentation entries or REGISTRY records for bug fixes.
-
-#### Step 4: Generate Retrospective Document
-Write retrospective.md in .prizmkit/specs/###-feature-name/:
-```markdown
-# Retrospective: <feature-name>
-Date: YYYY-MM-DD
-
-## Summary Statistics
-- Tasks total: N
-- Tasks completed: N
-- Tasks skipped: N (with reasons)
-
-## Key Decisions
-- Decision: <what> | Outcome: <good/bad/neutral> | Lesson: <takeaway>
-
-## Patterns Discovered
-- Pattern: <name> | Context: <when to apply> | Benefit: <why>
-
-## Anti-Patterns Discovered
-- Anti-pattern: <name> | Context: <when it occurred> | Fix: <what to do instead>
-
-## Improvement Suggestions
-- Skill: <skill-name> | Suggestion: <what to improve>
+**2a.** Gather context — read the **actual code that was changed** plus any available artifacts:
+
+- `git diff HEAD` — the real source of truth for what happened
+- `.prizmkit/specs/###-feature-name/plan.md` — if feature work, read planned vs actual
+- `.prizmkit/bugfix/<id>/fix-report.md` — if bugfix, read what was discovered
+- The relevant `.prizm-docs/` L1/L2 docs for affected modules
+
+**2b.** Extract knowledge from what was **observed in code**, not invented:
+
+**TRAPS** (highest priority) — things that look safe but break:
+- Format: `- <what looks safe but is dangerous> | FIX: <correct approach>`
+- Source: actual bugs hit, surprising behavior discovered in code, non-obvious coupling
+
+**RULES** — conventions established or constraints discovered:
+- Format: `- MUST/NEVER/PREFER: <rule>`
+- Source: patterns that proved necessary during implementation
+
+**DECISIONS** — architecture choices made and why:
+- Format: `- [YYYY-MM-DD] <decision and rationale>`
+- Format: `- REJECTED: <approach> — <why it failed>`
+- Source: alternatives tried, design trade-offs made
+
+**QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizm-docs/` and this entry, does it gain actionable understanding that prevents mistakes or accelerates work?" If not, discard.
+
+**2c.** Inject into the correct `.prizm-docs/` file:
+- Module-level TRAPS/RULES/DECISIONS → the affected L1 or L2 `.prizm` file
+- Project-level RULES/PATTERNS → `root.prizm`
+
+**RULE**: Only add genuinely new information. Never duplicate existing entries. Never rewrite entire files.
+
+---
+
+## Final: Changelog + Stage
+
+**3a.** Append to `.prizm-docs/changelog.prizm`:
+- Format: `- YYYY-MM-DD | <module-path> | <verb>: <one-line description>`
+- Verbs: add, update, fix, remove, refactor, rename, deprecate
+- One entry per meaningful change, not one per file
+
+**3b.** Stage all doc changes:
+```bash
+git add .prizm-docs/
 ```
 
-#### Step 5: Update Prizm Docs
-For each lesson learned, update the relevant `.prizm-docs/` files:
-- Add discovered pitfalls to the affected module's TRAPS section
-- Add new conventions or rules to the affected module's RULES section
-- Append decisions to DECISIONS section with rationale
-- Update changelog.prizm with retrospective findings
-
-#### Step 6: Handoff
-Suggest next action:
-- `prizmkit.specify` — start next feature
-- No action needed — just documenting for future reference
+**3c.** Handoff:
+- `/prizmkit-committer` — proceed to commit
+
+---
+
+## Integration with Pipeline
+
+In the dev-pipeline, this skill is the **single doc maintenance step** before commit:
+
+```
+implement → code-review → retrospective (memory maintenance) → committer (pure commit)
+```
+
+The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show changes in the final commit. This skill is the sole satisfier of that requirement.
+
+## HANDOFF Chain
+
+| From | To | Condition |
+|------|----|-----------|
+| `prizmkit-code-review` | **this skill** | Review passes or work is complete |
+| **this skill** | `prizmkit-committer` | Memory maintained, ready to commit |
+| `prizmkit-committer` | — | Committed |
+
+## Output
+
+- `.prizm-docs/*.prizm` — Structurally synced + knowledge enriched
+- `.prizm-docs/changelog.prizm` — Appended entries
+- All changes staged via `git add .prizm-docs/`

package/bundled/skills/prizmkit-retrospective/assets/retrospective-template.md

@@ -0,0 +1,13 @@
+# Retrospective: [FEATURE_NAME]
+Date: YYYY-MM-DD
+
+## Knowledge Captured
+- TRAPS added: N (list affected modules)
+- RULES added: N (list affected modules)
+- DECISIONS recorded: N (list affected modules)
+
+## Key Insights
+- [insight]: [why it matters for future work]
+
+## .prizm-docs/ Updates
+- [file]: [what was updated]

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

@@ -1,19 +1,25 @@
 ---
 name: "prizmkit-specify"
-description: "Create structured feature specifications from natural language. Invoke when starting a new feature, user says 'specify', 'define feature', or 'write requirements'. (project)"
+description: "Create structured feature specifications from natural language. Use this skill whenever the user wants to define a new feature, describe what to build, or write requirements. Trigger on: 'specify', 'define feature', 'write requirements', 'new feature', 'what should we build', 'I want to add...', 'I want to build...', 'let's add', 'let's build', 'feature idea', or when the user describes a feature they want. This is the first step in the full dev workflow — always use before /prizmkit-plan. Skip for bug fixes, config tweaks, or simple refactors (use fast path). (project)"
 ---
 
 # PrizmKit Specify
 
 Create structured feature specifications from natural language descriptions. This skill transforms a feature idea into a well-structured spec with user stories, acceptance criteria, and scope boundaries.
 
-## Commands
+### When to Use
+- Starting a new feature — user says "specify", "define feature", "new feature", "I want to add..."
+- Before `/prizmkit-plan` — to define WHAT will be built before deciding HOW
+- When a feature idea needs to be formalized before implementation
+- When multiple stakeholders need to agree on scope before coding starts
 
-### prizmkit.specify
+### When NOT to Use
+- Bug fixes with clear root cause → use fast path (/prizmkit-implement directly)
+- Config tweaks, typo fixes, simple refactors → edit directly
+- Documentation-only changes → no spec needed
+- User already has a detailed spec → skip to /prizmkit-plan
 
-Create a new feature specification.
-
-**STEPS:**
+## Execution Steps
 
 1. Ask user for feature description (natural language)
 2. Auto-generate 2-4 word feature slug from description
@@ -35,14 +41,58 @@ Create a new feature specification.
    - Check: No more than 3 `[NEEDS CLARIFICATION]` markers?
 8. Output: `spec.md` path and summary
 
-**KEY RULES:**
-- Focus on WHAT and WHY, never HOW (no tech stack details)
-- Max 3 `[NEEDS CLARIFICATION]` markers
-- Every user story MUST have at least one acceptance criterion in Given/When/Then format
-- Scope boundaries MUST be explicitly defined
-- Feature numbers are zero-padded to 3 digits (e.g., `001`, `012`)
+## Writing Principles
+
+- **Focus on WHAT and WHY, never HOW** — the spec describes the problem space; implementation choices belong in plan.md. Mixing in tech stack details couples the spec to a specific solution and makes it harder to explore alternatives during planning.
+- **Every user story needs acceptance criteria** in Given/When/Then format — without them, the implementer has no way to verify the feature works correctly, and the code reviewer has no baseline to check against.
+- **Scope boundaries must be explicit** — without "Out of scope" boundaries, implementers tend to gold-plate features with capabilities nobody asked for, wasting time and adding complexity.
+- **Max 3 `[NEEDS CLARIFICATION]` markers** — more than 3 means the feature idea isn't mature enough to spec. Suggest the user think through the concept further and return, or use `/prizmkit-clarify` to resolve them interactively.
+- **Feature numbers are zero-padded to 3 digits** (e.g., `001`, `012`) — ensures consistent sorting in file explorers and git logs.
+
+## Handling Vague Inputs
+
+When the user's feature description is vague:
+1. Extract what IS clear and write that into the spec
+2. Mark genuinely ambiguous parts with `[NEEDS CLARIFICATION]` and include a recommended default
+3. Suggest running `/prizmkit-clarify` to resolve ambiguities interactively before proceeding to plan
+
+The goal is to never block progress — always produce a usable spec, even if it has open questions.
+
+## Example
+
+**Input:** "I want users to upload avatars"
+
+**Output:** `.prizmkit/specs/003-user-avatar/spec.md`
+```markdown
+# Feature: User Avatar Upload
+
+## Overview
+Allow users to upload and manage profile avatar images.
+
+## User Stories
+
+### US-1: Upload Avatar
+As a registered user, I want to upload a profile picture,
+so that other users can visually identify me.
+
+**Acceptance Criteria:**
+- Given I am on my profile page
+- When I select an image file and click upload
+- Then my avatar is updated and visible across the platform
+
+### US-2: Remove Avatar
+As a registered user, I want to remove my avatar,
+so that I can revert to a default placeholder.
+
+## Scope
+- **In scope:** Upload, display, remove avatar; image format validation
+- **Out of scope:** Image cropping/editing, avatar history
+
+## Open Questions
+- [NEEDS CLARIFICATION] Maximum file size limit? Recommended: 10MB
+```
 
-**HANDOFF:** `prizmkit.plan` or `prizmkit.clarify`
+**HANDOFF:** `/prizmkit-plan` or `/prizmkit-clarify`
 
 ## Template
 

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

@@ -1,21 +1,28 @@
 ---
 name: "refactor-workflow"
 tier: 1
-description: "[Tier 1] End-to-end refactor workflow: analyze → plan → implement → review → commit. 5-phase behavior-preserving pipeline with mandatory test gates. (project)"
----
-
-refactor-workflow-SKILL.md
-refactor-workflow/SKILL.md
+description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 5-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', '重构', '优化代码结构', '代码重构'. (project)"
 ---
 
 # PrizmKit Refactor Workflow
 
-End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills (tech-debt-tracker, plan, implement, code-review, committer) into a 5-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 5-phase behavior-preserving pipeline with mandatory test gates after each task.
+
+### When to Use
+- User says "refactor", "clean up code", "restructure", "extract module", "重构", "优化代码结构"
+- Code has accumulated tech debt that needs structural improvement
+- Module needs to be split, merged, or reorganized
+- When behavior must remain unchanged but internal quality needs improvement
+
+**Do NOT use when:**
+- User wants to add new features (use `feature-workflow`)
+- User wants to fix bugs (use `bug-planner` + `bugfix-pipeline-launcher`)
+- Change is trivial (single rename, <5 lines) — just do it directly
 
 ## Overview
 
 ```
-prizmkit.refactor <目标模块或描述>
+refactor-workflow
   → Phase 1: Analyze   → refactor-analysis.md
   → Phase 2: Plan      → plan.md (including Tasks section)
   → Phase 3: Implement → (code)
@@ -27,43 +34,45 @@ prizmkit.refactor <目标模块或描述>
 
 | Phase | Name | Skill Used | Artifact |
 |-------|------|-----------|----------|
-| 1 | Analyze 代码分析 | `prizmkit.tech-debt-tracker` + code reading | → `refactor-analysis.md` |
-| 2 | Plan 重构方案与任务 | `prizmkit.plan` | → `plan.md` (含 Tasks section) |
-| 3 | Implement 实现 | `prizmkit.implement` | (code changes) |
-| 4 | Code Review | `prizmkit.code-review` | (review report) |
-| 5 | Commit | `prizmkit.committer` | git commit |
+| 1 | Analyze 代码分析 | `/prizmkit-tool-tech-debt-tracker` + code reading | → `refactor-analysis.md` |
+| 2 | Plan 重构方案与任务 | `/prizmkit-plan` | → `plan.md` (含 Tasks section) |
+| 3 | Implement 实现 | `/prizmkit-implement` | (code changes) |
+| 4 | Code Review | `/prizmkit-code-review` | (review report) |
+| 5 | Commit | `/prizmkit-committer` | git commit |
 
 ### Key Principles
+
 | Principle | Description |
 |-----------|-------------|
-| **Behavior preservation** | Refactoring MUST NOT change observable behavior. Acceptance criteria = "behavior unchanged + structure improved". |
-| **Test gates** | Full test suite MUST run after EVERY task** — not just at checkpoints. |
-| **No REGISTRY entry** | Refactoring does not go into REGISTRY.md (no user stories, no feature registration). |
-| **Incremental safety** | Each task preserves all tests; if tests fail → STOP and revert. |
+| **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. |
+| **Incremental safety** | Each task preserves all tests (green → green). If tests fail → stop and revert, because later tasks build on the assumption that previous ones are clean. |
 
 ### 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)
 
-## Commands
-### prizmkit.refactor \<目标模块或描述\>
-Execute the full refactor pipeline for a module or code area.
 **INPUT**: Target description. Can be:
 - Module or file path (e.g., "src/auth/")
 - Natural language description (e.g., "重构认证模块，提取公共逻辑")
 - Specific refactoring goal (e.g., "extract payment processing into separate service")
+
 ---
 
 ## Phase 1: Analyze — 代码分析
+
 **Goal**: Assess current code state, identify refactoring targets, establish baseline.
+
 **STEPS:**
+
 1. **Read target code**: Thoroughly read and understand the target module/files:
    - Code structure and architecture
    - Dependencies (incoming and outgoing)
    - Current test coverage
    - Known tech debt (from `.prizm-docs/` TRAPS)
-2. **Invoke `prizmkit.tech-debt-tracker`** on target area:
+2. **Invoke `/prizmkit-tool-tech-debt-tracker`** on target area:
    - Receive: debt items, complexity metrics, code smell patterns
    - Identify highest-impact refactoring opportunities
 3. **Establish baseline**:
@@ -77,15 +86,21 @@ Execute the full refactor pipeline for a module or code area.
    - **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
+
 **CHECKPOINT CP-RW-1**: `refactor-analysis.md` exists with baseline test results.
+
 ---
+
 ## Phase 2: Plan — 重构方案与任务
+
 **Goal**: Generate technical refactoring plan that preserves behavior, including task breakdown.
+
 **STEPS:**
+
 1. **Read context**: refactor-analysis.md, `.prizm-docs/` (PATTERNS, RULES, TRAPS)
-2. **Invoke `prizmkit.plan`** with refactor-analysis.md as input (in place of spec.md):
-   - Plan MUST specify: what changes, what stays the same, how behavior is preserved
-   - plan.md Tasks section: each task MUST be independently testable, MUST preserve all tests (green → green)
+2. **Invoke `/prizmkit-plan`** with refactor-analysis.md as input (in place of spec.md):
+   - Plan specifies: what changes, what stays the same, how behavior is preserved
+   - 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
@@ -93,77 +108,109 @@ Execute the full refactor pipeline for a module or code area.
    - 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.
+
 ---
+
 ## Phase 3: Implement — 实现
+
 **Goal**: Execute refactoring tasks with mandatory test verification after each task.
+
 **STEPS:**
+
 1. **For EACH task in plan.md Tasks section**:
    a. Implement the refactoring change
-   b. **Run FULL test suite** (not just affected tests)
+   b. **Run FULL test suite** (not just affected tests) — refactoring can have surprising cross-module effects that targeted tests miss
    c. Verify: all previously-passing tests still pass
-   d. If any test fails → STOP, revert task, investigate
+   d. If any test fails → stop, revert task, investigate
 2. **Progress tracking**:
    - 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.
-**KEY RULES:**
-- NEVER skip the test gate between tasks
-- NEVER allow temporary test failures ("we'll fix it in the next task")
+
+**Important constraints for Phase 3:**
+- 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
 - Max 3 attempts per task before escalating to user
+
 ---
+
 ## Phase 4: Code Review — 代码审查
+
 **Goal**: Verify refactoring quality and behavior preservation.
+
 **STEPS:**
-1. **Invoke `prizmkit.code-review`** (scoped to changed files):
+
+1. **Invoke `/prizmkit-code-review`** (scoped to changed files):
    - 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?
    - Verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
-2. **Run full test suite one final time**: All tests MUST pass
+2. **Run full test suite one final time**: All tests must pass
 3. **Handle review results**:
-   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 6
+   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 5
    - **NEEDS_FIXES**: Return to Phase 3 (max 2 review rounds)
+
 **CHECKPOINT CP-RW-4**: Code review passes, all tests green.
+
 ---
+
 ## Phase 5: Commit — 提交
+
 **Goal**: Commit with refactor convention.
+
 **STEPS:**
-1. **Invoke `prizmkit.committer`**:
+
+1. **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)
+   - If structural changes are significant (module split/merge), update L1 doc
+   - Stage doc changes: `git add .prizm-docs/`
+2. **Invoke `/prizmkit-committer`**:
    - Commit message: `refactor(<scope>): <description>`
    - Include all refactored code + any test updates
    - Do NOT push
-   - Do NOT invoke `prizmkit.summarize` (no REGISTRY entry for refactoring)
-2. **Update `.prizm-docs/`** if needed:
-   - Updated module structure documentation
-   - New PATTERNS discovered
-   - Resolved TRAPS (remove if debt is paid)
+
 **CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix.
+
 ---
+
 ## Fast Path — 快速路径
+
 For single-file refactoring (rename, extract method, <30 lines changed):
+
 ```
 Phase 1 (Analyze) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit)
 ```
+
 Skip Phase 2 (Plan).
+
 **CRITERIA** (ALL must be true):
 - Single file change
 - Estimated change < 30 lines
 - Well-known refactoring pattern (rename, extract method/class, inline, move)
 - No cross-module impact
 - No dependency changes
+
 **Fast Path still requires:**
 - refactor-analysis.md (lightweight version with baseline)
 - Full test suite run after implementation
 - Code review
 - `refactor(<scope>):` commit convention
+
 ---
+
 ## Resume — 中断恢复
+
 The pipeline supports resuming from the last completed phase by detecting existing artifacts.
+
 **Detection logic**: Check `.prizmkit/refactor/<slug>/` for:
+
 | Artifact Found | Resume From |
 |---------------|------------|
 | (nothing) | Phase 1: Analyze |
@@ -171,9 +218,13 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | `refactor-analysis.md` + `plan.md` | Phase 3: Implement |
 | All docs + code changes exist | Phase 4: Review |
 | All docs + review passed | Phase 5: Commit |
-**Resume command**: `prizmkit.refactor <slug>` — if `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
+
+**Resume**: If `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
+
 ---
+
 ## Error Handling
+
 | Scenario | Action |
 |----------|--------|
 | Cannot identify target module | Ask user for clarification |
@@ -184,22 +235,27 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Review fails after 2 rounds | Escalate with review findings |
 | Refactoring creates circular dependency | STOP, revise plan |
 | Performance regression detected | STOP, investigate, revise approach |
+
 ---
+
 ## Relationship to Other Skills
+
 | Skill | Role in Refactor Workflow |
 |-------|--------------------------|
-| `prizmkit-tool-tech-debt-tracker` | 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-tool-tech-debt-tracker` | 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) |
 | `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) |
-| `prizmkit-summarize` | NOT used (no REGISTRY entry for refactoring) |
-| `prizmkit-retrospective` | Optional: post-refactor lessons learned |
+| `/prizmkit-specify` | NOT used (no user stories for refactoring) |
+| `/prizmkit-analyze` | NOT used (no spec ↔ plan consistency needed) |
+
 ---
+
 ## Comparison with Feature and Bug Fix Pipelines
+
 | Dimension | Feature Workflow | Refactor Workflow | Bug Fix Pipeline |
 |-----------|-----------------|-------------------|------------------|
 | Input | Natural language requirement | Module/code target | Bug description |
@@ -211,9 +267,9 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | 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 |
-## Path References
-All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
+
 ## Output
+
 - `refactor-analysis.md` (Phase 1 artifact)
 - `plan.md` with Tasks section (Phase 2 artifact)
 - Refactored implementation code (Phase 3)