end-session

name

end-session

description

Wraps up a work session with a structured summary and action items. Use this skill whenever the user says "end session", "wrap up session", "close session", or similar. Default mode is sequential — each section presented one at a time, waits for confirmation before moving on. Say "end session quick" for all sections in one block. Always invoke proactively when the user signals they are done working.

End Session

The goal is to close the session cleanly — capture what happened, update the project files, and surface anything worth remembering or acting on next time.

Two modes:

• Default — sequential: each section is presented one at a time, wait for confirmation before moving to the next.
• Quick mode — triggered when the user says "end session quick" or "quick end session": present all sections in one report, user replies once.

If mode is unclear, use default (sequential).

Step 1 — Read current state

Before producing the report, read:

• SESSION.md — to understand what's already logged and what gotchas exist
• TODO.md — to know the current task list
• CLAUDE.md — to check if anything critical needs updating
• .reference/INDEX.md — if present, to align on existing evergreen reference docs

Also review the full conversation history — this is the source of truth for what actually happened this session.

Step 2 — Produce the end-session report

Default mode (sequential)

Present each section one at a time. Wait for the user's reply before moving to the next. Order:

1. Summary — show first, no confirmation needed, then immediately show Gotchas
2. Gotchas to add to SESSION.md → wait for reply
3. Tasks to mark as done → wait for reply
4. Suggested new tasks → wait for reply
5. INSIGHTS.md suggestions → wait for reply
6. Apply all confirmed changes

Quick mode (all at once)

If the user said "end session quick" — present all sections in one block, user replies once for all sections. Same structure, same numbered lists.

In quick mode, start with a compact summary table before the detailed sections:

Category	Count	Notes
Gotchas to add	N	include metadata tags
Tasks to mark done	N	include confidence tags
Suggested new tasks	N	deduped vs TODO.md
INSIGHTS suggestions	N	deduped vs INSIGHTS.md
Files to edit	N	SESSION.md / TODO.md / INSIGHTS.md

---

Section formats

Summary (no confirmation):

## End Session

### Summary
[2-4 lines — what was done, fixes made, decisions taken. Specific, not vague.]

Gotchas (wait for reply):

### Gotchas to add to SESSION.md
1. [Title — short explanation of what was learned and why it matters]
  Scope: [Global / Region / Business Unit / Service / Infrastructure]
  Confidence: [Confirmed / Strong evidence / Hypothesis]
  Active: [Yes / No / Unknown]
  Last verified: [YYYY-MM-DD]
2. ...
(or: None this session.)

→ Reply with numbers (e.g. "1, 3") or "all" or "skip"

Tasks to mark done (wait for reply):

### Tasks to mark as done
1. ✅ [Task text from TODO.md — confident it's done] (Confidence: High)
2. ⚠️ [Task text — partially done or needs follow-up] (Confidence: Medium)
3. ✅ [Task completed this session but not in TODO.md] *(will be added)* (Confidence: High)

→ Reply with numbers (e.g. "1, 3") or "all" or "skip"

When applying confirmed tasks: if a task exists in TODO.md, mark it [x] and move it to the ## Done section when appropriate.

## Done must be grouped by date headers and kept chronological, with the latest date block at the end. Use this header format:

## DONE - YYYY-MM-DD

If today's date header exists, append completed tasks under it. If it does not exist, create it at the end of ## Done and append tasks there. If the repository already uses a plain ## Done list without date headers, preserve existing style unless the user explicitly asks to migrate format.

If a task was NOT in TODO.md (marked with "will be added"), add it under today's ## DONE - YYYY-MM-DD header as:

- [x] Task title
scope: ... | target: ... | owner: ... | next: completed in session | updated: YYYY-MM-DD
#tag1 #tag2 #tag3

New tasks (wait for reply):

### Suggested new tasks
1. [ ] Task title
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
  #tag1 #tag2 #tag3

2. [!] Important task title
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
  #tag1 #tag2 #tag3
  desc: optional extra context only when needed

→ Reply with numbers (e.g. "1, 3") or "all" or "skip"

INSIGHTS (wait for reply):

### INSIGHTS.md suggestions
1. [Skill Candidate] Title — why it's a good skill candidate
2. [Skill Upgrade] Skill name — what to improve
3. [CLAUDE.md Gap] What was missing and slowed things down
4. [Automation] What could be scripted
5. [Workflow Idea] General observation

→ Reply with numbers (e.g. "1, 3") or "all" or "skip"

---

Step 3 — Apply confirmed changes

Once the user replies to each section, apply all changes:

SESSION.md — append a new entry at the bottom of the CHRONOLOGICAL LOG:

## [YYYY-MM-DD HH:MM] — [one-line description]
[Session summary text]

**Key learnings added:** [list confirmed gotcha numbers, or "none"]

And add confirmed gotchas to the KEY LEARNINGS section with the next sequential number.

Gotcha formatting in SESSION.md must include:

• Scope: Global / Region / Business Unit / Service / Infrastructure
• Confidence: Confirmed / Strong evidence / Hypothesis
• Active: Yes / No / Unknown
• Last verified: YYYY-MM-DD

Before adding a new gotcha, check for semantic duplicates in existing KEY LEARNINGS. If duplicate root cause exists, update the existing entry instead of adding a new one.

TODO.md — follow the canonical structure:

• One ## Open Tasks section at the top (urgent [!] first, then regular [ ]).
• One ## Done section at the bottom.

For each confirmed done task:

• If it exists in TODO.md: mark it [x], keep details intact, and move it to ## Done when appropriate, under today's ## DONE - YYYY-MM-DD block.
• If it was NOT in TODO.md (completed this session but never tracked): add it under ## Done using the standard 3-line task format, inside today's ## DONE - YYYY-MM-DD block. Never skip a completed task just because it wasn't pre-listed.

Ordering rule for ## Done:

• Keep older date blocks first and newest date block last.
• Do not insert a newer block above older ones.

For confirmed new tasks:

• Always add under ## Open Tasks (never scattered sections).
• Use this standard format:

- [ ] Task title
scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
#tag1 #tag2 #tag3

Rules:

• scope is required for all new tasks.
• Keep tags on their own line (prefer 4-6 tags).
• desc: is optional and only used when extra context is necessary.
• Before adding, check TODO.md for semantic duplicates and avoid re-adding the same task under different wording.

INSIGHTS.md — if the file doesn't exist, create it using the standard template (see below). Append confirmed insights to the appropriate section with a date stamp.

.reference/ — when a confirmed session output is stable and reusable (not incident-timeline specific), suggest promoting it into .reference/<prefix>__<topic>.md and add/update its entry in .reference/INDEX.md.

Before appending, dedupe semantically similar insights to avoid repeated items.

INSIGHTS.md template (create if missing)

# INSIGHTS — [Project Name]

> Captured during sessions — workflow ideas, skill candidates, context gaps,
> and patterns worth acting on.
> Review periodically and promote to CLAUDE.md, skills, or TODO.md.

---

## 🔁 Skill Candidates
<!-- Tasks repeated often enough to become a skill -->

---

## 🔧 Skill Upgrades
<!-- Improvements spotted for existing skills -->

---

## 📋 CLAUDE.md Gaps
<!-- Context that was missing and slowed down a session -->

---

## ⚡ Automation Ideas
<!-- Repetitive manual steps that could be scripted or automated -->

---

## 💡 General AI Workflow Ideas
<!-- Broader ideas — prompting patterns, session habits, tools -->

---

## 🗃️ Archive
<!-- Ideas promoted to action — moved here once acted on -->

Notes on judgment

• Summary: Be specific and honest. If you're not sure something was fully resolved, say so.
• Gotchas: Quality over quantity. One genuinely useful gotcha is better than five obvious ones. Always include Scope/Confidence/Active/Last verified.
• Done tasks: Be conservative with ⚠️ — if there's any doubt, flag it. The user may know something you don't. Add confidence tag (High/Medium/Low) in proposals.
• New tasks: Think about what the user would regret NOT having in TODO.md next session. Future-you will thank present-you. Do not add duplicates.
• INSIGHTS: Look for patterns across the session, not just individual moments. Did the same problem come up three times? That's a skill candidate. Prefer updating an existing insight over appending near-duplicates.
• Tone: Professional and direct. No filler. The user has just finished work — make this easy to process and confirm quickly.