prizmkit 1.0.144 → 1.0.148

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

@@ -0,0 +1,428 @@
+---
+name: "recovery-workflow"
+description: "Recover and resume interrupted feature pipeline sessions. Detects partial work (code changes, spec/plan artifacts, branch state, test results) from failed or interrupted sessions and intelligently resumes from the correct phase — instead of discarding everything and restarting from scratch. Use this skill whenever a pipeline session fails mid-execution, times out, gets interrupted, or when the user wants to salvage partial work from a failed feature. Trigger on: 'recover feature', 'resume session', 'continue from where it stopped', 'salvage partial work', 'fix failed feature', 'session interrupted', 'recover F-XXX', 'resume F-XXX', 'continue F-XXX', 'feature stuck', 'pick up where it left off', 'session timed out', 'don't want to restart from scratch', 'token limit exceeded'. (project)"
+---
+
+# Recovery Workflow
+
+Intelligently recover and resume interrupted feature pipeline sessions. Instead of discarding partial work and restarting from scratch (which wastes tokens and time), this skill inspects the actual filesystem state — code changes, artifacts, git branches, test results — and continues from the right point.
+
+## When to Use
+
+User says:
+- "Recover F-007", "Resume F-007", "Continue F-007 from where it stopped"
+- "Feature session failed/timed out, salvage the work"
+- "Pipeline interrupted, don't want to restart from scratch"
+- "F-003 is stuck, pick up where it left off"
+- "Session timed out but there's code already written"
+
+**Do NOT use when:**
+- User wants a clean retry from scratch → `retry-feature.sh` or `reset-feature.sh --clean --run`
+- Pipeline is still running normally → `dev-pipeline-launcher` (Intent B: Check Status)
+- User wants to fix a specific bug → `bug-fix-workflow`
+- Feature never started (no state at all) → `dev-pipeline-launcher` (Intent E: Retry)
+
+## Why This Skill Exists
+
+Current retry tools have a fundamental limitation:
+
+| Tool | What it does | What's lost |
+|------|-------------|-------------|
+| `retry-feature.sh` | Cleans all artifacts, resets status, spawns fresh session | All code changes, spec, plan — everything |
+| `reset-feature.sh --clean --run` | Even more thorough clean + retry | Same, plus session history |
+| `run.sh --resume-phase N` | Tells new session "start from phase N" via prompt | Better, but doesn't inspect actual worktree state — the new AI session has no memory of what was done |
+
+The gap: when a session is interrupted mid-implementation, the **worktree already has real code changes** — possibly a spec, plan, partial or complete implementation, even passing tests. Discarding all of this wastes significant tokens and time. This skill bridges that gap by inspecting the actual filesystem state and resuming intelligently within the current interactive session.
+
+---
+
+## Overview
+
+```
+recovery-workflow <feature-id>
+   │
+   ├── Phase 0: Identify feature and gather context
+   │
+   ├── Phase 1: Detect state (artifacts, code, tests, branch)
+   │
+   ├── Phase 2: Diagnose and present recovery options
+   │
+   └── Phase 3: Execute recovery (chain remaining prizmkit skills)
+```
+
+## Input
+
+| Input | Required | Example |
+|-------|----------|---------|
+| Feature ID | Yes | `F-007` |
+| Feature list path | No (default: `feature-list.json`) | `my-features.json` |
+
+---
+
+## Phase 0: Feature Identification
+
+**Goal**: Locate the feature and its context.
+
+1. **Parse feature ID** from user input (e.g., "recover F-007", "resume F-007")
+2. **Read feature-list.json** to get feature metadata:
+   ```bash
+   python3 -c "
+   import json, re
+   with open('feature-list.json') as f:
+       data = json.load(f)
+   for feat in data.get('features', []):
+       if feat.get('id') == 'F-007':
+           print(json.dumps(feat, indent=2))
+   "
+   ```
+3. **Compute feature slug** (same algorithm the pipeline uses):
+   ```python
+   # F-007 + "User Authentication" → "007-user-authentication"
+   numeric = feature_id.replace('F-', '').zfill(3)
+   slug = re.sub(r'[^a-z0-9\s-]', '', title.lower())
+   slug = re.sub(r'[\s]+', '-', slug.strip()).strip('-')
+   slug = f"{numeric}-{slug}"
+   ```
+
+If the feature is not found, ask the user for the correct ID or file path.
+
+---
+
+## Phase 1: State Detection
+
+**Goal**: Build a complete picture of what exists from the interrupted session.
+
+Run the detection script:
+
+```bash
+python3 ${SKILL_DIR}/scripts/detect-recovery-state.py \
+  --feature-id <FEATURE_ID> \
+  --feature-list feature-list.json
+```
+
+The script scans four categories of state and outputs structured JSON:
+
+### 1.1 Pipeline State
+- `dev-pipeline/state/features/{FEATURE_ID}/status.json` — pipeline tracking status, retry count, session history
+- Last session directory — path for log inspection
+
+### 1.2 PrizmKit Artifacts
+- `.prizmkit/specs/{slug}/spec.md` — specification generated?
+- `.prizmkit/specs/{slug}/plan.md` — plan generated?
+- If plan.md exists: count completed vs total tasks (look for `[x]` vs `[ ]` checkboxes)
+
+### 1.3 Git State
+- **Feature branch**: does `feat/{slug}` exist?
+- **Current branch**: are we already on the feature branch?
+- **Uncommitted changes**: `git diff --stat` (working tree changes)
+- **Staged changes**: `git diff --cached --stat`
+- **Commits ahead of main**: `git log main..HEAD --oneline`
+
+### 1.4 Code Changes
+- Number of modified/added/deleted files
+- Which directories were touched
+- Whether test files were created/modified
+
+### Detection Output
+
+The script produces a structured JSON report:
+
+```json
+{
+  "feature_id": "F-007",
+  "feature_title": "User Authentication",
+  "feature_slug": "007-user-authentication",
+  "pipeline": {
+    "status": "failed",
+    "retry_count": 1,
+    "last_session_id": "F-007-20260329101500",
+    "last_session_dir": "dev-pipeline/state/features/F-007/sessions/F-007-20260329101500"
+  },
+  "artifacts": {
+    "spec_exists": true,
+    "plan_exists": true,
+    "spec_path": ".prizmkit/specs/007-user-authentication/spec.md",
+    "plan_path": ".prizmkit/specs/007-user-authentication/plan.md",
+    "plan_tasks_total": 5,
+    "plan_tasks_completed": 3
+  },
+  "git": {
+    "feature_branch": "feat/007-user-authentication",
+    "branch_exists": true,
+    "on_feature_branch": true,
+    "uncommitted_files": 8,
+    "staged_files": 0,
+    "commits_ahead_of_main": 0
+  },
+  "code": {
+    "files_modified": 6,
+    "files_added": 4,
+    "test_files_touched": 2,
+    "directories_touched": ["src/auth/", "src/middleware/", "tests/"]
+  },
+  "recovery": {
+    "recommended_action": "continue_implementation",
+    "recommended_phase": "implement",
+    "reason": "spec and plan exist, 3/5 plan tasks completed, code changes present",
+    "remaining_work": "2 tasks + review + commit"
+  }
+}
+```
+
+**CHECKPOINT CP-RW-0**: State detection complete, structured report available.
+
+---
+
+## Phase 2: Diagnosis & Recovery Options
+
+**Goal**: Present findings to user and agree on a recovery strategy.
+
+### 2.1 Present Discovery Summary
+
+Read the detection script output and show the user a clear summary:
+
+```
+═══════════════════════════════════════════════════
+  Recovery Report: F-007 — User Authentication
+═══════════════════════════════════════════════════
+
+  Pipeline Status:  FAILED (retry 1)
+  Feature Branch:   feat/007-user-authentication
+
+  Artifacts Found:
+    ✓ spec.md (specification)
+    ✓ plan.md (5 tasks, 3 completed)
+    ✓ Code changes (10 files — 6 modified, 4 new)
+    ✓ Test files (2 found)
+
+  Recommended: Continue implementation
+  Remaining:   2 tasks + review + commit
+═══════════════════════════════════════════════════
+```
+
+### 2.2 Run Tests (if code changes exist)
+
+Before presenting options, run the project's test suite to understand the health of existing code:
+
+```bash
+# detect test command from .prizmkit/config.json or package.json
+npm test   # or the appropriate test command
+```
+
+Include test results in the summary:
+- How many tests pass/fail
+- If there are failures — which tests and why
+
+### 2.3 Present Recovery Options
+
+Based on the detected state, offer the appropriate options. The most common scenarios:
+
+**Scenario A: Implementation in progress** (spec + plan + code changes)
+Most common case — session died mid-implementation.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Smart Resume** (recommended) | Fix test failures if any, complete remaining plan tasks, then review → commit |
+| **(b) Review & Commit Only** | If implementation looks complete (all tasks done, tests passing), skip to code review |
+| **(c) Re-implement from Plan** | Keep spec and plan, discard code changes, re-implement. Useful if partial code is low quality |
+| **(d) Clean Restart** | Discard everything, start from scratch (equivalent to `reset-feature.sh --clean --run`) |
+
+**Scenario B: Only planning artifacts** (spec/plan exist, no code changes)
+Session died during or after planning, before implementation started.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Start Implementation** (recommended) | Plan is ready, begin implementing |
+| **(b) Re-plan** | Keep spec, regenerate plan (useful if plan was incomplete or poor) |
+| **(c) Clean Restart** | Discard everything and start over |
+
+**Scenario C: Code changes but no artifacts** (git changes, no .prizmkit artifacts)
+Unusual — might be manual work or artifacts were cleaned.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Adopt & Continue** | Read existing code, proceed to review + commit |
+| **(b) Clean Restart** | Discard and restart |
+
+**Scenario D: Already committed** (feature branch has commits ahead of main)
+Session completed implementation but didn't finish post-commit steps.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Complete Post-commit** (recommended) | Run code review, retrospective, handle merge |
+| **(b) Clean Restart** | Discard and restart |
+
+**Scenario E: No state found** (no branch, no artifacts, no code)
+Feature was never executed or was fully cleaned.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Run from Scratch** | Suggest using `dev-pipeline-launcher` (Intent E) or `retry-feature.sh` instead |
+
+Ask the user to choose. Default to the recommended option.
+
+**CHECKPOINT CP-RW-1**: User confirmed recovery strategy.
+
+---
+
+## Phase 3: Execute Recovery
+
+**Goal**: Execute the remaining phases based on the user's chosen strategy.
+
+### 3.0 Branch Setup
+
+Ensure we're on the right branch:
+
+```bash
+# If feature branch exists but we're not on it:
+git checkout feat/{slug}
+
+# If no feature branch but code changes are on current branch:
+git checkout -b feat/{slug}
+```
+
+### 3.1 Read Existing Artifacts
+
+Load the artifacts that were preserved, so we have full context:
+
+1. **Read spec.md** (if exists) — understand what this feature should do
+2. **Read plan.md** (if exists) — understand the implementation plan and task breakdown
+3. **Scan code changes** — `git diff main --stat` to understand what was already done
+4. **Read relevant `.prizm-docs/`** — load project context (L0 root, relevant L1)
+
+This step replaces the Phase 0-2 that the pipeline would have done (project bootstrap, context building, planning). The artifacts serve as memory of the interrupted session.
+
+### 3.2 Fix Existing Test Failures (if any)
+
+If tests are failing from the interrupted session, fix them first. Continuing implementation on top of a broken state compounds errors.
+
+1. Read the test failure output
+2. Read the relevant source files
+3. Apply minimal fixes to make tests pass
+4. Verify: run test suite → all green
+
+If failures cannot be fixed after 3 attempts, ask the user whether to:
+- Continue anyway (if failures are unrelated to this feature)
+- Switch to "Re-implement from Plan" strategy
+- Clean restart
+
+### 3.3 Continue Implementation
+
+If plan.md exists with incomplete tasks:
+
+1. **Read plan.md** and identify remaining tasks — look for unchecked `[ ]` items in the Tasks section
+2. **For each remaining task**:
+   - Read the task description from plan.md
+   - Implement the change following the same approach as `/prizmkit-implement`
+   - Run full test suite after each task
+   - Mark task as complete `[x]` in plan.md
+3. After all tasks complete → full test suite must pass
+
+If no plan.md exists but code changes are present (Scenario C), skip this step — go straight to review.
+
+### 3.4 Code Review
+
+Invoke `/prizmkit-code-review` on all changes:
+- Review scope: all files modified/added relative to main branch (`git diff main --stat`)
+- If review returns NEEDS_FIXES → apply fixes, re-review (max 2 rounds)
+- If review returns PASS or PASS_WITH_WARNINGS → proceed
+
+### 3.5 User Verification
+
+Ask user: "Implementation recovered and reviewed. Verify before committing?"
+- **(a) Run the app** → suggest and start the dev server
+- **(b) Run a specific command** → execute what the user specifies
+- **(c) Skip** → proceed directly to commit
+
+If user reports issues: return to 3.3 (max 2 additional rounds).
+
+### 3.6 Retrospective & Commit
+
+1. **Invoke `/prizmkit-retrospective`** — update `.prizm-docs/` for structural changes caused by this feature
+2. **Invoke `/prizmkit-committer`** — commit with `feat(<scope>): <description>` prefix
+3. **Update pipeline state** — mark feature as completed:
+   ```bash
+   python3 dev-pipeline/scripts/update-feature-status.py \
+     --feature-list feature-list.json \
+     --state-dir dev-pipeline/state \
+     --feature-id <FEATURE_ID> \
+     --action complete
+   ```
+
+### 3.7 Post-Recovery
+
+1. **Ask merge preference**:
+   - (a) Merge to main and delete feature branch
+   - (b) Keep feature branch for PR review
+   - (c) Decide later
+
+2. **Report completion**:
+   ```
+   Recovery complete: F-007 — User Authentication
+
+   Recovered from: implementation phase (3/5 tasks done)
+   Completed: 2 remaining tasks + test fixes + review + commit
+   Work preserved: spec.md, plan.md, 3 completed tasks
+
+   Next: Check pipeline status for remaining features,
+         or invoke /recovery-workflow for another failed feature.
+   ```
+
+3. **Suggest next steps**:
+   - If other features are pending/failed → offer to check pipeline status or recover another
+   - If this was the last feature → suggest integration verification
+
+**CHECKPOINT CP-RW-2**: Feature recovered, committed, and pipeline state updated.
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Feature ID not found in feature-list.json | Ask user for correct ID or file path |
+| No state to recover (never executed) | Inform user, suggest `dev-pipeline-launcher` instead |
+| Feature branch was deleted | Check if changes exist elsewhere; if not, offer clean start |
+| Merge conflicts on feature branch | Show conflicts, help resolve before continuing |
+| Test failures unfixable after 3 attempts | Escalate to user, offer alternative strategies |
+| Code quality too low to salvage | Recommend re-implement from plan |
+| Pipeline state file inconsistent with git | Trust git and filesystem over status.json — git is the ground truth |
+| detection script fails | Fall back to manual detection (Phase 1 checks can be done individually via bash) |
+
+---
+
+## Relationship to Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `dev-pipeline-launcher` | **Upstream** — launcher can suggest this skill when features fail; this skill updates pipeline state after recovery |
+| `retry-feature.sh` | **Alternative** — full clean retry; this skill is the smart alternative |
+| `reset-feature.sh` | **Used by option (d)** — clean restart delegates to reset-feature |
+| `/prizmkit-implement` | **Approach shared in Phase 3.3** — same implementation methodology |
+| `/prizmkit-code-review` | **Called in Phase 3.4** — reviews recovered code |
+| `/prizmkit-committer` | **Called in Phase 3.6** — commits the result |
+| `/prizmkit-retrospective` | **Called in Phase 3.6** — updates .prizm-docs/ |
+| `feature-workflow` | **Sibling** — feature-workflow builds new features; this skill salvages interrupted ones |
+
+---
+
+## Comparison with Existing Recovery Tools
+
+| Dimension | recovery-workflow | retry-feature.sh | reset + run | run.sh --resume-phase |
+|-----------|------------------|-------------------|-------------|----------------------|
+| State inspection | Deep (git + artifacts + tests) | None | None | None |
+| Preserves code | Yes | No (cleans) | No (cleans) | Prompt-level only |
+| Preserves artifacts | Yes (selective) | No | No | Prompt-level |
+| Runs tests first | Yes | No | No | No |
+| User choice | Multiple strategies | Always clean | Always clean | Fixed phase number |
+| Execution mode | Interactive (in-session) | Spawns new session | Spawns new session | Spawns new session |
+| Token efficiency | High (skips done work) | Low (redo all) | Low (redo all) | Medium |
+| Context continuity | Full (reads existing artifacts) | None (fresh AI session) | None | Partial |
+
+## Output
+
+- Recovered and completed feature implementation
+- Updated pipeline state (feature marked complete)
+- Git commit with `feat(<scope>):` prefix
+- Updated `.prizm-docs/` (via retrospective)
+- Recovery summary showing what was salvaged vs what was re-done