From ea61bdd1bfe7bfda06271ab5cdec10df8d1c054a Mon Sep 17 00:00:00 2001 From: Yonatan Hen Date: Sat, 4 Jul 2026 17:22:35 +0300 Subject: [PATCH 1/3] feat(skills): add db-snapshot skill for on-demand Mongo snapshots Wraps backend/scripts/DB/snapshot_dump.py so a DB snapshot can be taken on request or before starting a new feature, per CLAUDE.md. --- .claude/skills/db-snapshot/SKILL.md | 49 +++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 .claude/skills/db-snapshot/SKILL.md diff --git a/.claude/skills/db-snapshot/SKILL.md b/.claude/skills/db-snapshot/SKILL.md new file mode 100644 index 0000000..bf76a3b --- /dev/null +++ b/.claude/skills/db-snapshot/SKILL.md @@ -0,0 +1,49 @@ +--- +name: db-snapshot +description: Take a snapshot of the current MongoDB dev database state on request, using backend/scripts/DB/snapshot_dump.py. Trigger when the user asks to snapshot/save/backup the DB, or before starting a new feature per CLAUDE.md ("Always take a DB snapshot before implementing a new feature"). +--- + +# DB Snapshot + +Dumps `player_bios` + `player_stats` + `fetch_log` from the dev MongoDB to a local JSON file under `backend/snapshots/` (gitignored — developer-local only, preserves `_id` linkage via BSON Extended JSON). + +## Steps + +### 1. Confirm the stack is up + +Mongo must be reachable on `localhost:27017`: + +```bash +docker compose ps --format "{{.Service}} {{.State}}" +``` + +If `mongodb` isn't `running`, tell the user to `docker compose up -d mongodb` (or the full stack) before proceeding — do not start it yourself without asking. + +### 2. Determine the snapshot filename + +- If the user gave a name, use it (append `.json` if missing). +- Otherwise, propose one based on context: current branch/feature name or a dated name (e.g. `dev-fantasy-platform-sport5.json`, `pre-rag-chat.json`), and confirm with the user before running — don't silently overwrite an existing snapshot with the same name. + +### 3. Run the dump + +From `backend/`, using the project's venv per CLAUDE.md: + +```bash +.venv\Scripts\python scripts/DB/snapshot_dump.py .json +``` + +Omitting `.json` writes to the script's default (`cl-2025-2026.json`) — always pass an explicit name unless the user wants the default. + +### 4. Report the result + +Show the per-collection doc counts printed by the script and the output path (`backend/snapshots/.json`). Remind the user this file is gitignored (local-only) — it is not committed or pushed. + +## Restoring (reference only) + +This skill only takes snapshots. To restore one later: + +```bash +.venv\Scripts\python scripts/DB/snapshot_load.py .json +``` + +Restoring **replaces** `player_bios`, `player_stats`, and `fetch_log` entirely — confirm with the user before running it, since it's destructive to current DB state. From 6180e4c84e7e0c618b10a14647b17cc80bf69c02 Mon Sep 17 00:00:00 2001 From: Yonatan Hen Date: Sat, 4 Jul 2026 17:27:55 +0300 Subject: [PATCH 2/3] fix(skills): correct db-snapshot output path Verified by running the skill: snapshot_dump.py resolves its output dir relative to its own location (scripts/DB/../snapshots), so files land in backend/scripts/snapshots/, not backend/snapshots/ as initially documented. Still gitignored via the blanket backend/scripts/* rule. --- .claude/skills/db-snapshot/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/db-snapshot/SKILL.md b/.claude/skills/db-snapshot/SKILL.md index bf76a3b..5cf6d1a 100644 --- a/.claude/skills/db-snapshot/SKILL.md +++ b/.claude/skills/db-snapshot/SKILL.md @@ -5,7 +5,7 @@ description: Take a snapshot of the current MongoDB dev database state on reques # DB Snapshot -Dumps `player_bios` + `player_stats` + `fetch_log` from the dev MongoDB to a local JSON file under `backend/snapshots/` (gitignored — developer-local only, preserves `_id` linkage via BSON Extended JSON). +Dumps `player_bios` + `player_stats` + `fetch_log` from the dev MongoDB to a local JSON file under `backend/scripts/snapshots/` (the script resolves its output dir relative to its own location, `scripts/DB/../snapshots`; gitignored via the blanket `backend/scripts/*` rule — developer-local only, preserves `_id` linkage via BSON Extended JSON). ## Steps @@ -36,7 +36,7 @@ Omitting `.json` writes to the script's default (`cl-2025-2026.json`) — ### 4. Report the result -Show the per-collection doc counts printed by the script and the output path (`backend/snapshots/.json`). Remind the user this file is gitignored (local-only) — it is not committed or pushed. +Show the per-collection doc counts printed by the script and the output path (`backend/scripts/snapshots/.json`). Remind the user this file is gitignored (local-only) — it is not committed or pushed. ## Restoring (reference only) From 6c12af00ce2d48d692eaeae31fdf1c4221bc57dc Mon Sep 17 00:00:00 2001 From: Yonatan Hen Date: Sat, 4 Jul 2026 17:31:59 +0300 Subject: [PATCH 3/3] docs(readme): fix DB snapshot output path, note db-snapshot skill [docs-sync] snapshot_dump.py resolves its output dir relative to its own location (scripts/DB/../snapshots), writing to backend/scripts/snapshots/, not backend/snapshots/ as previously documented. Also point to the new db-snapshot Claude Code skill that wraps these scripts. --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ef0ebe8..9a0f48a 100644 --- a/README.md +++ b/README.md @@ -178,6 +178,8 @@ Tests use `mongomock` — no running MongoDB required. ```bash # From backend/ with the stack up -python scripts/DB/snapshot_dump.py # → backend/snapshots/cl-2025-2026.json +python scripts/DB/snapshot_dump.py # → backend/scripts/snapshots/cl-2025-2026.json python scripts/DB/snapshot_load.py # restore ``` + +Claude Code users: the `db-snapshot` skill (`.claude/skills/db-snapshot/SKILL.md`) wraps these scripts for on-demand snapshots.