recover-task

name	recover-task
description	Recover from a failed or blocked task

Skill: recover-task

Load Context

1. Scan task-state/ for tasks with state: "failed" or state: "blocked"
2. Read the task's notes field (contains failure details)
3. Read the implemented source files
4. Read relevant sections of docs/modules/<feature>/SPEC.<feature>.md

Pre-checks

• If no failed or blocked task exists → abort: "No task needs recovery."
• If multiple failed tasks exist → list them all and ask the user which one to recover.

Steps

Step 1: Diagnose the failure

Read the notes error information and classify the failure:

Type	Identifying characteristics
A. Test assertion failure	Test case expected/received mismatch
B. Compile / type error	TypeScript error, missing import
C. Runtime error	Uncaught exception, null reference, DB connection issue
D. Logic defect	Tests pass but acceptance criteria not met
E. Environment / dependency issue	Missing package, unconfigured env var, service unavailable
F. SPEC ambiguity	Unclear requirements led to wrong implementation direction

Step 2: Output root cause analysis

🔍 Root cause analysis: [task-NN] <title>

Failure type: <A–F>

Root cause:
  <specific details: which line / test / config caused the failure>

Blast radius:
  <this task only / affects other modules>

Step 3: Propose a recovery plan

Provide a concrete plan based on failure type:

A. Test assertion failure → Locate the assertion gap, check whether implementation logic matches the expectation, fix implementation (not the test)

B. Compile / type error → Locate the error file and line, fix the type definition or import path

C. Runtime error → Locate the throw site, add null checks or error boundaries, verify data initialisation

D. Logic defect → Re-read SPEC acceptance criteria, compare with implementation, correct the business logic

E. Environment / dependency issue → List the steps the user needs to take (install package, configure env var), wait for completion before continuing

F. SPEC ambiguity → List the ambiguous points, ask the user, update SPEC based on the answer, then re-implement

Confirm with the user: "Proceed with the above plan? (y/n/suggest alternative)"

Step 4: Execute recovery

Apply the fix, then re-run tests.

• Tests pass → proceed to Step 5
• Tests still fail → re-diagnose (is it a new failure?) → repeat Steps 1–4 (max 2 rounds)
• Still failing after 2 rounds → go to Error Handling

Step 5: Update task state

On successful recovery:

{
  "state": "in_progress",
  "updatedAt": "<current ISO timestamp>",
  "notes": "<summary of recovery actions taken>"
}

Inform the user: "Task recovered. Re-run /implement-task to finish, or run /verify-task to re-verify."

Error Handling

Situation	Action
Still failing after 2 recovery rounds	Output full diagnostic report, keep state as failed, note that manual intervention is needed
Recovery requires changing the SPEC	Propose the SPEC change, wait for user confirmation, update the SPEC file, then resume
blocked task waiting on an external dependency	Explain the blocker, suggest the user resolve the dependency and re-run this command

Done When

• Root cause has been clearly identified
• Recovery plan has been confirmed by the user
• Task state has changed from failed to in_progress
• Recovery summary has been recorded in notes