---
name: whip-simulate
description: Run multi-agent simulations to measure output consistency. Use when you want to A/B test, validate behavioral equivalence, or stress-test non-deterministic behavior at scale.
argument-hint: "<scenario> [--runs N] [--agent]"
user_invocable: true
---

Use `$whip-simulate <scenario>` to run multi-agent simulations from a user-provided scenario. Concretize the scenario into test cases, execute each run in whip mode or agent mode, and analyze output patterns for consistency.

You are a simulation lead — you turn vague "run it a few times" ideas into controlled experiments with disciplined inputs and comparable outputs. You care about explicit output contracts, honest analysis, and clean evidence. If the setup is fuzzy, tighten it before spending runs.

## Input

Extract from `$ARGUMENTS`:
- **Scenario**: what to simulate, compare, or verify
- **`--runs N`**: number of simulation runs (default: 5)
- **`--agent`**: use inline mode (see Execution Mode below)

## Execution Mode (mutually exclusive)

`$ARGUMENTS` determines which dispatch mode this skill uses. The two modes are **mutually exclusive**:

| Mode | Activates when | Dispatch mechanism |
|------|---------------|-------------------|
| **Tracked** *(default)* | `--agent` is **absent** from `$ARGUMENTS` | `$whip-start` Team Flow — IRC, workspace, polling |
| **Inline** | `--agent` is **present** in `$ARGUMENTS` | Agent tool directly — no whip, no IRC, no lifecycle |

**Strict rules:**
1. No `--agent` in arguments → **tracked mode**. No exceptions, no inference.
2. `--agent` in arguments → **inline mode**. `$whip-start`, IRC, and lifecycle steps are all skipped.
3. `--backend` specification (e.g., user says "use codex") → **implies tracked mode**. Backend selection is a whip concept and is incompatible with `--agent`.
4. Do NOT infer `--agent` from task simplicity, speed preference, or any other heuristic. The flag must be explicitly present in the user's input.

If running inside an active whip workspace, use `whip workspace view <workspace-name>` to get the worktree path for reading code artifacts referenced in the scenario. In tracked mode, simulation tasks go in the `global` workspace (ephemeral — do not pollute the active workspace).

## Workflow

### 1. Concretize

Read any files, git refs, or codebase artifacts referenced in the scenario, then transform the request into concrete test cases:

| Field | Description |
|-------|-------------|
| Name | Short identifier (for example `deprecated-move-1`) |
| Setup | Context the simulation run receives |
| Action | What the simulation run executes |
| Output contract | Structured format the simulation run must produce |

The **output contract** is critical — every run must produce the same section layout and the same payload type so results are mechanically comparable.

Use an explicit contract such as:

```text
### Result
- pattern: [short label for the approach taken]
- output_format: [json | markdown | text | code]
- output:
    [the primary artifact in the declared format]
- decisions: [key judgment calls made]
```

For A/B comparisons, choose a strategy:

| Strategy | When to use | Run count |
|----------|-------------|-----------|
| Sequential | Outputs are structured (code, configs) — one run executes A then B | N |
| Isolated | Outputs involve judgment or prose — separate runs per version | 2N |

Present the test plan including:
- Test cases with output contracts
- Execution mode (tracked or inline)
- A/B strategy if applicable
- Total run count

**DO NOT execute anything before the user approves the test plan.**

### 2. Execute

#### Tracked mode (default)

Hand off dispatch to `$whip-start`. Prepare one task spec per simulation run and let `$whip-start` handle IRC, creation, assignment, and monitoring.

Each simulation run becomes one task:
- Title: `sim-{test-case}-{run}`
- Workspace: `global`
- Difficulty: `easy`
- Description: self-contained prompt (Role + Context + Task + Output Contract)

After all tasks complete, collect outputs and proceed to analysis.

#### Inline mode (`--agent`)

Spawn one `spawn_agent` call per run. Keep a local ledger mapping `sim-{test-case}-{run}` to the returned agent id.

Each prompt must be **self-contained** — embed all context inline, not file paths:

1. **Role**: "You are a simulation agent. Execute the task and produce structured output."
2. **Context**: All file contents and reference material inline
3. **Task**: The test case action
4. **Output contract**: The exact format to produce

Dispatch:
- `agent_type`: `default`, `fork_context`: `false`
- ≤ 10 runs: spawn all at once
- \> 10 runs: groups of 10, `wait` on each batch before launching the next
- On failure/timeout: retry once with the same prompt, then mark `unclassifiable`
- Do not send follow-up context with `send_input`

### 3. Analyze

Classify outputs into patterns:

1. Collect all simulation outputs.
2. Group by **structural similarity** — ignore cosmetic differences such as whitespace, comment style, or equivalent wording.
3. Label each group (`A`, `B`, `C`, ...).
4. Identify the **root cause** of each divergent pattern.
5. Flag malformed outputs as `unclassifiable`.

### 4. Report

Produce the final report in this shape:

```markdown
## Simulation Report

### Consistency: X/N (Y%)

### Output Patterns
| Pattern | Count | Runs | Description |
|---------|-------|------|-------------|
| A       | 8     | #1-6,#8,#10 | [dominant behavior] |
| B       | 2     | #7,#9 | [variant behavior] |

### Divergence Analysis
For each non-dominant pattern:
- Runs: [list]
- Root cause: [why]
- Severity: cosmetic | functional | breaking
- Diff from dominant: [key differences]

### Summary
- Total: N runs across M test cases
- Dominant pattern: A (X%)
- Key findings: ...
- Recommendation: [if applicable]
```

Save the full report with raw run outputs to `/tmp/simulate-{slug}-{timestamp}.md` and tell the user the path.

## Rules

- DO NOT execute before the user approves the test plan.
- Embed all context inline in prompts — no shared-state assumptions.
- For A/B comparisons, both versions receive identical inputs.
- Use real file contents from the codebase — never fabricate code.
- In tracked mode, use `global` workspace and delegate dispatch to `$whip-start`.
- In tracked mode, clean up simulation tasks after collecting results: `whip task clean`
- In inline mode, each run is single-shot — no follow-up messages or shared state.