From 7e3a1cb93f80896c16a94f281679143653e9a64a Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Fri, 29 May 2026 00:00:54 +0200 Subject: [PATCH] chore(skills): generalize loyalty-wrap into topic-agnostic /wrap Rewrites the end-of-day wrap skill so it works for any session topic (not just the loyalty E2E walkthrough) and is safe to run with other agents working on the same repo concurrently. Detects the session's topic, creates a memory file if no matching one exists, only edits a proposal doc if one already exists for the topic, and pushes via fetch + pull --rebase + retry-once instead of bare push. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/skills/loyalty-wrap/SKILL.md | 109 ------------------ .claude/skills/wrap/SKILL.md | 158 +++++++++++++++++++++++++++ 2 files changed, 158 insertions(+), 109 deletions(-) delete mode 100644 .claude/skills/loyalty-wrap/SKILL.md create mode 100644 .claude/skills/wrap/SKILL.md diff --git a/.claude/skills/loyalty-wrap/SKILL.md b/.claude/skills/loyalty-wrap/SKILL.md deleted file mode 100644 index c12bd6d6..00000000 --- a/.claude/skills/loyalty-wrap/SKILL.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -name: loyalty-wrap -description: End-of-day session wrap for the loyalty pre-launch E2E walkthrough. Use when the user says any of "call it a night", "wrap up", "save memory and docs", "let's pause for today", "end of session", or similar phrasing — and the session has been working on the loyalty Tests 1-8 (or related loyalty pre-launch fixes). Updates the persistent memory file + the go-live readiness proposal with today's progress, runs mkdocs strict + architecture validation, commits and pushes the doc changes, then prints a concise recap with next-session carry-over. ---- - -# Loyalty walkthrough — end-of-day wrap - -A repeatable routine for closing out a session on the loyalty pre-launch E2E walkthrough. Every session in this thread has the same shape: do work → user says "call it a night" → record progress in two places → ship the doc changes → print a recap. This skill mechanises that. - -## 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". - -If the user invokes this when the session has not been on the loyalty walkthrough (e.g. they were doing unrelated work), confirm before proceeding — the skill is loyalty-specific. - -## Files touched - -| Path | Purpose | -|---|---| -| `~/.claude/projects/-home-samir-Documents-PycharmProjects-letzshop-product-import/memory/project_loyalty_e2e_walkthrough.md` | Persistent memory file — auto-loaded next session | -| `docs/proposals/loyalty-go-live-readiness.md` | In-repo proposal doc — same content but framed for the team / future readers | - -## Steps - -### 1. Update memory - -Edit the memory file: insert a new dated section **above** the line that currently reads `## Current state — paused end of day YYYY-MM-DD`, and also update that line's date to today. - -Section template: - -```markdown -## YYYY-MM-DD — - -### - -Body covering: what surfaced, root cause, commit hash + commit subject. If multiple commits, list each with `\`abc12345\` `. - -### - -Body covering: what was found, what's queued. Include file:line citations. -``` - -The memory file's last section heading is always `## Current state — paused end of day YYYY-MM-DD`. Rename it to today's date so the file's most-recent timestamp tracks. - -### 2. Update the proposal - -Edit `docs/proposals/loyalty-go-live-readiness.md`: insert a new section above the `## Status board` heading using a similar dated template. The proposal entries skew slightly more formal (team-readable) but cover the same factual ground. Always include: - -- Tests that progressed (with status board delta) -- Commits with hashes + subjects -- Carry-over for next session - -### 3. Verify the docs build clean - -Per the user's global rule (`~/.claude/CLAUDE.md`): always run mkdocs after doc changes AND always run architecture validation. Run them in parallel via two `run_in_background: true` Bash tool calls: - -```bash -mkdocs build --strict 2>&1 | tail -6 -pre-commit run validate-architecture --all-files 2>&1 | tail -5 -``` - -Both must pass. mkdocs failures usually mean a broken nav entry or a doc that doesn't exist; architecture warnings are OK (16 pre-existing baseline; 126 if another agent's TPL-016 work is in flight — treat as expected unless the count jumped further). - -### 4. Commit + push - -Stage ONLY `docs/proposals/loyalty-go-live-readiness.md` — never `-A`. The memory file is at `~/.claude/...` and isn't part of the repo (don't try to add it). - -Commit message template: - -``` -docs(loyalty): record YYYY-MM-DD - -<2-4 sentence body covering the day's work — Tests progressed, bugs -fixed with commit hashes, investigations/scopes recorded, what's -carrying over to next session.> - -Co-Authored-By: Claude Opus 4.7 (1M context) -``` - -Push to the `gitea` remote (not `origin` — that's the Synology backup; prod pulls from gitea): - -```bash -git push gitea master -``` - -### 5. Recap to the user - -End the turn with a tight summary: - -- Today's shipped commits (`hash` + one-line subject for each) -- What's complete (which Tests; which bugs are now resolved) -- The carry-over list for next session (mirrors the memory file's "Carry over" subsection) -- Sign-off: "Just say `resume` tomorrow and I'll pick up at . Goodnight 🌙" - -## Edge cases - -- **Nothing shipped today** (only investigation, no commits): still record the investigation in memory + proposal, still run mkdocs + architecture, but the commit message body should reflect that no code shipped, only docs. -- **The other agent's `TPL-016` warning count keeps climbing**: this is expected — that agent is actively addressing the rule. As long as none of the new warnings are in files this session touched, ignore. -- **Architecture validation fails (errors, not warnings)**: do NOT push docs. Surface the error to the user and ask whether to fix or skip the wrap. -- **mkdocs strict build fails**: same — do not push, surface the failure first. Usually a broken nav reference to a deleted page or a malformed cross-link. -- **Branch isn't `master`**: confirm with the user before pushing. The walkthrough has only ever used 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. The day's code commits (cooldown fixes, template edits, etc.) should already be in by the time wrap is invoked. The wrap commit is docs-only. -- Does not run the test suite. The work-in-progress commits earlier in the session would have triggered pre-commit hooks already. -- Does not update the global `~/.claude/CLAUDE.md` or other user-level files. -- Does not advance the walkthrough (no test execution, no new fixes) — only records what already happened. diff --git a/.claude/skills/wrap/SKILL.md b/.claude/skills/wrap/SKILL.md new file mode 100644 index 00000000..95733991 --- /dev/null +++ b/.claude/skills/wrap/SKILL.md @@ -0,0 +1,158 @@ +--- +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_.md` with this frontmatter + skeleton: + +```markdown +--- +name: project- +description: +metadata: + type: project +--- + +# + +**Started:** YYYY-MM-DD. + +**Why:** . + +**How to apply:** . + +## YYYY-MM-DD — + + + +## Current state — paused end of day YYYY-MM-DD + + +``` + +Then add an index line to `MEMORY.md` under the right section (or create a new section if the topic is new): + +```markdown +- [](project_.md) — +``` + +**Dated-section body template** (used in both new and existing files): + +```markdown +## YYYY-MM-DD — + +### + +What surfaced, root cause if a bug, decisions made, commit hash + subject if shipped (`abc12345` ). 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//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/.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(): record YYYY-MM-DD + +<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) +``` + +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 . 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).