archive-session

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

1. 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.

2. 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.

3. 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).

4. 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._
   

5. 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.