| name | archive-session |
| description | Archive the current Claude session into development/<date-slug>/ (transcript, statistics, analytics scaffold) at the end of a feature, before committing. User-invoked only — type /archive-session. |
| disable-model-invocation | true |
| argument-hint | [date-slug] |
Archiving a development session
Run this at the end of a feature-development session, after the work is done but
before committing. It populates the feature's development/<YYYY-MM-DD-slug>/
folder with the record artifacts, then hands back to the user to commit.
Do the deterministic, secret-sensitive work (rendering, scrubbing, token math) via
development/finalize-session.py — never eyeball-redact a transcript yourself. This
skill's job is only to (a) figure out the target folder, (b) capture the two things
the script can't reach from outside a live session, and (c) run the script.
Steps
-
Determine the target folder. It is development/<YYYY-MM-DD-slug>/ for the
feature just built. If the user passed a slug as the argument, use
development/<that>/. Otherwise infer it from the active SPEC.md, the git branch,
or the feature under discussion; if it's ambiguous, ask the user. Create the folder
if it doesn't exist. If prompts weren't saved yet, remind the user that
NN-*.prompt.md files and any design-notes/ are part of the record.
-
Capture in-session-only data to a gitignored *.raw.txt file in the folder:
- /usage (dollar cost) — you cannot invoke
/usage yourself (it's a
built-in CLI command, not a tool). Ask the user to run /usage and paste its
output, then save that verbatim to <dir>/usage.raw.txt. This is the source of
the cost figure — the script has no price table. If the user skips it, proceed;
the cost section will just say it wasn't captured.
The .raw.txt file is gitignored; the script folds its contents into
statistics.md.
-
Run the script. From the repo root:
python development/finalize-session.py --dir development/<YYYY-MM-DD-slug> \
[--usage-capture development/<YYYY-MM-DD-slug>/usage.raw.txt] \
[--label NN]
It defaults to the newest session JSONL under ~/.claude/projects/-workspace/.
Pass --label NN only for a feature spanning multiple sessions (produces
transcript-NN.md / statistics-NN.md). Omit --usage-capture if you didn't create it.
This writes transcript.md (scrubbed, committed), transcript.raw.md (gitignored),
and statistics.md (committed).
-
Scaffold analytics.md in the folder if it doesn't already exist — a short
template for the user's own narrative analysis (distinct from the auto-generated
statistics.md, which is machine-written; do not hand-edit statistics.md):
# Analytics — <feature>
_Your narrative: what went well, what to do differently, decisions worth remembering._
-
Verify and report — do NOT commit. Confirm transcript.md scrubbed cleanly
with a value-shaped grep (matches actual secret VALUES, not prose mentions of
the names — a session that merely discusses SMTP_PASSWORD etc. is fine):
grep -nE '(SMTP_PASSWORD|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|CLOUDFLARE_API_KEY|CLOUDFLARE_EMAIL)[[:space:]]*[=:][[:space:]]*[^[:space:]«]|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|Bearer [A-Za-z0-9._-]{12,}' development/<dir>/transcript.md
This should return nothing; any hit is a real secret value that slipped the regex —
surface it, don't commit. (A bare quoted word that happens to look like a token is
left alone by design.) List what was written. Then tell the user the folder is ready
and that they can ask you to commit everything (code + development/<dir>/) in one
commit, with you writing the commit message.
