How To Recover And Troubleshoot

Use this guide when Slipway reports blockers, stale evidence, missing artifacts, adapter drift, or confusing local state.

The rule is simple: inspect first, then follow the named recovery path. Do not hand-edit lifecycle authority, evidence verdicts, timestamps, or runtime task proof.

Inspect Without Mutating

These commands are the primary Diagnostic JSON surfaces for recovery work.

Run these from the governed worktree:

git status --short --branch
slipway status --json
slipway validate
slipway next --json --diagnostics

Use status for the lifecycle snapshot, validate for gate readiness, and next --diagnostics for the actionable blocker or skill handoff.

Run Doctor Output

When local state looks inconsistent:

slipway health --doctor --json

Read applied_repairs, unrepaired_drift, and the named next_action fields. Only run repair when the doctor output matches the issue you see:

slipway repair --json

repair is for bounded local integrity issues. It is not a way to force a change through lifecycle gates.

Missing Or Stale Task Evidence

Symptoms usually appear in validate or next --json --diagnostics as missing runtime task evidence, stale execution summaries, or mismatched freshness inputs.

Safe recovery:

Identify the task and required evidence path in the JSON output.
Rerun the owning implementation or wave-orchestration handoff.
Record task evidence through the owning Slipway command or generated skill.
Rerun slipway validate.

Do not write files under .git/slipway/runtime/changes/<slug>/evidence/ by hand.

Missing Artifact Substance

If a governed artifact is missing, placeholder-only, or structurally invalid, use the authoring surface named by recovery output:

slipway instructions requirements --json
slipway instructions decision --json
slipway instructions research --json
slipway instructions tasks --json
slipway instructions assurance --json

The command gives the template and quality bar. The authoring skill or human must write real artifact content from the current objective and source facts. Copying the template is rejected.

Review Findings

If review found actionable issues, do not mix review and repair in the same context. Use the repair surface:

slipway fix --json

Give the returned repair contract to a fresh-context repair agent. After repair, rerun the affected selected reviewers and then rerun:

slipway review --json
slipway validate

Selected reviewer evidence must be fresh for the current diff, planning artifacts, and execution summary inputs. The one authoritative full suite is run by the terminal ship-verification gate after the peers converge, not from a peer-shared keystone.

Scope Drift

If scope_contract reports changed files outside a task’s target_files, choose one safe path:

Revert or move the out-of-scope change yourself if it was accidental.
Amend the same-intent task or artifact through the surfaced Slipway planning or review path.
Start a new governed change if the objective changed.

Do not hide a changed file by editing evidence.

Dirty Worktrees After Done

slipway done can archive a done-ready change while returning a worktree_dirty_warning for non-active files that still need committing.

Safe recovery:

git status --short
git diff --check

Commit the intended implementation diff together with the archived Slipway record. The active bundle is rewritten into artifacts/changes/archived/<slug>/.

Adapter Drift

If generated AI-tool commands or skills look stale:

slipway init --refresh

Then inspect the diff:

git status --short .claude .codex .cursor .opencode

Generated adapters are handoff aids. If adapter behavior and CLI behavior disagree, trust the current-worktree CLI output and refresh the generated files.

Recovery Quick Reference

Symptom	Inspect	Safe action
Unsure what to do next	`slipway next --json --diagnostics`	Follow returned skill, blocker, or command.
Gate says stale evidence	`slipway validate`	Rerun the owning stage, reviewer, or task evidence path.
Local state looks corrupt	`slipway health --doctor --json`	Run `slipway repair --json` only for named bounded repairs.
Artifact is placeholder-only	`slipway instructions <artifact> --json`	Author real content and rerun validation.
Review found issues	`slipway fix --json`	Repair in a fresh context, rerun affected reviewers.
Adapter files are stale	`slipway init --refresh`	Inspect generated diff and preserve user-owned files.