clean-up

Clean Up Session Artefacts

Audit the current branch for docs and files created during the development session (planning, review, grilling, specs) rather than as permanent codebase additions. Present a classified list for confirmation, then delete only what the user approves.

Process

1. Discover what was added

# Tracked files added on this branch
git diff --name-only --diff-filter=A $(git merge-base HEAD origin/develop 2>/dev/null || git merge-base HEAD develop) HEAD

# Untracked files (check .claude/specs/, docs/, etc.)
git ls-files --others --exclude-standard

2. Read content before classifying

For every non-code file discovered, read it before assigning a verdict — filename heuristics alone are unreliable. Look for:

• Frontmatter Status: fields (e.g. draft, pre-grill, sharp (self-grilled)) → DELETE
• Prose explaining WHY something was built (design decisions, trade-offs, deferred items) → KEEP
• Grilling transcripts, implementation specs, fix plans → DELETE
• "Not a bug (verified)" sections, named deferred decisions → lean KEEP

3. Classify each file

Assign one of three verdicts:

DELETE — created to serve the session, now superseded by the code:

• .claude/specs/ — all files (draft plans, self-grill specs, implementation specs)
• .planning/ — if tracked (should be gitignored; if not, remove and add to gitignore)
• Files with frontmatter Status: draft, pre-grill, or self-grilled
• Files whose entire purpose was to plan or review work that is now in commits

KEEP — has genuine value for future readers of the codebase:

• Design specs explaining WHY (architecture decisions, trade-offs, deferred items, verified-not-a-bug rationale) — e.g. DESIGN-SPEC.md
• ADRs (docs/adr/)
• User-facing operational docs (how to run a script, how to use a feature)
• Agent files that have clear ongoing utility beyond this branch — read the description: field; if it's well-formed and covers a domain the codebase will keep touching, lean KEEP

ASK — genuinely ambiguous; ask the user before deciding:

• CODE-REVIEW.md files — lean KEEP if the file contains deferred rationale, "verified not a bug" sections, or named architectural decisions; lean DELETE if it's purely a list of findings that are all resolved and in commits
• Agent files added on this branch but unrelated to the feature — read the description; if it's well-formed and future-useful, suggest keeping it (or moving to ~/.claude/agents/ globally); if it looks accidental or low-quality, suggest deleting
• Any doc in docs/ that doesn't clearly fit KEEP or DELETE

4. Present the classification

Show a numbered list before touching anything — numbers are required so the user can skip specific items:

Session artefacts to DELETE:
  1. .claude/specs/foo-draft.md        [untracked] — draft pre-grill spec
  2. .claude/specs/foo-final.md        [untracked] — self-grill implementation spec
  3. docs/feature/CODE-REVIEW.md       [tracked]   — code review working doc (all findings resolved)

Files to KEEP (no action):
  - docs/feature/DESIGN-SPEC.md        [untracked] — design rationale, worth keeping
  - .claude/agents/my-agent.md         [tracked]   — useful ongoing agent

Files to ASK about:
  ? .claude/agents/unrelated-agent.md  [tracked]   — unrelated to this feature; keep or delete?

Note: [tracked] deletions will be staged with git rm and require a commit.
      [untracked] deletions are permanent immediately — not recoverable from git.
      All [tracked] deletions are recoverable via git after commit.

Also flag any KEEP files that are untracked — they may need to be staged:

Note: docs/feature/DESIGN-SPEC.md is KEEP but currently untracked — run `git add` if you want it in the PR.

Ask: "Delete the items listed above? Enter y to delete all, n to cancel, or numbers to skip (e.g. '1 3' to skip items 1 and 3)."

5. Delete approved files

For each confirmed deletion, check whether tracked or untracked:

# Tracked files:
git rm <file>

# Untracked files:
rm <file>

# Remove any directories that are now empty (only the ones affected):
for dir in $(dirname <deleted-files> | sort -u); do
  find "$dir" -type d -empty -delete 2>/dev/null || true
done

6. Commit tracked deletions — with confirmation

If any tracked files were deleted, show the staged diff and ask before committing:

Staged deletions:
  deleted: .claude/agents/pbs-scripting-expert.md
  deleted: docs/feature/CODE-REVIEW.md

Commit these as "chore: remove session artefacts before merge"? (y/n)

If yes:

git commit -m "chore: remove session artefacts before merge"

Note: lefthook will run on this commit (prettier, lint, typecheck). If hooks fail, fix them before proceeding.

Classification heuristics (quick reference)

File pattern	Default	Notes
.claude/specs/*	DELETE	Always session artefacts
.planning/* (if tracked)	DELETE	Should be gitignored; also add to .gitignore
*-PLAN.md, *-RESEARCH.md	DELETE	Planning artefacts
*-CONTEXT.md in .claude/	DELETE	GSD context docs
*-CONTEXT.md in docs/ or repo root	ASK	Could be a Matt-Pocock domain vocabulary doc — read it first
DESIGN-SPEC.md	KEEP	Explains WHY
docs/adr/*	KEEP	Always keep
CODE-REVIEW.md	ASK	Read content — keep if WHY rationale exists, delete if pure findings list
.claude/agents/*.md — well-formed, future-useful	KEEP	Read description; if covers a domain the codebase will keep touching, keep
.claude/agents/*.md — accidental / low-quality	ASK	Suggest delete or move to global ~/.claude/agents/
Grilling transcript files	DELETE

Hard rules

• Never delete code files (.ts, .tsx, .py, .tf, etc.), tests, or config
• Never delete without showing the numbered list and getting confirmation
• Read the file content for anything not obviously in .claude/specs/ before classifying
• When in doubt, classify as ASK rather than DELETE
• A doc explaining WHY is always KEEP; a doc explaining HOW we got to the code is DELETE