---
name: wrap
description: End-of-day session wrap that records *whatever this session was about* into the right persistent memory file (and, if one exists, the matching in-repo proposal doc), runs mkdocs strict + architecture validation if docs changed, commits and pushes any doc edits, then prints a concise recap with next-session carry-over. Triggers on "call it a night", "wrap up", "save memory and docs", "let's pause for today", "end of session", "save where we are", "goodnight let's commit". Safe to run with other agents concurrently on the same repo — uses pull-rebase-retry on push and stages only its own files.
---

# Session wrap

Closes out a working session by persisting today's progress so the next session (or another agent) can pick up cold. Generic across topics — the skill figures out what the session was about and routes the writes accordingly.

## When to invoke

Trigger phrases (non-exhaustive): "call it a night", "save memory and docs", "wrap up", "let's pause for today", "end of session", "save where we are", "goodnight let's commit", "good night".

The skill works for *any* topic. Don't bail out because the session wasn't loyalty.

## Step 0 — Identify the session topic

Look back over the current conversation and answer three questions in your head:

1. **What was the session about?** A single noun phrase: "loyalty E2E walkthrough", "admin/merchant/store shell unification scoping", "messaging.messages consolidation", "infra debug", etc.
2. **Was a code commit shipped?** Check `git log --oneline -10` and compare against what the user actually saw happen in this session. If commits landed, list them. If not, the wrap is doc-only.
3. **Is there an existing memory file that matches?** `ls ~/.claude/projects/-home-samir-Documents-PycharmProjects-letzshop-product-import/memory/project_*.md` — pick the closest match by name/description. If none fits, you'll create a new one in step 1.

Pick the topic slug (kebab-case) you'll use throughout: e.g. `loyalty-e2e-walkthrough`, `shell-unification`, `messaging-consolidation`.

## Step 1 — Update (or create) the memory file

Memory dir: `~/.claude/projects/-home-samir-Documents-PycharmProjects-letzshop-product-import/memory/`

**If a matching `project_*.md` already exists** (e.g. `project_loyalty_e2e_walkthrough.md`):
- Read it. Insert a new dated section **above** the file's last "current state" / "paused" / "carry over" heading (whatever the trailing heading is — different files use different conventions). Update that trailing heading's date to today.
- Edit pattern: use the Edit tool with an `old_string` anchored on the trailing heading line, so two concurrent agents inserting different sections don't race on the same anchor.

**If no matching file exists**, create `project_<topic-slug>.md` with this frontmatter + skeleton:

```markdown
---
name: project-<topic-slug>
description: <one-line summary of the work this file tracks>
metadata:
  type: project
---

# <Topic title>

**Started:** YYYY-MM-DD.

**Why:** <what kicked this off — link related memories with [[name]]>.

**How to apply:** <what the next session / another agent should do with this file>.

## YYYY-MM-DD — <one-line headline>

<body — see template below>

## Current state — paused end of day YYYY-MM-DD

<one-paragraph "where we are" + next concrete step>
```

Then add an index line to `MEMORY.md` under the right section (or create a new section if the topic is new):

```markdown
- [<Topic title>](project_<topic-slug>.md) — <one-line hook>
```

**Dated-section body template** (used in both new and existing files):

```markdown
## YYYY-MM-DD — <headline>

### <Sub-block per thing that happened>

What surfaced, root cause if a bug, decisions made, commit hash + subject if shipped (`abc12345` <subject>). For investigations that didn't ship code, include file:line citations.

### Carry over to next session

- 1-N bullets covering the next concrete steps.
```

## Step 2 — Update the proposal doc (only if one exists)

Look for an in-repo proposal/doc that corresponds to this topic. Common spots:
- `docs/proposals/*.md` (most common — e.g. `loyalty-go-live-readiness.md`, `cms-redesign-alignment.md`, `persona-template-consolidation-audit.md`)
- `docs/architecture/*.md` (for pattern/architecture work)
- `app/modules/<m>/docs/*.md` (for module-internal trackers)

**If one exists** that's the team-readable counterpart to this session's work: insert a dated section above the doc's status/board/timeline heading, mirroring the memory entry but team-framed (less first-person, no internal links to memory files).

**If none exists**, skip this step — don't fabricate a proposal doc just to have something to commit. Step 3 + 4 then become no-ops (no docs changed → nothing to validate or push).

## Step 3 — Validate doc changes (only if step 2 wrote a file)

Per `~/.claude/CLAUDE.md`'s global rules: mkdocs strict + architecture validation after any doc change. Run both in parallel via `run_in_background: true`:

```bash
mkdocs build --strict 2>&1 | tail -6
pre-commit run validate-architecture --all-files 2>&1 | tail -5
```

Both must pass. Architecture warnings are OK (the project has a baseline); only **new** errors block the wrap. mkdocs strict failures are usually a broken nav entry or cross-link — fix and re-run before pushing.

If either fails: do NOT push. Surface the failure to the user and ask whether to fix or skip the wrap.

## Step 4 — Commit + push (only if step 2 wrote a file)

**Concurrency safety: another agent may be doing the same wrap on this repo right now.** Follow this exact order:

1. `git status --short` — confirm the only modified/added file is the doc you just edited. If unrelated files are dirty (another agent in flight), do NOT stage them; commit only your own file by name.
2. `git fetch gitea master` — get the latest remote tip without merging.
3. `git pull --rebase gitea master` — rebase any new commits from the other agent on top of HEAD before you commit. If this fails with a conflict on the doc file you're about to edit, the other agent committed first to the same doc; re-read the file, re-apply your section, and retry from step 1.
4. Stage ONLY the doc file by explicit path (`git add docs/proposals/<file>.md` — never `-A` / `.`). The memory file at `~/.claude/...` is outside the repo; don't try to add it.
5. Commit with the message template below.
6. `git push gitea master`. If push is rejected (`! [rejected]` or `non-fast-forward`), another agent pushed between your pull and push. Run `git pull --rebase gitea master` and `git push gitea master` once more. If it still fails after one retry, surface to user — don't loop.

Push to **gitea** (not `origin` — that's the Synology backup; prod pulls from gitea).

**Commit message template:**

```
docs(<scope>): record YYYY-MM-DD <one-line headline>

<2-4 sentence body covering the session's work — what shipped (with
commit hashes), what was scoped/investigated without shipping, and
what's carrying over to next session.>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
```

Scope is the topic area: `loyalty`, `audit`, `arch`, `cms`, `infra`, etc. — match it to the doc's directory.

## Step 5 — Recap to the user

End the turn with a tight summary:

- Today's shipped commits if any (`hash` one-line subject for each)
- What's complete (Tests/items done, bugs resolved)
- Carry-over for next session (mirrors the memory file's "Carry over" subsection)
- Sign-off: `Just say "resume" tomorrow and I'll pick up at <next concrete item>. Goodnight 🌙`

## Edge cases

- **Nothing shipped today, only scoping/investigation**: still record in memory (and proposal if one exists). The commit message body should reflect that no code shipped, only docs. If no proposal exists and the session was pure scoping, memory write alone is enough — no commit, no push.
- **No matching memory file AND no matching proposal**: create the memory file only; skip the proposal/commit/push entirely. Recap still happens.
- **Other agent's `TPL-016`/other warning count keeps climbing**: expected when another agent is actively addressing the rule. As long as none of the new warnings are in files this session touched, ignore.
- **Architecture validation surfaces new ERRORS in files this session didn't touch**: not your fault, but don't push. Tell the user another agent likely introduced them and ask whether to push docs anyway or wait.
- **`git pull --rebase` conflicts on the doc you're editing**: the other agent shipped to the same doc first. Re-read the doc (it now has their section), re-apply yours below theirs (or above, depending on convention — most files insert newest-on-top), retry.
- **`git push` rejected twice in a row**: stop retrying; surface to user with the remote tip's last 3 commits so they can decide.
- **Branch isn't `master`**: confirm with the user before pushing. Wraps have only ever targeted master.
- **gitea push fails (auth, network)**: tell the user to push manually; don't retry blindly.

## What the skill explicitly does NOT do

- Does not commit code changes. Code commits should already be in by wrap time. The wrap commit is doc-only.
- Does not run the test suite. Code commits earlier in the session would have triggered pre-commit hooks already.
- Does not update `~/.claude/CLAUDE.md` or other user-level files.
- Does not advance the work (no test execution, no new fixes) — only records what already happened.
- Does not stage files it didn't write itself (`-A` / `.` are forbidden — they'd grab another agent's in-flight edits).
