working-in-scratch-areas

Working in Scratch Areas

Overview

Helps Claude save one-off scripts and documents to persistent scratch areas instead of littering repositories with temporary files or using /tmp.

Core principles:

• Temporary work deserves permanent storage
• Scripts and documents should be documented, organized, and preserved
• Never use /tmp or project tmp/ directories for these files
• Files belong in .scratch/ subdirectories with context

Announce at start: "I'm using the working-in-scratch-areas skill."

When to Use

Use this skill when creating:

• One-off debug scripts
• Analysis or investigation tools
• Temporary documentation or reports
• Quick test scripts
• Data extraction utilities
• Monitoring or diagnostic tools

Don't use for:

• Production code that belongs in the main codebase
• Configuration files that should be committed
• Tests that belong in the test suite
• Documentation that should be in docs/

NEVER use /tmp or project tmp/ directories. Always use .scratch/ for temporary work.

Setup Workflow

Check for Existing Scratch Area

First, check if a scratch area already exists:

test -L .scratch && echo "Scratch area exists" || echo "No scratch area"

If the symlink exists, verify gitignore is configured (see below), then you're ready to use it.

Setting Up New Scratch Area

When no scratch area exists:

1. Detect: "I notice this repository doesn't have a scratch area set up."
2. Check CLAUDE.md: Check if scratch areas location is configured in ~/.claude/CLAUDE.md
3. If not configured: Ask user where they want scratch areas with AskUserQuestion tool
4. Run setup script with the chosen location
5. Optionally save the location to CLAUDE.md for future use

Setup Steps:

# 1. Get repo root
git rev-parse --show-toplevel
# Output: /Users/josh/workspace/some-repo

# 2. Check if configured in CLAUDE.md
grep -i "scratch areas:" ~/.claude/CLAUDE.md

# 3a. If configured, run setup (reads from CLAUDE.md automatically)
cd /Users/josh/workspace/some-repo && ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh

# 3b. If not configured, ask user for location and run with --areas-root
cd /Users/josh/workspace/some-repo && ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh --areas-root ~/workspace/scratch-areas

# 3c. If user wants to save preference, add --save-to-claude-md flag
cd /Users/josh/workspace/some-repo && ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh --areas-root ~/workspace/scratch-areas --save-to-claude-md

# 4. Verify gitignore (see Gitignore Setup section below)

What the script does:

• Checks ~/.claude/CLAUDE.md for configured scratch areas location (or accepts --areas-root flag)
• Creates scratch areas root directory and repository-specific subdirectory
• Creates symlink {repo-root}/.scratch → scratch area
• Creates README from template with repository-specific information
• Optionally saves location to CLAUDE.md with --save-to-claude-md flag

Script Location: ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh

Script Options:

• --areas-root PATH - Specify scratch areas root directory (required if not in CLAUDE.md)
• --save-to-claude-md - Save the areas root to ~/.claude/CLAUDE.md for future use
• --help - Show help message

Configuring Scratch Areas Location

The setup script checks ~/.claude/CLAUDE.md for your preferred scratch areas location. If not found, you must provide --areas-root flag.

To configure in CLAUDE.md, add:

## Scratch Areas

When using the `dev-tools:working-in-scratch-areas` skill, create scratch areas in `~/workspace/scratch-areas` directory.

Suggested locations to offer user:

• ~/workspace/scratch-areas - Central location for all scratch areas
• ~/workspace/pickled-scratch-area/areas - If using the full pickled-scratch-area repository
• $(dirname "$REPO_ROOT")/scratch-areas - Sibling to current repository (for project-specific scratch areas)

Use AskUserQuestion to present these options when not configured.

Gitignore Setup

After creating scratch area, ensure .scratch is gitignored:

Preferred: Global gitignore

# Check if globally ignored
git config --global core.excludesfile
# Verify .scratch is in that file

# If not set up, add to global gitignore
echo ".scratch" >> ~/.gitignore
git config --global core.excludesfile ~/.gitignore

Alternative: Project .gitignore

If global gitignore isn't used:

# Add to project .gitignore if not present
grep -q "^\.scratch$" .gitignore || echo ".scratch" >> .gitignore

Why global is preferred: Prevents accidental commits across all repositories.

Subdirectory Organization

Always Use Subdirectories

Organize scratch files into topic-specific subdirectories:

.scratch/
├── database-debug/
│   ├── README.md
│   ├── check-connections.sh
│   └── query-results.txt
├── performance-analysis/
│   ├── README.md
│   ├── profile-api.sh
│   └── results-2024-11-05.md
└── data-extraction/
    ├── README.md
    └── extract-users.rb

Do NOT create files directly in .scratch/ root. Always use a subdirectory.

Subdirectory Workflow

1. Check for existing relevant subdirectory:

``bash ls -la .scratch/ ``

1. If relevant subdirectory exists: Ask user if it makes sense to use it:

• "I see there's already a .scratch/database-debug/ directory. Should I add this script there, or create a new subdirectory?"

1. If creating new subdirectory:

• Use descriptive names: database-debug, api-performance, user-data-extraction
• Create a README.md explaining the purpose

1. Subdirectory README required:

Every subdirectory MUST have a README.md describing:

• What kind of files are stored here
• What problem/investigation spawned these files
• How files relate to each other (if at all)

Example subdirectory README:

# Database Connection Debugging

## Purpose

Scripts and notes for investigating database connection timeout issues reported on 2024-11-05.

## Files

- `check-connections.sh` - Monitor active connections
- `query-slow-queries.sql` - Identify slow queries
- `findings.md` - Investigation notes and conclusions

## Status

Investigation completed 2024-11-08. Issue was connection pool exhaustion.
Keeping files for reference.

Script Creation Rules

When creating scripts in scratch areas, follow these mandatory rules:

1. Always Use Proper Shebang

Every script MUST start with #!/usr/bin/env <command>:

#!/usr/bin/env bash

#!/usr/bin/env python3

#!/usr/bin/env ruby

#!/usr/bin/env node

Why: Enables proper allow list management and makes scripts directly executable.

2. Make Scripts Executable

After creating a script (file with shebang), use the helper script to make it executable:

~/.claude/skills/working-in-scratch-areas/scripts/make-executable .scratch/subdir/script.sh

Why:

• Allows calling scripts directly (./script.sh) instead of through interpreter
• Helper script gets approved once, not per-file
• Consistent executable permissions
• Validates shebang exists (prevents making non-script files executable)

Never use chmod +x directly - use the helper script instead.

Important: Only make script files executable (files with shebangs). Do NOT make markdown files, text files, or other non-script files executable. The helper script will reject files without shebangs.

3. Call Scripts Directly

When invoking scripts, use direct execution:

✅ CORRECT:

./.scratch/database-debug/check-connections.sh

❌ WRONG:

bash .scratch/database-debug/check-connections.sh # Don't use interpreter
ruby .scratch/data-extraction/extract-users.rb    # Don't use interpreter

Why: Direct execution