Close Out

Close out

End-of-session housekeeping. The user's convention (per ~/dev/CLAUDE.md and ~/.claude/CLAUDE.md):

• CLAUDE.md per repo - project schema and conventions
• LOG.md per repo - chronological decision log, date-headed ## YYYY-MM-DD, entries tagged ### [][]
• INDEX.md per repo - content catalog: where artifacts live
• PLAYBOOK.md per repo (or the consolidated HANDBOOK.md's ## Processes section where adopted, e.g. the ~/dev root) - the repeatable plays we run (local-only as of 2026-06-21, like LOG/INDEX); prose plays are the backlog of what to systematize into skills
• README.md per repo - human-facing notes
• ~/.claude/projects//memory/ - durable cross-session knowledge (user / feedback / project / reference types)
• .pen wireframes (Pencil): demote 🚧 NEW NEW frames whose content shipped

The convention only pays off if the files stay current. This skill is the discipline that prevents rot.

How to run it

Default mode is fast and parallel for LOG / INDEX / CLAUDE / README edits. Apply first, summarize at the end. Do NOT preview those drafted entries and ask for approval; the summary is where the user reviews; if they want changes, iterate then.

Memory writes are the exception: they require explicit per-entry approval. Memory persists across every future session and quietly shapes Claude's behavior, so a wrong memory is a long-tail cost. Always confirm each proposed memory write or update with the user via a single AskUserQuestion multi-select before writing. See Step 2 for the gate's exact shape.

Step 0: Print the run roadmap

Before doing anything else, print the fixed roadmap (6 main steps plus conditional 2.5 and 5.5) so the user can follow the run. Mark each step with a status indicator that updates as work progresses:

• ⏳ pending
• 🔄 in-progress
• ✅ done AND made a change (wrote a file, pushed, opened a PR, deleted a branch, etc.)
• ❌ either conditionally skipped OR ran and found nothing to do (with reason inline)

The ✅/❌ distinction is about outcomes, not execution. A step that ran successfully but produced no change gets ❌ with reason "nothing to do" (or similar), not ✅. Reserve ✅ for steps that actually moved the world. This keeps the roadmap honest: at-a-glance scan of green checks tells the user exactly what changed.

Initial print:

Close-out plan:
- ⏳ 1. Inventory (git, memory dir, Q+A log, branch protection)
- ⏳ 1.5. Release docs sync (only if a ship happened this session and the repo has user-facing docs)
- ⏳ 2. Decide and apply edits (LOG / INDEX / CLAUDE / memory / README)
- ⏳ 2.5. Playbook harvest (repeatable plays -> HANDBOOK.md `## Processes` or PLAYBOOK.md; only if a reusable flow ran)
- ⏳ 3. Push and PR (direct push or open PR depending on branch protection)
- ⏳ 4. Pencil sweep (only if .pen was edited and a deploy happened)
- ⏳ 5. Memory-candidate batch review (only if candidates file has entries)
- ⏳ 5.3. Memory gardening (harness warning, 45-day TTL, or 20KB/170-line working target)
- ⏳ 5.5. Agent files architect (only if TTL/session/activity trigger fires)
- ⏳ 5.7. Cleanup stale branches and return to main (per touched repo)
- ⏳ 5.8. Skill / plugin upgrade check (only if something is behind upstream)
- ⏳ 5.9. Open-PR finish gate (only if a touched branch has an OPEN unmerged PR)
- ⏳ 6. Summary

As each step completes, print a one-liner like ✅ Step N done. and continue. Do not reprint the full roadmap between every step; the running output reconstructs progress.

When a conditional step (1.5, 4, or 5) is going to skip, mark it as ❌ with the reason at the moment you confirm the skip (during or right after Step 1), not later. Example: after inventory, if there were no .pen edits this session, immediately note ❌ Step 4 skipped: no .pen edits; if no ship happened this session, note ❌ Step 1.5 skipped: no ship this session.

Similarly, when an unconditional step (2, 5.7) runs and produces no change, mark it ❌ with reason "nothing to do" (or more specific: "no edits warranted", "no merged branches to prune"). Do not give it ✅ just because it executed without error.

Always render skipped or no-op steps with ❌ (red X), never hide them. They must remain visible in the running output and in the final roadmap reprint so the user can see at a glance what didn't move. Do not omit a step from the roadmap just because it was skipped or did nothing.

For Step 6, reprint the full roadmap with final markers so the run ends with a clear "here is everything that happened" view, then add the one-line summary.

This roadmap is the user's read on what is about to happen and what is in flight. Keep it accurate and lightweight; do not embellish it with sub-bullets or commentary.

---

Step 1: Inventory in one parallel bash call

Run a single bash invocation that gets everything you need:

• git status and git log --oneline -20 for each touched repo (chain with cd ... && ... ; cd ... && ...)
• For each touched repo's current branch, check for an OPEN unmerged PR with gh pr list --head --state open --json number,title,url. Prefer this gh pr list form over gh pr view : a branch with no PR (the common case) makes gh pr view exit non-zero, which under the chained &&/; inventory call can abort the chain; gh pr list returns an empty array and exits 0. --state open already excludes merged and closed PRs, so any entry it returns is an OPEN unmerged PR to record for the Step 5.9 finish gate. If a repo touched more than one branch this session, check each.
• ls of ~/.claude/projects//memory/ to see existing memory files
• ls of ~/.cloudflare/, any new credential dirs, etc.

Also re-scan the conversation for: decisions made in chat, gotchas that cost time, deploys/state changes in external systems (GitHub repos, CF projects, DNS zones), .pen file edits.

For Step 1.5, also record two signals per touched repo: (a) whether a ship happened this session (a PR merged, a release/tag cut, or a deploy ran; a plain WIP commit with no merge/deploy is NOT a ship), and (b) whether the repo carries tracked user-facing docs that can drift (README.md, CHANGELOG.md, ARCHITECTURE.md, CONTRIBUTING.md, or a docs/ dir). These two booleans decide whether Step 1.5 runs.

Surface a short inventory to the user (5-10 bullets max). Do not ask any question yet; just show what you saw, then immediately move to Step 2.

Step 1.5: Release docs sync (only if a ship happened this session)

This step auto-runs the gstack /document-release skill so post-ship docs (README / CHANGELOG / ARCHITECTURE / CONTRIBUTING / VERSION) stay in sync with what actually shipped. It runs BEFORE Step 2 on purpose: /document-release leaves its edits uncommitted, and running it first means Step 2 reads the updated docs and Step 3 sweeps the doc edits into the same push/PR.

Availability gate first. This step depends on the gstack document-release skill. Confirm it is present (e.g. ~/.claude/skills/document-release/SKILL.md exists, or the /document-release slash command resolves). If it is not installed, skip silently and mark ❌ with reason "document-release not installed", then continue to Step 2. Do not error or stop close-out over a missing optional dependency.

Relevance gate. Run this step for a touched repo only when BOTH of the Step 1 signals are true for it:

1. A ship happened this session: a PR was merged, a release/tag was cut, or a deploy ran. A plain WIP commit, an open-but-unmerged PR, or doc-only churn is NOT a ship.
2. The repo carries tracked user-facing docs that can drift (README.md, CHANGELOG.md, ARCHITECTURE.md, CONTRIBUTING.md, or docs/). close-out's own LOG.md / INDEX.md / CLAUDE.md are local-only and out of /document-release's scope, so they do not count here.

If either is false, skip and mark ❌ with the specific reason ("no ship this session" or "no user-facing docs").

When it fires (auto-run). For each qualifying repo, invoke /document-release directly. Do NOT add a close-out-level confirmation before invoking: the user has opted into auto-run for this step. Auto-run means close-out does not gate the invocation; it does NOT bypass /document-release's OWN internal approval gates (VERSION bump, CHANGELOG voice polish), which still fire normally inside that skill. If more than one touched repo qualifies, run /document-release once per qualifying repo.

Mark ✅ if /document-release ran and changed at least one doc; ❌ (reason: "no doc changes") if it ran but found nothing to update.

Step 2: Decide and apply in one batch

Use these rules to decide what gets written where:

| What | Where | |------|-------| | WHY a decision was made | LOG.md in the affected repo | | Gotcha that cost real time (with symptom + fix so future-you can grep) | LOG.md | | Where a new artifact lives | INDEX.md | | Durable convention that governs future work IN THIS PROJECT | CLAUDE.md | | Durable convention that governs future work ACROSS PROJECTS | memory (feedback type) | | Fact about external infrastructure | memory (reference type), maybe also INDEX.md / CLAUDE.md | | User role / preference revealed in chat | memory (user type) | | User-visible surface or setup steps changed | README.md | | A repeatable, reusable flow we ran this session (a play) | HANDBOOK.md ## Processes or PLAYBOOK.md (captured in Step 2.5, not here) |

For LOG entries: match the existing file's voice (terse vs. discursive) and tag conventions. Date header ## YYYY-MM-DD once per day, not per entry. Lead with the decision or fact, then a short paragraph of WHY (motivation, constraint, the gotcha + fix).

For memory: the index is tiered (since 2026-06-10): MEMORY.md carries hot cross-cutting rules plus one trigger line per cat_*.md category sub-index; domain knowledge is indexed in the category files. Read MEMORY.md and the relevant cat_*.md first to avoid duplicates. Prefer updating an existing memory file over creating a new one.

Apply all NON-memory edits (LOG / INDEX / CLAUDE / README) in parallel tool calls. Read all the files you need to edit in one parallel batch; apply all the Edits in a follow-up parallel batch. Do not Read-then-Edit-then-Read-then-Edit serially across repos. Do not preview these entries; the user reviews them in the Step 6 summary.

Memory writes go through an explicit approval gate. After deciding what memory you would write (new files or updates to existing ones), pause and present the full set to the user in a single AskUserQuestion with multiSelect: true. One option per proposed memory. The option label is a short title (under 50 chars). The option description is a one-line summary of what that memory would say plus its type and target filename (e.g., new reference_codex_install.md or update reference_codex_cli_breaking_changes.md). The question text is:

> Which of these memories should I write? (Each persists across all future sessions.)

Set header: "Memory writes". Use multi-select so the user can approve, reject, or partially approve in one click. Only after the user submits do you apply the approved subset (in parallel). For any memory the user rejects, do not write it, do not "save a smaller version", do not retry. If the user wants a different cut they will say so.

If zero memories are proposed in a given close-out, skip the gate entirely; do not ask an empty question.

Carve-outs (skip the gate, narrow exceptions):

• User explicitly said "save this", "remember this", or named the memory they want written during the session: their request IS the approval, do not re-ask.
• User asked you to forget or remove a memory: that is a delete, not a write. Confirm what you are deleting once, then proceed.
• Trivial mechanical edits to keep memory consistent with itself (renaming a slug in MEMORY.md to match a renamed file, fixing a broken [[link]]): not new claims, just bookkeeping. Mention in summary; no gate.

Non-interactive mode. If you are running in a mode where AskUserQuestion cannot fire (piped-prompt mode like claude -p, CI runs, scripted invocations), do NOT silently fall back to writing the memory. Skip the write and surface a warning in your output for each skipped memory: Memory write skipped: (non-interactive mode, approval gate could not run). Re-run interactively or re-prompt with explicit approval to save. List each skipped slug so the user can re-trigger only the ones they want.

Header reservation (re-entrancy). The strings "Memory writes" and "CLAUDE.md edit" are reserved AskUserQuestion header values: a Q+A capture hook that records every AskUserQuestion answer (such as the user's ~/.claude/scripts/memory-candidate-capture.sh) must skip questions carrying these headers, otherwise the gate's approval question itself becomes a future memory candidate and the loop feeds itself. If your environment has such a hook, ensure it is configured to skip both reserved headers before relying on the gate at scale; flag this to the user the first time you notice the gap.

Step 2.5: Playbook harvest (repeatable plays -> HANDBOOK.md ## Processes, or PLAYBOOK.md)

The repo's local-only record of the repeatable plays we run (the four-file convention in ~/dev/CLAUDE.md; a play is born as prose, then graduates into a skill once it recurs, at which point its entry keeps the judgment and points at the skill). Target file: where a repo has adopted the consolidated HANDBOOK.md (its plays live under the ## Processes section, e.g. the ~/dev root), write there; otherwise the repo's PLAYBOOK.md. Prefer HANDBOOK.md when both exist. The entry grammar (### Play: + Status:) is identical in both. This step looks retroactively at the session for a reusable flow worth recording, and decides whether each one is already covered by an existing skill or tool, or is a candidate to build. The reference shapes are ~/dev/businesses/dxangels/PLAYBOOK.md (per-repo) and ~/dev/HANDBOOK.md (consolidated).

Relevance gate. Run only when this session actually executed a repeatable, reusable flow (scored a pool, ran an outreach sequence, pulled and transformed data through a multi-step process, stood up a recurring artifact, etc.). Pure conversation, a one-off debug, planning, or a trivial edit has no play; skip and mark ❌ "no play this session". Never invent plays to fill the file. The bar is "we will plausibly do this again".

Search before proposing a build (the user's standing rule). For each candidate play, find what already covers it BEFORE proposing a new skill. Spin up ONE subagent (general-purpose) over the full candidate set that, per candidate, checks:

1. Installed skills: scan ~/.claude/skills/*/SKILL.md AND installed plugin skills (~/.claude/plugins/cache/*/*/*/skills/*/SKILL.md) frontmatter (name + description) for a skill that already runs this flow.
2. Existing software / tools: a quick search for an off-the-shelf tool, library, or service that already does it (do not reinvent something that exists).

The subagent returns, per candidate: covered-by-skill: | covered-by-tool: | no-match (candidate skill), each with a one-line why. Give it a strict output contract at the top of its prompt so the result parses.

Apply. Read the repo's playbook file (HANDBOOK.md's ## Processes section where the repo has adopted it, else PLAYBOOK.md), creating a PLAYBOOK.md from the dxangels reference shape if neither exists (every repo under ~/dev carries one per the four-file convention, so "missing" means "not bootstrapped yet", not "this repo opts out"; never create a second file when HANDBOOK.md already holds the plays). For each candidate, apply directly (no per-entry preview; the user reviews in the Step 6 summary):

• nothing covers it -> a new ### Play: entry with `Status: prose (candidat

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mujtaba3B
• Source: mujtaba3B/mutwo-skills
• License: MIT

Install and usage instructions live in the source repository linked above.