wrap-up

What this skill does

# 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:

```text
Follow-Up