close-session
Wrap up a work session in one pass — find the issue-tracker tickets the session touched (Linear) and update them, or propose a new one when the work has none; mark the Slack threads that announced the
SKILL.mdplugins/fabien-skills/skills/close-session/SKILL.md
GitHub/close-session — wrap up a session
Four jobs, one confirmation:
- Tickets — update the tickets this session worked on, or propose one when the work has none.
- Slack — react on the thread that announced each merged PR.
- Docs — run
capture-docson a fresh branch and open a docs PR. - Cleanup — remove the scratch data this session created.
The conversation is the primary source. Same rule as capture-docs: do not re-research the
codebase. Use cheap signals (gh, git, the MCP tools) to confirm state, never to rediscover the
session's work.
Step 0 — Load config
Config file: .claude/.config/close-session.json. Walk up from the cwd to $HOME (inclusive),
first match wins; $CLOSE_SESSION_CONFIG overrides the walk. Every key is optional.
A job runs only when it is set up: Tickets needs a linear section and a tracker tool
connected, Slack needs a slack section and a Slack tool connected. Docs and Cleanup
always run. A job that does not run is silent: not gathered, not in the plan, not in the report,
no "skipped" or "not configured" line. Inside a running job, a missing key falls back to its
default (no linear.team: ask for a team only when a ticket is actually created).
{
"linear": {
"team": "ENG", // team key for new tickets
"labels": ["platform"], // labels every new ticket carries
"doneState": "Done" // state to propose when the work is finished
},
"slack": {
"reaction": "pr-merged", // emoji name, no colons
"channels": ["#team-prs"] // where PRs get announced; [] = search everywhere
},
"docs": {
"prDraft": false, // open the docs PR as draft
"assignee": "@me"
},
"cleanup": {
"tmpRoots": ["/tmp", "$TMPDIR"] // where session scratch clones live
}
}
If a project's agent docs (CLAUDE.md / AGENTS.md / memory) define ticket, PR, or commit rules, those rules win over this skill's defaults. Load any skill they name for ticket writing before a ticket write.
Step 1 — Gather (read-only)
Run the gathers of the jobs that run, in parallel. Nothing is written in this step.
a) PRs of the session. From the conversation: every PR opened, pushed to, reviewed-and-merged,
or merged this session. Confirm each with
gh pr view <url> --json number,url,title,state,mergedAt,body,headRefName. Keep the URL — every
later step keys on it.
b) Tickets. Collect ticket ids ([A-Z][A-Z0-9]+-\d+) from the conversation, the PR titles,
bodies, and branch names from (a). Fetch each (get_issue) for its state, assignee, and labels.
Map each ticket to the PRs and outcomes that concern it. Work with no ticket: search the tracker
first (list_issues, two or three keyword queries — feature name, component, error string). A
match becomes an update, not a new ticket. Only unmatched work becomes a creation proposal.
c) Slack threads. For each merged PR: search Slack for its URL (and <repo>#<number>
form), scoped to slack.channels when set. For each hit take the thread root (the message
itself if it has no parent). Read its reactions; drop roots that already carry the reaction. Open
or closed-unmerged PRs get no reaction.
d) Scratch data. Only what the transcript shows this session created:
- temp clones and worktrees under
cleanup.tmpRoots(git worktree listin each repo touched) - local branches whose PR merged (never the current branch, never the default branch)
- background processes the session started (port-forwards, dev servers, watchers) still running
- scratch files the session wrote outside the repo
- for each repo with a merged PR: its main checkout (first line of
git worktree list), if it sits on the default branch, gets agit pull --ff-only -p
Before listing a path, check it: git -C <path> status --short — uncommitted changes or unpushed
commits (git log @{u}.. or no upstream) mark it dirty. Dirty items are listed but never
deleted without an explicit per-item go. Never list the current working directory, the main
checkout, or anything the session did not create.
e) Docs worth capturing. Decide whether the session produced doc-worthy knowledge, using
capture-docs Step 1 rules. If not, the docs job is skipped.
Step 2 — Plan and wait
Show one plan, grouped by job, every write spelled out:
Tickets
ENG-123 comment: "Shipped in <PR link>: <one line outcome>" state: In Progress → Done
ENG-130 comment only (work continues: <what is left>)
new "<title>" — <~250-char body> — team ENG, labels [platform] (searched: q1, q2 → no match)
Slack (:pr-merged:)
#team-prs <permalink> → <PR link>
skipped <PR link> — no announcement found
Docs
branch docs/<topic> from origin/<default> → capture-docs → PR "<title>"
Cleanup
/tmp/repo-topic-1a2b worktree, clean remove
feat/foo local branch, PR merged delete
kubectl port-forward pid 4242 kill
/tmp/repo-x-9f9f DIRTY (2 unpushed) keep unless you say so
~/repos/repo main, 3 behind pull --ff-only -p
Give a recommendation for each judgment call (state moves, new ticket vs comment) in one line. Then stop and wait for the user's go. The user can drop or edit items ("go, skip the new ticket"). A job with nothing to do is left out of the plan; if every job is empty, say so in one line and stop.
Step 3 — Execute
Run in this order. One failure does not stop the rest — record it and continue.
- Tickets. Comments first, then state moves, then creations. On an update that sets labels, pass the existing labels too (many trackers replace the set). Link each PR to its ticket (attachment or link field) when the tracker supports it.
- Slack.
slack_add_reactionon each thread root.already_reactedcounts as success. - Docs. Never in the current working tree — other sessions may share it.
Rungit fetch origin dir=$(mktemp -d "${TMPDIR:-/tmp}/<repo>-docs-XXXXXX") git worktree add "$dir" -b docs/<topic> origin/<default-branch>capture-docswith$diras the repo root; it draws from this conversation, so the fresh branch is fine. If it reports "Nothing new to capture", remove the worktree and branch and mark the job skipped. Else commit (project's commit convention), push, andgh pr create --assignee <docs.assignee>(add--draftwhendocs.prDraft), with the project's PR template when one exists. Add the new docs worktree to the cleanup list. - Cleanup.
git worktree remove <path>(no--forceon a dirty one),git branch -d(lowercase-d: it refuses an unmerged branch — report it, do not escalate to-Dwithout a go; squash-merged branches need-D, which the plan already showed),kill <pid>,rm -ronly on paths in the approved list. Rungit worktree pruneonce per repo touched. - Main checkouts.
git -C <main checkout> pull --ff-only -pon each listed one, somainhas every PR merged this session and deleted remote branches are pruned. It keeps the user's uncommitted edits; if it refuses (diverged, conflicting local edit), report it: never stash, reset or merge.
Step 4 — Report
Outcome first, a few lines, only for jobs that ran and did something:
- tickets updated / created, as links
- threads reacted, as permalinks; PRs with no announcement found
- docs PR link, or "no docs to capture"
- what was removed, what was kept and why (dirty, refused
-d) - main checkouts fast-forwarded (old..new), or why one refused
- every failure with its error
Rules
- One gate. Nothing writes before the go in Step 2. Reads are free.
- Quiet when not set up. An unconfigured job is never mentioned, in the plan or the report.
- Only this session's footprint. Tickets, threads, and scratch data trace back to the conversation. Never sweep "all my PRs" or "everything in /tmp".
- Search before create. No ticket creation without a recorded search that found no match.
- Reaction on merged PRs only, on the thread root, once.
- Docs on a fresh branch in its own worktree, never on the session's branch.
- Dirty means keep. Uncommitted or unpushed work survives unless the user names it.
- Never force-push, never merge a PR as part of closing.