working-in-scratch-areas

What this skill does

# 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:

```bash
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:**

```bash
# 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:**

```markdown
## 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**

```bash
# 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:

```bash
# 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/
   ```

2. **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?"

3. **If creating new subdirectory:**

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

4. **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:**

```markdown
# 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>`:

```bash
#!/usr/bin/env bash
```

```python
#!/usr/bin/env python3
```

```ruby
#!/usr/bin/env ruby
```

```javascript
#!/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:

```bash
~/.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:**

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

❌ **WRONG:**

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

**Why:** Direct executio