jacobpevans/wrap-up

Post-Session Wrap-Up

State warning: Branch state, remote tracking, TaskList contents, and plan checklist state all change between invocations. Re-run every git/gh command and re-call TaskList from Step 0; never trust prior outputs from this conversation.

/wrap-up has two paths. Step 0 decides which one runs.

| Step 0 outcome | Path | | ------------------------ | ----------------------------------------------------------------- | | Plan complete OR no plan | Path A — refresh repo, retrospective, clean branches, follow-up prompt | | Plan incomplete | Path B — emit resume blocks; skip Path A cleanup entirely |

The purge-pr focused mode (bottom of this file) bypasses Step 0 entirely.

Step 0: Determine session state

There are two distinct things to keep straight here:

1. The plan file itself — a real markdown file at <HOME>/.claude/plans/<slug>.md. Plan mode writes it; the assistant reads and edits it during implementation; it persists on disk after the session ends. The file is the canonical store of the plan's content — the checklist items, the context, the files to change. Step 0b reads it.
2. The binding from session → plan file — i.e. which of the many files under ~/.claude/plans/ is the one this session is working against. That binding is the hard problem under parallelism, because many sessions may be writing files into the same directory concurrently. Filesystem heuristics (mtime, ctime, filename slug) all race. Step 0a resolves the binding using the only signal that is scoped to one session: the conversation transcript.

0a. Resolve which plan file belongs to this session

When a session enters plan mode, the harness injects a <system-reminder> into the conversation containing a literal ## Plan File Info: block that names the plan file's absolute path (shape: <HOME>/.claude/plans/<slug>.md). That reminder is session-local — it appears only in this session's transcript — and it persists in conversation context after plan mode exits. So scanning the conversation for that reminder is the deterministic way to find the plan path for this session, no matter how many other sessions are running.

To resolve:

1. Scan the current conversation context for <system-reminder> blocks whose body contains a path matching the regex [^[:space:]]+/\.claude/plans/[^[:space:]]+\.md — any absolute path ending under .claude/plans/, not just one specific user's home directory.
2. If multiple matches exist (plan mode was re-entered against a different file), take the most recently quoted one — latest in conversation order, not by file mtime.
3. If zero matches exist, this session never entered plan mode. There is no plan file for this session. Treat the plan checklist as empty; the completion decision then rests entirely on TaskList.

Never search ~/.claude/plans/ by mtime, ctime, or filename pattern. Never guess which plan belongs to this session.

0b. Read the resolved plan file

If 0a returned a path, Read that exact file. Extract:

• GitHub-style checkboxes (- [ ] / - [x]) with their line numbers
• Numbered or bulleted step lists under headings such as "Step", "Phase", "Tasks", or "Files to Change", but only when an item has an unambiguous done/not-done signal in the file itself or in this session's conversation

0c. Read the harness TaskList

Call TaskList. It is intrinsically session-scoped by the harness — no disambiguation needed. Inspect status per task.

0d. Conversation evidence for ambiguous items

For checklist items without an explicit [x], decide based on this session's actual evidence: file edits the assistant performed, command output, test results visible in this conversation. Be conservative: if in doubt, treat as incomplete. Never consult other sessions' transcripts.

Completion rule

The plan is complete iff:

• every TaskList task has status == "completed" (or the list is empty), AND
• every plan-file checklist item is checked or has clear conversation evidence of completion (or there is no plan file at all).

If either set has unfinished items → Path B. Otherwise → Path A.

---

Path A — Clean wrap-up (plan complete or absent)

Run Steps A1 and A2 in parallel (they are independent). Step A3 starts as soon as Step A1 completes (depends on its remote prune). Step A4 runs after all prior steps finish. Provide a summary of actions taken.

A1. Refresh Repository

Invoke /refresh-repo to:

• Check merge-readiness of any remaining open PRs
• Sync local main with remote
• Clean up stale worktrees (merged PRs, [gone] remote branches)
• Report repository state

A2. Quick Retrospective

Invoke /retrospecting quick to capture a brief session retrospective:

• Git history analysis (commits, files changed)
• Session efficiency metrics
• Key decisions and outcomes
• Actionable improvements

Requires: claude-retrospective plugin (external). If not installed, skip this step and note it was skipped.

A3. Clean Gone Branches

Invoke /clean_gone to remove any local branches whose remote tracking branch has been deleted:

• Identify branches marked [gone]
• Remove associated worktrees
• Delete the local branches

Requires: commit-commands plugin (external). If not installed, skip this step and note it was skipped.

A4. Follow-Up Session Prompt

After the retrospective completes (or is skipped), generate a follow-up prompt for the next session.

Scan the conversation history in reverse chronological order, stopping when no new items appear for ~10 consecutive messages. Most unfinished forward-looking work surfaces near the end of a session.

A4a + A4b: Gather Unfinished Work and Session Issues (parallel)

Scan simultaneously for both categories:

Unfinished work (A4a):

• Incomplete tasks — anything started but not finished, or marked as TODO/FIXME during this session
• Items needing production-readiness — code that works but needs hardening, tests, error handling, or documentation before it is production-ready
• Future work identified — any issues, improvements, or ideas called out during the session as "later", "follow-up", "out of scope", or similar

Session issues (A4b):

• Errors (build failures, test failures, runtime errors)
• Warnings (linter warnings, deprecation notices, compiler warnings)
• Flaky or unreliable behavior observed
• Workarounds applied that should be properly fixed
• Tool or dependency issues encountered

A4c: Triage Into Prompt vs GitHub Issues

Split the gathered items into two buckets:

1. Next-session prompt — items small enough to complete in a single focused session (roughly 1–3 tasks). Combine related items where possible.
2. GitHub issues — everything else. Before recommending new issues:
   • Search existing open issues with gh issue list --state open --json number,title,url for duplicates. Capture the url field — every issue or PR referenced in the output below must be a full URL the user can click, never a bare #123.
   • If a matching issue exists, recommend updating it instead of creating a new one
   • Consolidate related items into a single issue when they share a root cause
   • Each recommended issue should include a clear title, description, and acceptance criteria

URL rule (applies to every section that mentions a PR or issue): always emit the full https://github.com/<owner>/<repo>/(issues|pull)/<n> URL on first reference. Bare #123 or PR 123 references are forbidden because they force the reader to guess the repo from context. If the same number appears again in the same block, a bare #123 is acceptable as a short reference after the URL has been shown once.

A4d: Output the Follow-Up Prompt

Present the results in this format:

Follow-Up Session Prompt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommended prompt for next session:
──────────────────────────────
<A ready-to-paste prompt covering the 1–3 quick-win tasks identified above. Be specific: reference file paths, function names, error messages, etc.>
──────────────────────────────

Recommended GitHub Issues:
──────────────────────────────
1. <Title> — <one-line summary> [new | update https://github.com/<owner>/<repo>/issues/123]
2. <Title> — <one-line summary> [new | update https://github.com/<owner>/<repo>/pull/456]
   ...
──────────────────────────────

Session Issues Log:
──────────────────────────────
- <error/warning/issue encountered, with context>
- ...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If no follow-up items are found, state that explicitly — do not fabricate work.

Path A Summary

Wrap-Up Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Plan:             <path or "none">
  Plan status:      complete
  Refresh:          done or skipped
  Retrospective:    done or skipped
  Branch cleanup:   done or skipped
  Follow-up prompt: done or skipped
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Path B — Resume blocks (plan incomplete)

Skip Path A entirely. Skipping is intentional: /refresh-repo prunes stale worktrees, which would delete the in-flight worktree the user needs to resume in.

B1. Group remaining items

Collect every unfinished item from Step 0 (plan checklist items still unchecked + TaskList tasks with status != "completed") and group them with judgement, not by repo alone:

• Items touching the same repo AND sharing one coherent goal → one block
• Items touching the same repo but addressing unrelated concerns → separate blocks, so a fresh session is not polluted by an unrelated thread
• Items touching different repos → separate blocks
• If block X must finish before block Y can start, order X first and record the dependency on Y's header

For each block, resolve the working directory:

1. If the block's tasks name file paths inside a worktree, use that worktree root (git -C <path> rev-parse --show-toplevel).
2. Otherwise, derive from the plan file's "Files to Change" / "File to modify" section.
3. Last resort: the cwd at wrap-up time.

B2. Emit each block

Print blocks in dependency order. Each block must be copy-pasteable into a fresh terminal + new Claude session and runnable cold — the new session sees none of this conversation.

Resume Block N of M — <short label>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Working dir:
  cd <absolute worktree path>

Resume prompt:
──────────────────────────────
<Self-contained prompt for this block. Must include:
 - Plan file path so the new session can re-enter plan mode against it:
   ~/.claude/plans/<slug>.md (use the resolved absolute path emitted by the
   plan-mode system reminder, not this literal example)
 - Exact remaining checklist items with plan-file line numbers
 - Any TaskList task IDs still pending and their subjects
 - Relevant file paths from the plan
 - Full URLs for any referenced PR or issue (e.g.
   https://github.com/<owner>/<repo>/pull/123) — never a bare #123
 - One-line "already done this session" so the new session does not redo work>
──────────────────────────────

Depends on: <block id, or "none">
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The resume prompt restates the goal explicitly. It must never say "continue what you were doing" or reference "this session" — the new session has no memory of it.

Path B Summary

After all resume blocks, print:

Wrap-Up Summary (incomplete)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Plan:             <plan-file path or "none">
  Plan status:      incomplete (<n> open checklist items, <m> open TaskList items)
  Refresh:          skipped — plan incomplete
  Retrospective:    skipped — plan incomplete
  Branch cleanup:   skipped — plan incomplete
  Resume blocks:    <count>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Focused Mode: Purge a Specific PR

Invoke as /wrap-up purge-pr <PR_NUMBER> to close one PR and atomically purge all local state for its branch. Bypasses Step 0 and both paths above. Use when you know a PR should be closed (obsolete duplicate, workaround anti-pattern, abandoned work) and you want the local trace gone in one operation.

Sequence:

1. Capture the branch name first — step 2 deletes the remote ref, so capture before that runs: gh pr view <PR_NUMBER> --repo <owner>/<repo> --json headRefName --jq '.headRefName'.
2. Close the PR and delete the remote branch in one call: gh pr close <PR_NUMBER> --repo <owner>/<repo> --comment "<reason>" --delete-branch.
3. If the current worktree IS the captured branch's, git switch main first so step 4 can remove it.
4. Find the worktree path via git worktree list matching the captured branch, then git worktree remove <path> --force if present, and git branch -D <branch>.

Closes the gap where gh pr close --delete-branch removes only the remote branch and leaves the local branch + worktree behind. Reuses the worktree-removal command shape from /troubleshoot-worktree and aligns with /clean_gone's post-removal state.

Related Skills

• refresh-repo (github-workflows) — PR readiness check + repo sync + worktree cleanup (Path A Step A1 dependency); also provides --sweep and --prune-stale modes
• shape-issues (github-workflows) — Shape and create well-structured GitHub issues
• troubleshoot-worktree (git-workflows) — Worktree-removal command shape reused by purge-pr mode
• pr-standards (git-standards) — Workaround Classification rubric used to decide when purge-pr is the right action