agentleFS
jsuchetjsuchet/jonathan-skills-lab/skills/wrap-session/SKILL.md

wrap-session

Skill1 starsChanged 5 months agoMITView on GitHub

End-of-session logging ritual. Resolves scope from CWD + session work, asks 3 reflection questions (decision / learning / blocker), auto-writes journal.md + evals.md, appends to all 5 files in <scope>/meta/. Use after a plan is successfully executed, when the user signals end-of-session, or via /wrap-session.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 11 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 11

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Automatically: after a successfully executed plan, before declaring completion

    line 16
  2. Distinctive:

    No em-dashes: use colons, semicolons, line breaks

    line 23
  3. Distinctive:

    No hype words: revolutionary, game-changing, cutting-edge, synergy, leverage

    line 24
  4. Distinctive:

    Read tool-call history for file paths

    line 56
  5. Very specific:

    Create <scope>/meta/ if missing

    line 73
  6. Distinctive:

    Before asking the user anything, write down (internally) your best draft for each of the 3 reflection questions:

    line 78
  7. Very specific:

    Use a single AskUserQuestion call with 3 grouped sub-questions.

    line 86
  8. Distinctive:

    Skip a sub-question: only when you have very high confidence (obvious decision from the diff, obvious blocker the user already named).

    line 92
  9. Distinctive:

    Skip the entire prompt: when:

    line 94
  10. Very specific:

    If a scope keeps detailed per-decision files in its own decisions/ folder, write a one-line summary linking to the detailed file:

    line 114
  11. Distinctive:

    Confidentiality redaction: when writing journal.md at a scope HIGHER than a touched confidential client, redact client name and specifics.

    line 163
  12. Distinctive:

    Default grade is B. Grade A requires an explicit reasoning line citing specifics

    line 183
  13. Distinctive:

    If multiple scopes: one line per scope.

    line 198
  14. Distinctive:

    After a plan finishes for a confidential client's work, invoke:

    line 212

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/wrap-session [scope-path] [--skip-questions] [--scope-only]

End-of-session ritual that maintains 5 append-only log files in the relevant scope's meta/ folder. Captures a structural decision, a learning, a blocker (asks the user only when Claude is unsure), plus an auto-written factual session journal and Claude's own cognitive self-eval.

When to invoke

  • Automatically after a successfully executed plan, before declaring completion
  • When the user signals end-of-session ("done for today", "let's wrap", "OK I'm out")
  • Manually via /wrap-session at any time

Voice rules (CARL global, non-negotiable)

  • Active voice only
  • No em-dashes: use colons, semicolons, line breaks
  • No hype words: revolutionary, game-changing, cutting-edge, synergy, leverage
  • Direct and concise

Scope vocabulary

A "scope" is any project (or sub-project) that keeps its own meta/ log folder. Define your own; an example multi-project layout:

<vault-root>/
├── work/meta/                  ← work, cross-cutting
│   ├── <company>/meta/         ← a business / entity you run
│   └── clients/<slug>/meta/    ← one folder per client
├── content/meta/               ← a content project
├── personal/meta/              ← personal / life OS
└── notes/meta/                 ← a knowledge base

Each meta/ holds 5 append-only files: decisions.md, learnings.md, blockers.md, journal.md, evals.md.

Steps

1. Parse arguments

  • <scope-path> optional. If provided, use as the logging target. Skip auto-inference.
  • --skip-questions flag: do not prompt the user; auto-fill all 5 files from your own observation.
  • --scope-only flag: do not infer additional scopes; log only to the explicit scope.

2. Resolve scope (if no <scope-path> provided)

Inspect the session to find which scopes were touched:

  • Read tool-call history for file paths
  • Group paths by scope prefix
  • For each touched client folder, read its README.md frontmatter to capture confidential flag
  • Build a touched-scopes list

Apply these rules:

Touched scopesAction
1 scopeUse it
2+ Work clientsAsk via AskUserQuestion (multi-select) which to log to
Work + non-WorkLog to each as its own scope
None obviousDefault to CWD-derived project root; ask if still ambiguous

3. Ensure files exist

For each target scope:

  • Create <scope>/meta/ if missing
  • For each of the 5 files, create it with the canonical header if missing. Headers come from ~/.claude/skills/wrap-session/templates/.

4. Draft your own answers first (cognitive forcing function)

Before asking the user anything, write down (internally) your best draft for each of the 3 reflection questions:

  • Decision (decisions.md): "What structural choice did we make this session, and why?" — base on actual tool calls / edits / commitments made. If no structural decision was made, draft "no entry for this file".
  • Learning (learnings.md): "What did I/we learn?" — a domain insight, a user preference picked up, a tool quirk discovered, a mistake-fix that taught something. If nothing learned, draft "no entry".
  • Blocker (blockers.md): "What blocked us, or what repeated?" — structural friction, missing access, recurring problem, ambiguity that cost time. If nothing blocked, draft "no entry".

5. Ask the user

Use a single AskUserQuestion call with 3 grouped sub-questions. For each, your draft is the first option:

  • Q1: "What did we decide and why?" Options: [your draft], no structural decision this session, different — I'll type it
  • Q2: "What did we learn?" Options: [your draft], nothing notable to log, different — I'll type it
  • Q3: "What blocked us, or what repeated?" Options: [your draft], nothing blocked, different — I'll type it

Skip a sub-question only when you have very high confidence (obvious decision from the diff, obvious blocker the user already named). State in the report which questions you skipped and why.

Skip the entire prompt when:

  • --skip-questions flag set: auto-fill from draft
  • Pure-question session (no work produced): only write journal.md + evals.md

6. Compose entries

Date stamp = today's currentDate injection (ISO YYYY-MM-DD). Time = local 24h HH:MM.

decisions.md entry (only if Q1 yielded one)

## YYYY-MM-DD — <short decision title>
**Context:** what prompted the decision
**Decision:** what we chose
**Why:** the reason; what we rejected and why
**Owner:** [YOUR NAME] / Claude / both
**Reversibility:** easy / moderate / hard
**Related:** [[link to detailed decision file or session journal entry, if any]]

If a scope keeps detailed per-decision files in its own decisions/ folder, write a one-line summary linking to the detailed file:

## YYYY-MM-DD — <title> → [[decisions/YYYY-MM-DD-slug]]

Insert AT THE TOP of the file (most recent first).

learnings.md entry (only if Q2 yielded one)

## YYYY-MM-DD — <learning title>
**Type:** domain / preference / process / mistake-fix / tool
**Insight:** the lesson, in one or two sentences
**Triggered by:** session/work that surfaced this
**How to apply:** when this will matter again, where to use it

Insert at top.

blockers.md entry (only if Q3 yielded one)

## YYYY-MM-DD — <blocker title>
**Symptom:** what got stuck
**Root cause:** the real reason (if known) or "unknown"
**Workaround:** what got us moving (if any)
**Status:** active / resolved / recurring
**Resolution:** date + how it was resolved (if applicable)
**Pattern:** does this repeat? what's the trigger?

Insert at top. If a prior blocker matches this one, ADD a "Recurrence: YYYY-MM-DD (Nth occurrence)" line to the existing entry instead of creating a duplicate.

journal.md entry (ALWAYS)

## YYYY-MM-DD HH:MM — <session title>
**Scope:** what we worked on
**Inputs:** plans, files, decisions consulted
**Outputs:** files produced, commits made, decisions logged
**Plan executed:** path to plan file (if any)
**Outcome:** completed / partial / blocked
**Time:** rough duration
**Next:** what's next, if known
**See also:** [[decision entry slug]] · [[learning entry slug]] · [[blocker entry slug]]

Append at the BOTTOM (chronological).

Confidentiality redaction: when writing journal.md at a scope HIGHER than a touched confidential client, redact client name and specifics. Refer to it generically as "confidential client (routing: <how-it-was-routed>)". The full entry lives in the client's own meta/journal.md.

evals.md entry (ALWAYS)

## YYYY-MM-DD — <session title>
**Hallucinations caught:** facts/files asserted that turned out wrong (cite or "none caught")
**Silent bias detected:** opinions baked in without flagging (cite or "none noticed")
**Uncertainty I should have flagged:** spots I sounded confident but shouldn't have (cite or "none")
**Mistakes I made:** what went wrong and why (cite or "none")
**Confidence calibration:** where overconfident / underconfident (cite or "calibrated")
**Self-eval grade:** A / B / C / D
**Reasoning for grade:** one line; A requires explicit justification
**Next-session intent:** what to do differently (only if C/D)

Insert at top.

Rules:

  • Each category MUST contain either a concrete instance or the literal "none caught" / "none noticed" / "none" / "calibrated"
  • Default grade is B. Grade A requires an explicit reasoning line citing specifics
  • C or D requires the "Next-session intent" line

7. Cross-link

In the journal entry, fill **See also:** with the slugified headings of any decision/learning/blocker entries written this session. Slug format: lowercase, dashes, no special chars.

8. Report

Print a one-line summary to the user:

Wrapped session in <scope>. Logged: decisions / learnings / blockers / journal / evals. Skipped: <none|list>.

If multiple scopes: one line per scope.

Examples

Manual invocation, ai-in-marketing context

> /wrap-session

Skill detects CWD = ai-in-marketing/, infers scope, drafts answers, asks 3 questions, writes 5 entries, reports.

After plan execution, single client work

After a plan finishes for a confidential client's work, invoke:

/wrap-session <vault-root>/work/clients/<client-slug>

The skill writes confidential entries inside the client scope. If the session also touched cross-cutting concerns, additionally invoke:

/wrap-session <vault-root>/work --scope-only

to log a redacted higher-level journal entry.

Auto-fill (no user interaction)

> /wrap-session --skip-questions

Skill auto-fills all 5 files from observation. Useful when wrapping a long session and the user is away.

File header templates

Templates live at ~/.claude/skills/wrap-session/templates/. When stamping a new meta/ file:

  1. Copy the canonical header from the template
  2. Strip the example entry (commented out)
  3. Append fresh entries via the rules above

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.