restoring-session

name	restoring-session
description	Restore session state (plan, target files, in-flight tasks) from bit issues created by the start-work skill. Use when resuming work after Claude Code restart, when the in-memory task list is empty but bit issues exist for the current branch, or when the user mentions "restore session", "repair session", "pick up where I left off", or references a prior bit-issue-tracked session.

Overview

Reverse companion of the start-work skill. start-work writes session state (plan, target files, tasks) into bit issues; restoring-session reads them back and rehydrates the in-memory TaskList.

Use when the conversation has lost task context (new session, compacted history) but the underlying bit issues still describe ongoing work.

When to invoke

• User asks to "resume", "restore", "repair", or "continue" a session.
• A new conversation starts and you suspect prior task issues exist (e.g., user references work from earlier).
• After context compaction, before resuming any non-trivial change.

Do not invoke when no prior session work exists — start-work is the right skill for fresh work.

Issue title contract (must match start-work)

Kind	Title prefix
Parent	[plan:<branch-name>#<seq>] <title>
Task	[task:<branch-name>#<seq>:<task_id>] <title>

Both labelled with session:<branch-name>.

Execution flow

Phase 1: Verify bit CLI

command -v bit >/dev/null 2>&1 && bit --version

If absent: report to user, stop. No restoration possible.

Phase 2: Determine current branch and list open issues

git branch --show-current
bit issue list --open

Optionally narrow with --label "session:<branch-name>" if the branch is known.

Phase 3: Locate the active parent issue

Scan open issues for titles starting with [plan:<branch-name>#. Two outcomes:

(a) Active parent found → proceed to Phase 4.

(b) No active parent → branch has no in-flight session. Inspect recent activity to characterize state:

bit issue list --closed --limit 10

Then view: the most recent [plan:...] closed issue (1 issue) plus every closed task issue that references it as parent (filter by title prefix [task:<that-branch>#<that-seq>:). For each selected issue run bit issue view <id> and bit issue comment list <id>. Skip plans/tasks from other branches/seqs unless the user explicitly asks.

Summarize: what was completed, when it was closed (use the latest comment timestamp if no explicit close date is exposed), any open follow-ups mentioned in comments. Then stop — do not fabricate tasks. Report to the user.

Phase 4: Load parent issue

bit issue view <parent_id>

Extract from the body:

• Branch name, worktree path, main repo path (Session Info section).
• Plan content (Plan section).

Note <branch-name>#<seq> for filtering task issues.

Phase 5: Load sub-issues (open task issues)

Filter open issues whose titles start with [task:<branch-name>#<seq>:. For each:

bit issue view <task_id>
bit issue comment list <task_id>

Extract from each body:

• Parent reference (parent: #<id>) — sanity check it matches.
• Target Files list with operation (modify | create | delete).
• Task Description.

Comments may record scope adjustments (Target Files added/excluded). Apply the latest body as authoritative; comments are audit trail only.

Phase 6: Report status to user

Before assembling the report, count closed task issues belonging to the same <branch-name>#<seq> as the parent:

bit issue list --closed --label "session:<branch-name>"

Then filter the result to titles starting with [task:<branch-name>#<seq>: — that count is what the report needs. (--label narrowing is valid for both --open and --closed lists.)

Render a compact summary before restoring tasks. Include:

• Branch + worktree path.
• Parent issue id and plan title.
• Count of open task issues, count of closed task issues for the same <branch-name>#<seq> (computed above).
• Per-open-task: task title, target files, brief description.

Ask the user to confirm if any reconstructed task looks wrong. In auto mode, proceed without confirmation but still show the summary.

Phase 7: Restore tasks via TaskCreate

For each open task issue (Phase 5), call TaskCreate with:

• subject: extracted from the issue title (the part after [task:...:<task_id>]).
• description: assembled from the issue body — Target Files block + Task Description.

Important — preserve the issue↔task linkage: the task id returned by TaskCreate is new and will not match the original <task_id> embedded in the bit issue title. Without re-linking, the TaskCompleted hook will fail to auto-close the bit issue when the restored task completes.

Re-link by updating the bit issue title to embed the new task id:

bit issue update <task_id_issue> \
  --title "[task:<branch-name>#<seq>:<NEW_task_id>] <task summary>"

Add an audit comment so the rename is traceable:

bit issue comment add <task_id_issue> \
  --body "Re-linked: task_id <OLD> → <NEW> on session restore"

Phase 8: Hand off to start-work conventions

Once tasks are restored, work continues under the start-work Cross-Session Awareness Protocol (overlap detection, scope-change updates, completion protocol). restoring-session does not own the rest of the lifecycle.

Error handling

Situation	Response
bit CLI missing	Report and stop. No restoration possible.
bit issue list returns "No issues"	Report "no prior session" and stop.
Open parent without matching open task issues	Report parent plan only; let user decide whether to recreate tasks.
Open task issue with no matching parent	Orphan — follow references/examples.md Example 3: report parent state, list options (standalone restore / parent reopen / close), pause for user input. No side effects until user replies.
Parent body malformed (missing Plan section)	Restore what is parseable; flag the missing fields in the report.
Multiple open parents on the same branch	List all with seq numbers; ask the user which session to restore.
Worktree path in parent body does not exist	Report the mismatch; do not auto-cd. User decides whether to recreate the worktree.

Prohibited (relay/network)

Same restrictions as start-work — never run: bit issue claim / unclaim / claims / watch / import, bit pr import, bit relay serve / sync, bit clone relay+*. Restoration is a read-mostly local operation.

Worked examples

See references/examples.md for concrete restoration walk-throughs:

• Single-parent active session restore
• No-active-parent (recent-history-only) report
• Orphan task issue handling
• Re-link audit trail on TaskCreate id remap