SKILL

---
name: cold-start-audit
description: Simulate a new user in a sandboxed environment to discover CLI tool UX friction. Use when auditing a tool's onboarding experience or running isolation-mode audits.
argument-hint: [mode|preflight|setup|run|report|init|container] <tool-name> [--mode container|local|worktree] [args]
disable-model-invocation: false
allowed-tools: Bash, Read, Write
---

Cold-Start UX Audit: AI agents simulate new users in sandboxed environments.

## Arguments

- `mode <tool-name>`: Analyze the tool's help output and recommend the appropriate sandbox isolation mode. See [Mode Advisory](#mode-advisory-mode-tool-name).
- `preflight <tool-name> --mode <mode> [mode-args]`: Validate all prerequisites before running an audit. Auto-run before `setup` and `run`. See [preflight.md](preflight.md).
- `container build <tool-name> [--dockerfile PATH]`: Auto-increment round number, check for reusable containers/images, build new image if needed, start container. See [container.md](container.md).
- `container list <tool-name>`: Show all images and containers for a tool with their status. See [container.md](container.md).
- `container cleanup <tool-name> [--keep-latest N]`: Remove old containers and images, keeping the latest N rounds. See [container.md](container.md).
- `setup <tool-name> --mode container <container-name>`: Run the filler agent to discover tool metadata from the running container and produce a filled audit prompt at `docs/cold-start-audit-prompt.md`.
- `setup <tool-name> --mode local --env KEY=VALUE [--env KEY=VALUE ...]`: Run the filler agent in local mode. Creates temp dir, sets env vars, discovers tool metadata.
- `setup <tool-name> --mode worktree --dir <source-path>`: Run the filler agent in worktree mode. Copies `<source-path>` to a temp dir, discovers tool metadata.
- `run <tool-name> --mode <mode> [mode-args]`: Full audit. Checks for existing prompt (reuse or regenerate), launches audit agent, writes findings to `docs/cold-start-audit.md`. Same mode args as `setup`.
- `report`: Read and summarize findings from `docs/cold-start-audit.md`, grouped by severity.
- `init <container-name>`: Scaffold `.claude/settings.json` with scoped permissions for the container (container mode only).


## Sandbox Modes

Three modes satisfy the core invariant — **the audit agent must not modify production state** — using different isolation mechanisms:

| Mode | Argument form | When to use |
|---|---|---|
| `container` | `--mode container <container-name>` | Tool has destructive ops (remove, delete, system writes) |
| `local` | `--mode local --env KEY=VALUE [--env KEY=VALUE ...]` | Tool writes only to self-managed state (own DB or config) |
| `worktree` | `--mode worktree --dir <source-path>` | Tool reads/writes files in the current directory |

**Container mode** (default): audit agent prefixes every command with `docker exec <container-name>`. Requires Docker and a running sandbox container.

**Local mode**: audit agent sets env vars that redirect the tool's state to a temp directory. No Docker needed. Example: `--mode local --env COMMITMUX_DB=/tmp/audit-$$/db.sqlite3`.

**Worktree mode**: audit agent runs inside a fresh copy of a directory. Example: `--mode worktree --dir /path/to/project`.

## Prompt Reuse Strategy

When running subsequent audits on the same tool:

**Check for existing prompt first:**
1. Look for `docs/cold-start-audit-prompt.md`
2. If found, read the metadata header to see the previous container name and date
3. Ask user: "Found existing prompt from [date] using container [name]. Options:
   - **Reuse** - Update only container name and date (fast, use when tool commands haven't changed)
   - **Regenerate** - Run filler agent to rediscover everything (use when tool structure changed)"

**Implementation:**
- For reuse: Use Edit tool to update container name throughout and metadata date
- For regenerate: Run the full filler agent as before

This prevents wasteful parallel execution of filler agent when audit agent doesn't need it.

## Permissions

Background agents cannot prompt for tool approval. Without an explicit `allow` rule, every Bash call is denied silently.

### Project-level (recommended, scoped)

Create `.claude/settings.json` in the project repo. Use a wildcard that covers all round numbers so it doesn't need updating each round: