prizmkit 1.1.111 → 1.1.112

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

@@ -1,345 +1,284 @@
 ---
 name: "recovery-workflow"
-description: "Recover and resume interrupted interactive workflow sessions. Auto-detects which workflow (feature-workflow, bug-fix-workflow, refactor-workflow) was interrupted and what phase it reached by inspecting git branch names, characteristic artifacts, and pipeline state — then resumes from the breakpoint. Use this skill whenever an AI CLI session is interrupted mid-workflow, times out, or hits token limits. Trigger on: 'recover', 'resume', 'continue where I left off', 'session interrupted', 'session timed out', 'pick up where it left off', 'token limit exceeded', 'salvage partial work'."
+description: "Recover and resume interrupted PrizmKit workflow or pipeline sessions. Auto-detects feature-workflow, bug-fix-workflow, refactor-workflow, plan lists, pipeline state, git branches, diffs, spec/plan artifacts, review artifacts, and session summaries; then offers recovery script, manual command, interactive resume, clean retry, or start-fresh options. Use when an AI CLI session timed out, crashed, hit token limits, left partial work, or the user says recover, resume, continue where I left off, pick up where it left off, or salvage partial work."
 ---
 
 # Recovery Workflow
 
-Auto-detect and resume interrupted interactive workflow sessions. When a user's AI CLI session is interrupted mid-workflow (timeout, token limit, crash, manual stop), this skill inspects the workspace to determine which workflow was running and what phase it reached, then continues from the breakpoint.
+Recover interrupted workflow or pipeline work. This skill is intentionally different from the ordinary feature/bug/refactor workflows: the success criterion is high-quality continuation of interrupted work, not structural consistency with other workflows.
 
 ## When to Use
 
-User says:
-- "Recover", "Resume", "Continue where I left off"
-- "Session interrupted / timed out / token limit exceeded"
-- "Pick up where it left off"
-- "Don't want to restart from scratch"
+Use this skill when the user says:
+- Recover, resume, continue where I left off, or pick up where it left off.
+- Session interrupted, timed out, crashed, or hit token limits.
+- A pipeline/AI session left partial work and the user wants to salvage or complete it.
+- The user does not know whether the interrupted work was feature, bug fix, or refactor work.
 
-**Do NOT use when:**
-- Pipeline interrupted → use `python3 ./.prizmkit/dev-pipeline/cli.py reset feature <F-XXX> --clean --run .prizmkit/plans/feature-list.json` / `python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix <B-XXX> --clean --run .prizmkit/plans/bug-fix-list.json` for a fresh retry
-- User wants a clean restart → use the original workflow skill directly (`/feature-workflow`, `/bug-fix-workflow`, `/refactor-workflow`)
-- Nothing was ever started → use the original workflow skill
+Do not use this skill when:
+- The user only wants normal pipeline status/logs/stop/retry for a healthy pipeline -> use the matching launcher.
+- The user explicitly wants a clean retry of one pipeline item -> use the matching launcher reset guidance.
+- The user wants to discard all interrupted work and start fresh -> route to the original workflow after confirmation.
 
-## Pipeline Recovery (Recommended)
+## Recovery Approach Policy
 
-**IMPORTANT**: In Phase 1.3, you MUST present the user with a choice between pipeline recovery (`python3 ./.prizmkit/dev-pipeline/cli.py recovery run`) and interactive recovery. **NEVER skip this choice. NEVER decide for the user.** The pipeline approach is recommended because it generates a comprehensive bootstrap prompt that explicitly lists every remaining phase with full instructions, ensuring the AI completes the full workflow — not just the implementation part.
+Always present the user with recovery choices after detection. Do not silently choose between script recovery and interactive recovery.
 
-Pipeline commands (for reference — Phase 1.3 will present these as a selectable option):
+Recommended default:
+- Use `python3 ./.prizmkit/dev-pipeline/cli.py recovery run` when the interrupted work appears to be a pipeline or AI-session continuation problem and the user wants autonomous completion.
 
-```bash
-python3 ./.prizmkit/dev-pipeline/cli.py recovery run                # Auto-detect and recover
-python3 ./.prizmkit/dev-pipeline/cli.py recovery detect              # Detection report only
-python3 ./.prizmkit/dev-pipeline/cli.py recovery run --dry-run       # Generate prompt, don't execute
-python3 ./.prizmkit/dev-pipeline/cli.py recovery run --yes           # Skip confirmation
-python3 ./.prizmkit/dev-pipeline/cli.py recovery run --model <model> # Override AI model
-```
-
-### When to use pipeline vs interactive recovery
-
-| Scenario | Approach |
-|----------|----------|
-| Pipeline session timed out / crashed | `python3 ./.prizmkit/dev-pipeline/cli.py recovery run` — autonomous, completes all phases reliably |
-| Interactive session interrupted | This skill (`/recovery-workflow`) — for in-session interactive use |
-| Want to inspect before recovering | `python3 ./.prizmkit/dev-pipeline/cli.py recovery detect` or `python3 ./.prizmkit/dev-pipeline/cli.py recovery run --dry-run` |
-| Daemon/scripted use | `python3 ./.prizmkit/dev-pipeline/cli.py recovery run --yes` — no user confirmation needed |
-
-## Supported Workflows
-
-| Workflow | Branch Pattern | Key Artifacts |
-|----------|---------------|---------------|
-| bug-fix-workflow | `fix/<BUG_ID>-*` | `.prizmkit/bugfix/<BUG_ID>/fix-plan.md`, `fix-report.md` |
-| feature-workflow | `feat/*` | `.prizmkit/plans/feature-list.json`, `.prizmkit/state/features/` |
-| refactor-workflow | `refactor/*` | `.prizmkit/plans/refactor-list.json`, `.prizmkit/state/refactor/` |
-
----
-
-## Overview
-
-1. **Phase 0: Auto-detect**
-   1. Read current branch name
-   2. Scan characteristic artifacts
-   3. Match workflow signature → determine workflow type
-   4. Based on artifact presence → infer current phase
-   5. No match → reject and guide user
-2. **Phase 1: Diagnose + report + user choice**
-   1. Check branch and working tree state
-   2. Scan all pipelines for failed/in-progress tasks
-   3. Find residual dev branches from failed tasks
-   4. Display diagnosis + detection results
-   5. If code changes exist → run test suite
-   6. If multiple failed tasks → ask user which to recover
-   7. User chooses: python3 ./.prizmkit/dev-pipeline/cli.py recovery run (recommended) | interactive | start fresh
-3. **Phase 2: Execute remaining steps**
-   1. Read target workflow's SKILL.md
-   2. Read existing artifacts to restore context
-   3. Execute from inferred phase through completion
-
----
+Interactive recovery remains valid when:
+- The user wants control in the current conversation.
+- The recovery script is unavailable or fails.
+- The interrupted work is a small current-workspace Fast Path task.
+- The user wants to inspect before launching another AI session.
 
-## Phase 0: Auto-detect
+Clean retry is different from recovery:
+- Use clean retry when the user wants to discard the failed item attempt and rerun from scratch.
+- Use recovery when partial work, context, or decisions should be preserved.
 
-**Goal**: Identify which workflow was interrupted and what phase it reached.
+## Detection Signals
 
-Run the detection script:
+Inspect multiple signals. Do not depend on a single artifact.
 
-Run the detection script (`python3 ${SKILL_DIR}/scripts/detect-recovery-state.py`). For the full signature matching table, phase inference tables (bug-fix/feature/refactor), and no-workflow-detected guidance, read `${SKILL_DIR}/references/detection.md`.
+| Signal | Meaning |
+|---|---|
+| Current branch | `fix/*`, `feat/*`, `refactor/*`, or task-specific branch names can indicate workflow family |
+| Git diff / staged / untracked files | Shows partial implementation or planning work |
+| `spec.md` / `plan.md` | Current-session Fast Path planning artifacts |
+| `.prizmkit/plans/feature-list.json` | Feature pipeline planning artifact |
+| `.prizmkit/plans/bug-fix-list.json` | Bugfix pipeline planning artifact |
+| `.prizmkit/plans/refactor-list.json` | Refactor pipeline planning artifact |
+| `.prizmkit/state/features/` | Feature pipeline state |
+| `.prizmkit/state/bugfix/` | Bugfix pipeline state |
+| `.prizmkit/state/refactor/` | Refactor pipeline state |
+| `session-summary.md` / `context-snapshot.md` | Previous-session context handoff |
+| Review artifacts | Evidence that implementation reached review |
+| `.prizmkit/bugfix/<BUG_ID>/fix-plan.md` / `fix-report.md` | Optional bug recovery signals when present, not required contract |
 
-**CHECKPOINT CP-REC-0**: Workflow type and phase identified.
+Run the detection script for the first pass:
 
----
+```bash
+python3 ${SKILL_DIR}/scripts/detect-recovery-state.py
+```
 
-## Phase 1: Diagnose + Report + User Confirmation
+For the signature matching and phase inference tables, read `${SKILL_DIR}/references/detection.md`.
 
-**Goal**: Assess workspace health, identify failed tasks across all pipelines, and present recovery options.
+## Recovery Flow
 
-### 1.0 Workspace & Failure Diagnosis
+### Phase 0: Auto-detect
 
-Before showing the recovery report, run a comprehensive diagnosis:
+1. Run the detection script.
+2. If the script fails, fall back to manual checks: branch, git status, list files, pipeline state directories, and obvious session artifacts.
+3. Identify primary workflow family: bug-fix, feature, refactor, or unknown.
+4. Identify whether the work is current-workspace Fast Path, planned pipeline work, active pipeline work, failed pipeline item, or ambiguous.
 
-1. **Check current branch and working tree**:
-   ```bash
-   git branch --show-current
-   git status --porcelain | head -10
-   ```
-   Report: which branch is active, whether there are uncommitted changes.
+Checkpoint: recovery target and likely phase are known, or no workflow is detected.
 
-2. **Scan all pipelines for failed/in-progress tasks**:
-   ```bash
-   # Feature pipeline
-   python3 ./.prizmkit/dev-pipeline/cli.py feature status .prizmkit/plans/feature-list.json
+### Phase 1: Diagnose workspace health
 
-   # Bugfix pipeline
-   python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
+Before recommending recovery, inspect and summarize:
 
-   # Refactor pipeline
-   python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
-   ```
-   For each pipeline that has state, extract: total tasks, completed, failed, in-progress, pending.
+- Current branch.
+- Whether the working tree has uncommitted changes.
+- Whether code/test files changed.
+- Which plan lists exist.
+- Which pipeline state directories exist.
+- Failed, in-progress, pending, and completed items when status commands are available.
+- Residual task branches that may correspond to failed/interrupted work.
+- Detected artifacts such as `spec.md`, `plan.md`, review reports, session summaries, or optional bugfix reports.
 
-3. **Find residual dev branches** from failed/interrupted tasks:
-   ```bash
-   git branch --list 'dev/*' 'feat/*' 'fix/*' 'bugfix/*' 'refactor/*'
-   ```
-   Cross-reference with failed task IDs to identify which branches belong to which failed tasks.
+Use concise markdown, not box-drawing banners:
 
-4. **Present diagnosis summary** — show all findings before the recovery report:
-   ```
-   ═══════════════════════════════════════════════════
-     Workspace Diagnosis
-   ═══════════════════════════════════════════════════
+```markdown
+## Workspace Diagnosis
 
-     Branch:       fix/B-001-login-crash
-     Working tree: 3 uncommitted changes
+- Branch: fix/B-001-login-crash
+- Working tree: 3 uncommitted files
+- Code changes: 2 source files, 1 test file
+- Plan lists: bug-fix-list.json found
+- Pipeline state: bugfix has 1 failed item
+- Session artifacts: plan.md found, review report not found
 
-     Feature pipeline:  2 completed, 1 failed (F-003), 2 pending
-     Bugfix pipeline:   1 completed, 1 failed (B-002), 0 pending
-     Refactor pipeline: (no state found)
+## Detected Recovery Target
 
-     Residual branches:
-       dev/F-003-payment-integration-202604201030
-       fix/B-002-encoding-bug
+- Workflow: bug-fix-workflow
+- Likely phase: Review
+- Reason: fix branch + code changes + no review artifact
+- Remaining work: review -> verification -> commit -> merge decision
+```
 
-     Failed tasks:
-       F-003: Payment integration    [FAILED] → branch: dev/F-003-...
-       B-002: CSV encoding bug       [FAILED] → branch: fix/B-002-...
-   ═══════════════════════════════════════════════════
-   ```
+If code changes exist, run or suggest the project test command when it is safe and reasonably detectable. Report failures without hiding them.
 
-   If no pipelines have state and no failed tasks are found, skip to 1.1 (standard recovery report).
+### Phase 2: Select recovery target
 
-### 1.1 Display Detection Report
+If multiple failed or interrupted targets exist, use `AskUserQuestion` to choose the first target.
 
-Read the script output and present a formatted summary:
+For up to three targets, list each target explicitly plus an all-sequential option. If there are more than three targets, group choices to avoid an overloaded question:
 
-```
-═══════════════════════════════════════════════════
-  Recovery Report
-═══════════════════════════════════════════════════
-
-  Workflow:     bug-fix-workflow
-  Branch:       fix/B-001-login-crash
-  Phase:        5 — Review
-
-  Artifacts Found:
-    ✓ fix-plan.md (fix approach documented)
-    ✗ fix-report.md (not yet created)
-    ✓ Code changes (4 files — 3 modified, 1 new)
-    ✓ Test files (1 touched)
-
-  Reason:   fix-plan.md exists + code changes present
-  Remaining: code review → user verification → commit & merge
-═══════════════════════════════════════════════════
+```text
+Question: Multiple interrupted targets found. Which should we recover first?
+Header: Target
+Options:
+- Highest-priority failed item — recover the most urgent failed item first
+- Choose from summary — show full target list before selecting
+- Recover all sequentially — recover each failed/interrupted item in priority order
+- Stop here — do not recover now
 ```
 
-### 1.2 Run Tests (if code changes exist)
+### Phase 3: Select recovery approach
 
-If the detection report shows code changes (`code.has_changes == true`), run the project's test suite:
+Use `AskUserQuestion` for the approach. Do not proceed without an explicit selection.
 
-```bash
-# detect test command from package.json or .prizmkit/config.json
-npm test   # or the appropriate test command
+```text
+Question: Interrupted work was detected. How would you like to recover?
+Header: Recovery
+Options:
+- Run recovery script (Recommended) — execute python3 ./.prizmkit/dev-pipeline/cli.py recovery run to generate a bootstrap prompt and complete remaining phases in a dedicated AI session
+- Resume interactively — continue from the inferred phase in this conversation
+- Clean retry — discard the failed item attempt and rerun it from scratch through the matching launcher reset flow
+- Start fresh — abandon interrupted work and restart the original workflow
 ```
 
-Include test results in the report:
-- How many tests pass/fail
-- If failures exist — which tests and why
-
-### 1.3 Select Recovery Target (if multiple failed tasks)
-
-If the diagnosis in 1.0 found **multiple failed/interrupted tasks** across pipelines, ask the user which one to recover first before proceeding:
+If the user wants to inspect first, offer:
 
-```
-AskUserQuestion:
-  question: "Multiple failed/interrupted tasks found. Which would you like to recover?"
-  header: "Target"
-  options:
-    - label: "F-003: Payment integration"
-      description: "Feature pipeline — FAILED — branch: dev/F-003-payment-integration-202604201030"
-    - label: "B-002: CSV encoding bug"
-      description: "Bugfix pipeline — FAILED — branch: fix/B-002-encoding-bug"
-    - label: "Recover all sequentially"
-      description: "Recover each failed task one by one in priority order"
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py recovery detect
+python3 ./.prizmkit/dev-pipeline/cli.py recovery run --dry-run
 ```
 
-Generate the options dynamically from the diagnosis results. Include task ID, title, pipeline type, status, and branch name.
+### Phase 4: Execute the selected approach
 
-If only one failed/interrupted task is found, skip this step — proceed directly to 1.4 with that task as the recovery target.
+**Run recovery script**:
 
-### 1.4 Ask User to Choose Recovery Approach
-
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. **NEVER skip this step. NEVER choose for the user.**
-
-```
-AskUserQuestion:
-  question: "Interrupted {workflow_type} detected at Phase {N} ({phase_name}). How would you like to recover?"
-  header: "Recovery"
-  options:
-    - label: "Run recovery script (Recommended)"
-      description: "Execute python3 ./.prizmkit/dev-pipeline/cli.py recovery run — autonomously completes ALL remaining phases (review, commit, merge, etc.) via a dedicated AI session with explicit phase instructions"
-    - label: "Copy command and run manually"
-      description: "I'll give you the exact shell command to paste into your terminal — you run it yourself outside this session"
-    - label: "Resume interactively in this session"
-      description: "Continue from Phase {N} within this conversation — more control, but may not complete all phases if session is interrupted again"
-    - label: "Start fresh"
-      description: "Discard interrupted work and restart the original workflow from scratch"
-```
-
-**If "Run recovery script"** → Execute the pipeline recovery:
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py recovery run
 ```
-The script handles everything: detection, confirmation, prompt generation, session spawn, and post-session validation. **End this skill after launching the script** — do not proceed to Phase 2.
 
-**If "Copy command and run manually"** → Output the command for the user to copy and run in their own terminal:
-```
-To recover, run this command in your project root:
+After launch, stop this skill and report how the user can monitor the recovery session.
 
-  python3 ./.prizmkit/dev-pipeline/cli.py recovery run
+**Resume interactively**:
 
-Or with options:
-  python3 ./.prizmkit/dev-pipeline/cli.py recovery run --dry-run    # Preview the recovery prompt first
-  python3 ./.prizmkit/dev-pipeline/cli.py recovery run --yes         # Skip confirmation
-  python3 ./.prizmkit/dev-pipeline/cli.py recovery run --model <model>  # Specify AI model
-```
-**End this skill** — do not proceed to Phase 2. The user will run the command themselves.
+1. Read the target workflow SKILL.md.
+2. Read available context artifacts in this order:
+   - `context-snapshot.md` when present.
+   - `session-summary.md` when present.
+   - `spec.md`, `plan.md`, review reports, relevant diffs, and list entries.
+3. Read relevant `.prizmkit/prizm-docs/` according to the project progressive-loading protocol.
+4. Continue from the inferred phase using the target workflow's rules.
+5. Preserve existing work where safe; do not restart from scratch unless the user chooses that.
 
-**If "Resume interactively"** → Continue to Phase 2 below (execute remaining steps in this session).
+**Clean retry**:
 
-**If "Start fresh"** → Suggest the appropriate original workflow skill:
-- bug-fix-workflow → `/bug-fix-workflow`
-- feature-workflow → `/feature-workflow`
-- refactor-workflow → `/refactor-workflow`
-End this skill.
+Route to the matching launcher reset flow:
 
-**NEVER proceed to Phase 2 without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature <FEATURE_ID> --clean --run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix <BUG_ID> --clean --run .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <REFACTOR_ID> --clean --run .prizmkit/plans/refactor-list.json
+```
 
-**CHECKPOINT CP-REC-1**: User chose recovery target and approach.
+Ask before running a clean retry because it intentionally discards that item's prior session state.
 
----
+**Start fresh**:
 
-## Phase 2: Execute Remaining Steps
+Suggest the original workflow:
+- `feature-workflow`
+- `bug-fix-workflow`
+- `refactor-workflow`
 
-**Goal**: Read the target workflow's SKILL.md and execute from the inferred phase.
+Stop after the user confirms restart.
 
-### 2.0 Read Target Workflow
+## Per-Workflow Recovery Notes
 
-1. **Read the workflow's SKILL.md** from `core/skills/orchestration-skill/workflows/{workflow-type}/SKILL.md`
-2. **Read existing artifacts** to restore context — check in this order for the most efficient recovery:
-   - If `context-snapshot.md` exists in the artifact directory → read it first. It provides a snapshot of completed tasks, key decisions, and remaining work from the interrupted session.
-   - If `session-summary.md` exists → read it for a lightweight summary of the previous session.
-   - Then read remaining artifacts: spec.md, plan.md, review-report.md, code diffs, bug descriptions, etc.
-3. **Read relevant `.prizmkit/prizm-docs/`** — load project context (L0 root, relevant L1/L2 for affected modules).
+### Bug-fix recovery
 
-This step replaces the context that was lost when the AI session was interrupted.
+Bug-fix recovery should not assume `fix-plan.md` or `fix-report.md` exists. Use them when present, but also infer from:
 
----
+- `fix/*` branch.
+- Code/test diff.
+- `spec.md` / `plan.md`.
+- Review artifacts.
+- Commits ahead of the original branch.
+- User-provided bug ID or matching bug-fix-list entry.
 
-### 2.1 Per-Workflow Phase Inference
+Typical inference:
 
-Read `${SKILL_DIR}/references/detection.md` for the per-workflow phase-inference tables (bug-fix / feature / refactor) that map detected state → the phase to resume from and its actions.
+| Detected state | Resume from |
+|---|---|
+| Fix branch, no implementation artifacts | Diagnosis / triage |
+| `spec.md` or `plan.md`, no code changes | Fix implementation |
+| Code/test changes, no review artifact | Review |
+| Review artifact or optional `fix-report.md` | User verification |
+| Fix commit exists on branch | Merge decision |
 
-**Bug-fix execution**: Follow the bug-fix-workflow SKILL.md instructions exactly. Call the same prizmkit sub-commands (`/prizmkit-code-review`, `/prizmkit-committer`) at the same points.
+### Feature recovery
 
-**Special handling**:
-- If resuming from Phase 5 (Review) and tests are failing, fix test failures first (max 3 attempts). If unfixable, ask user whether to continue or restart.
-- If resuming from Phase 4 (Fix), read fix-plan.md to understand the planned approach before writing code.
+Feature recovery is usually list/pipeline driven:
 
-**Feature recovery**: Phases 3-4 are pipeline-driven. The main recovery value is avoiding re-brainstorming (Phase 1) when `.prizmkit/plans/feature-list.json` already exists.
+| Detected state | Resume from |
+|---|---|
+| No feature list and no Fast Path artifacts | Route selection or feature clarification |
+| Valid feature list, no pipeline state | `feature-pipeline-launcher` launch |
+| Feature list plus pipeline state | `feature-pipeline-launcher` status/retry or recovery script |
+| Current-workspace Fast Path artifacts | Continue `/prizmkit-implement`, review, retrospective, or commit based on state |
 
-**Refactor recovery**: Mirrors feature-workflow (brainstorm → launch → monitor).
+### Refactor recovery
 
-### 2.4 Post-Recovery Report
+Refactor recovery mirrors feature recovery but must preserve behavior checks:
 
-After all remaining phases complete, output a summary:
+| Detected state | Resume from |
+|---|---|
+| No refactor list and no Fast Path artifacts | Route selection or refactor clarification |
+| Valid refactor list, no pipeline state | `refactor-pipeline-launcher` launch |
+| Refactor list plus pipeline state | `refactor-pipeline-launcher` status/retry or recovery script |
+| Current-workspace Fast Path artifacts | Continue implementation, behavior checks, review, retrospective, or commit based on state |
 
-```
-Recovery complete.
+## Runtime Status Reference
 
-  Workflow:     bug-fix-workflow
-  Recovered from: Phase 5 (Review)
-  Completed:    code review → user verification → commit & merge
-  Preserved:    fix-plan.md, 4 code files, 1 test file
+Recovery may inspect pipeline state before choosing recovery, interactive resume, or clean retry. Use the canonical Python runtime forms:
 
-  Next steps:
-    • Check for other interrupted workflows
-    • Or start a new workflow
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py recovery run
+python3 ./.prizmkit/dev-pipeline/cli.py recovery detect
+python3 ./.prizmkit/dev-pipeline/cli.py feature status .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature <F-XXX> --clean --run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix <B-XXX> --clean --run .prizmkit/plans/bug-fix-list.json
 ```
 
-**CHECKPOINT CP-REC-2**: Workflow recovered and completed.
-
----
+Use the matching launcher for healthy status/logs/retry flows. Use clean retry only after explicit user confirmation because it discards the selected item session state.
 
 ## Error Handling
 
 | Scenario | Action |
-|----------|--------|
-| No workflow signature matches | Show guidance message, suggest original workflow skills |
-| Branch exists but artifacts are inconsistent | Trust git as ground truth, report discrepancy in detection report |
-| Test failures in existing code | Report in detection summary; user decides whether to continue |
-| Multiple workflows could match (e.g., on main but both .prizmkit/plans/feature-list.json and bug-fix artifacts exist) | Pick highest priority (bug-fix > refactor > feature), mention others in report |
-| Detection script fails | Fall back to manual detection (run individual git/file checks in bash) |
-| Bug ID not found in .prizmkit/plans/bug-fix-list.json | Continue with branch-only context; note that full bug description is unavailable |
-
----
+|---|---|
+| No workflow signature matches | Report no interrupted workflow detected and suggest original workflow skills |
+| Multiple workflows match | Present the evidence and ask which target to recover first |
+| Branch and artifacts disagree | Trust git diff/status as ground truth, but report the discrepancy |
+| Detection script fails | Fall back to manual detection checks |
+| Tests fail during diagnosis | Report failures and ask whether to continue recovery, fix tests, or stop |
+| Recovery script unavailable | Offer interactive recovery or clean retry |
+| Clean retry requested with uncommitted changes | Warn that retry may discard item session state; ask for explicit confirmation |
 
 ## Relationship to Other Skills
 
-| Skill | Relationship |
-|-------|-------------|
-| `feature-workflow` | **Recovery target** — this skill can resume interrupted feature-workflow sessions |
-| `bug-fix-workflow` | **Recovery target** — this skill can resume interrupted bug-fix-workflow sessions |
-| `refactor-workflow` | **Recovery target** — this skill can resume interrupted refactor-workflow sessions |
-| `feature-pipeline-launcher` | **Called in Phase 2.2** — launches or checks pipeline status for feature recovery |
-| `python3 ./.prizmkit/dev-pipeline/cli.py reset feature <F-XXX> --clean --run .prizmkit/plans/feature-list.json` | **Alternative** — full clean retry for pipeline failures; this skill is the smart interactive alternative |
-| `python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix <B-XXX> --clean --run .prizmkit/plans/bug-fix-list.json` | **Alternative** — full clean retry for bugfix pipeline failures |
-| `python3 ./.prizmkit/dev-pipeline/cli.py recovery run` | **Pipeline counterpart** — Python recovery that generates bootstrap prompt and spawns AI CLI session for autonomous completion |
-| `/prizmkit-code-review` | **Called in Phase 2.1** — reviews recovered bug-fix code |
-| `/prizmkit-committer` | **Called in Phase 2.1** — commits the recovered result |
-
----
+| Skill or command | Relationship |
+|---|---|
+| `feature-workflow` | Recovery target for interrupted feature workflows |
+| `bug-fix-workflow` | Recovery target for interrupted bug-fix workflows |
+| `refactor-workflow` | Recovery target for interrupted refactor workflows |
+| `feature-pipeline-launcher` | Status/logs/retry for healthy or resumable feature pipelines |
+| `bugfix-pipeline-launcher` | Status/logs/retry for healthy or resumable bugfix pipelines |
+| `refactor-pipeline-launcher` | Status/logs/retry for healthy or resumable refactor pipelines |
+| `/prizmkit-code-review` | Used when interactive recovery resumes at review |
+| `/prizmkit-committer` | Used when interactive recovery resumes at commit |
+| `python3 ./.prizmkit/dev-pipeline/cli.py recovery run` | Dedicated script recovery counterpart |
 
 ## Output
 
-- Resumed and completed workflow from the breakpoint
-- Same outputs as the original workflow would produce (commits, artifacts, state updates)
-- Recovery summary showing what was preserved vs what was re-done
+- Recovery diagnosis summary.
+- User-selected recovery target and approach.
+- Either launched recovery script, interactive continuation, clean retry command, or start-fresh handoff.
+- Final recovery summary when interactive recovery completes.