Proposal: a wrap-up skill for the phase boundary that has no next phase

[kriegerlukas]

The gap

Every flow in this repo ends at its own last artifact. implement ends at "commit your work". wayfinder charting ends at "Stop"; working the map has no ending step at all. grill-with-docs ends at the ADRs. handoff writes the file for the next session. Nothing owns the moment after that: the session is over, and what it leaves behind is whatever happened to be on disk and on the tracker when the human closed the window.

ask-matt's phase-boundary tree has five options, and all five assume a next phase in this or another window. The sixth case, "no next phase in this window", is the one that leaves debris, and the tree has nothing for it.

Evidence

I ran the skills on a ten-repo platform for 25 days, 2026-08-19 to 2026-09-12, and measured this in the session transcripts. Every number below is a count over those transcripts.

Sessions in the period	216
Sessions where I remembered to ask "can we close this session?"	115
Sessions that ended with nobody checking	101
Close requests in total	122
Answers that said something was still open or undone	45
Requests where the agent had to run checks before it could answer	89
Tool calls to answer, median	2
Tool calls to answer, maximum	44

So the question was worth asking better than one time in three, and answering it was real work, not a summary from memory. What the agent did once asked, counted per close request:

Action during the close-out	Requests
Pulled a clone level with its remote after a squash merge	26
Deleted a branch whose PR had merged	19
Verified PR, CI or release state on the remote	17
Removed a leftover worktree	12
Filed a follow-up issue or corrected a comment it had written	7
Closed an issue the work had completed	7
Emptied its scratch directory	7
Removed test containers or images	2

Single cases worth naming, each invisible until the question was put:

• a research branch that could not be deleted because three tracker links still pointed at its blob URLs (the case in prototype/wayfinder: "throwaway" research and prototype branches can never actually be deleted — and they keep piling up #1020)
• seven test images from a prototype, 496 MB, still on disk
• a comment the session itself had written earlier, now stale, on the ticket it was closing
• a ticket that read "ready-for-agent" after the work had merged and released (the case in /implement has no completion step, finished tickets are never marked done #508)
• two findings out of the ticket's scope, worth their own issues, filed only because I asked

None of this is a defect in any one skill. It is the absence of a step that runs after all of them.

What it costs to leave this manual

The 101 unchecked sessions are the cost. Their state is unknown, and by the time it matters the context that could tell scratch from real is gone.

• Debris is silent. A branch, a worktree or a container announces nothing. It surfaces weeks later as a puzzling git branch listing or a full disk, and nobody can say which session made it or whether it is safe to delete.
• The tracker lies. An open ticket for finished work, or a stale comment on a closed one, is read as truth by the next session. One /implement has no completion step, finished tickets are never marked done #508 commenter ran implement twice on the same ticket and the agent never noticed the work was already done.
• Decisions evaporate. A choice made in conversation and recorded nowhere is remade, sometimes differently, next time.
• Out-of-scope findings die with the window. Filing them costs a minute while the context is live and is impossible after.
• The human is the trigger. It worked in 115 sessions because I remembered to ask. It failed in 101 because I did not. A trigger that depends on the human remembering to fire it at the moment of least attention, the end of the session, is the wrong trigger. That is the same argument Wayfinder never names the context window — and "Work through the map" never ends the session #716 makes for wayfinder and implement: define a safe incomplete-run handoff #723 for implement, and it holds for every skill.

Proposal

A wrap-up skill. It verifies and reports; it takes no destructive action on its own.

1. Read the session's own primary sources: what it created, changed, or started. Branches, worktrees, files outside the repo, processes and containers, issues, PRs, comments, handoff files.
2. Check each against its intended end state, live, and sort it: landed (merged, closed, released, verified on the remote), in flight (waiting on review, CI, a nightly, another party), debris (a branch after its merge, a worktree, a temp file, a stale comment the session wrote), decided but unrecorded (a decision from the conversation that landed nowhere durable), out of scope (a finding that deserves its own issue).
3. Report the sorted list. Propose one action per item. Act only on what the user confirms; the repo's issue-tracker doc from setup-matt-pocock-skills decides how tracker state is written, so a team that closes tickets from the merge keeps doing that.
4. End with the one line that opens the next session, naming the skill it should call.

Sketch, in the register of handoff:

---
name: wrap-up
description: Close out a session. Use when the user wants to end, close, or wrap up the session, or when a skill's last step is done and nothing follows in this window.
---

The session is ending. Everything it leaves behind is either **landed**, **in flight**, or **debris**, and the human is about to lose the context that tells which is which.

1. List what this session created, changed, or started: branches, worktrees, files outside the repo, processes, issues, PRs, comments, handoff files.
2. Verify each against its intended end state, live: the remote, the tracker, the filesystem. Do not report from memory.
3. Sort the list: landed, in flight (and on whom), debris, decided but recorded nowhere, surfaced but out of scope.
4. Report it. Propose one action per item and act on what the user confirms. Tracker state follows the repo's issue-tracker doc.
5. End with one line that opens the next session, naming the skill to call.

Invocation

Two options. I lean to the first.

Model-invoked. The test in .agents/invocation.md is "could the model usefully reach for this autonomously?". It could: #716 wants wayfinder to end the session after a resolution, and #723 wants implement to exit cleanly when it cannot finish. A user-invoked skill can never be reached by either, so each would have to inline its own copy of the close-out. Model-invoked, both become one line: call the Skill tool with wrap-up. The risk of a spurious auto-fire is one unwanted report, since the skill acts only on what the user confirms. The decision that the session is over stays with the human either way; the skill never clears or compacts.

User-invoked. Keeps the repo's stance from #906 that boundaries are the user's decision, at the cost of #716 and #723 each carrying their own ending.

Redundancy check

• handoff buys portability for a next session. It verifies nothing, cleans nothing, files nothing. wrap-up runs before it or instead of it.
• retro (in-progress) improves the agent's environment after a session. Different question.
• code-review reviews the diff. Debris is by definition outside the diff.
• /implement has no completion step, finished tickets are never marked done #508, /implement does not update ticket status or leave session context on completion #990, Add issue-tracker closeout step to implement skill #466: tracker state after implement. Add issue-tracker closeout step to implement skill #466 was closed because teams differ on it. wrap-up reports the stale state and lets the tracker doc and the user decide, which is the same stance.
• Wayfinder never names the context window — and "Work through the map" never ends the session #716, implement: define a safe incomplete-run handoff #723: an ending for wayfinder and implement. Both become a call to this skill.
• prototype/wayfinder: "throwaway" research and prototype branches can never actually be deleted — and they keep piling up #1020, handoff skill: save into a gitignored docs/handoffs/ instead of OS temp (+ optional self-delete) #482: branches and handoff files that pile up. Both are debris this skill surfaces.

Out of scope

• Writing tracker state automatically. Add issue-tracker closeout step to implement skill #466 settled that.
• Redefining "done" for implement. implement: make the completion criterion explicit #485 settled that.
• Worktree creation, temp-file locations, /clear and /compact themselves. Harness concerns, per Ask if user wants to work in git worktree on the implement skill #473 and Wayfinder leaving files in the project root #497.

Acceptance criteria

• skills/productivity/wrap-up/SKILL.md exists with the steps above and an agents/openai.yaml beside it.
• Run after a session that merged a PR from a scratch worktree, it reports the worktree and branch as debris and the PR as landed, verified against the remote.
• Run after a session that decided something in conversation only, it lists the decision under "decided but unrecorded" with a proposed home.
• It writes nothing to the tracker and deletes nothing without a confirmation.
• Its last line is a runnable prompt for the next session naming a skill.
• ask-matt's phase-boundaries section names it as the option for the boundary with no next phase.

[dajiaohuang]

I prepared a tested implementation on my fork: dajiaohuang/skills@main...feat/wrap-up-skill (commit f771b553764c4da6ea4daf16ae048591b98fcf82). It adds the model-invoked wrap-up skill, five outcome buckets, confirmation gates, documentation, and the no-next-phase wiring; plugin validation, acceptance checks, JSON checks, and diff-check pass. I could not open an upstream PR because this fork belongs to the vercel-labs/skills network rather than mattpocock/skills. If this direction fits, please invite me or indicate the correct fork route for submission.