swarm: Command for Claude Code

/write_paper

Scaffold a research paper from SWARM run data, pre-populated with methods, results tables, and figure references.

Usage

/write_paper <title_slug> [scenario_ids...] [--figures]

Examples:

• /write_paper collusion_dynamics collusion_detection network_effects --figures
• /write_paper governance_sweep (uses all runs in SQLite)
• /write_paper adversarial_threshold baseline redteam_v1 redteam_v3 collusion

Behavior

1. Query run data from the scenario_runs SQLite table (at $SWARM_RUNS_DB_PATH or runs/runs.db):

   • If scenario_ids are given, filter to those. Otherwise use all rows.
   • Extract: scenario_id, seed, n_agents, n_epochs, acceptance_rate, avg_toxicity, welfare_per_epoch, adversarial_fraction, collapse_epoch, notes.
   • If multiple seeds exist per scenario, compute mean +/- std for each metric.

2. Read scenario configs: for each scenario_id, read the corresponding scenarios/<id>.yaml to extract:

   • Agent composition (types, counts, adversarial fraction)
   • Governance parameters (tax rate, reputation decay, circuit breakers, etc.)
   • Network topology (if any)
   • Simulation parameters (epochs, steps, seed)

3. Generate docs/papers/<title_slug>.md with this structure:

# <Title from slug, title-cased>

**Authors:** <resolve from $SWARM_AUTHOR, then git config user.name, then ask user>
**Date:** <today>
**Framework:** SWARM v<from pyproject.toml>

## Abstract
[TODO: 150-word summary. Key numbers pre-filled below.]
- N scenarios, M total epochs, K agents
- Key finding 1: [TODO]
- Key finding 2: [TODO]

## 1. Introduction
[TODO: Motivation and research question]

## 2. Experimental Setup

### 2.1 Scenarios
| Scenario | Agents | Adversarial % | Epochs | Governance |
|----------|--------|---------------|--------|------------|
<auto-populated from scenario YAMLs>

### 2.2 Governance Parameters
<auto-populated table of governance config per scenario>

### 2.3 Metrics
- **Acceptance rate**: fraction of interactions accepted by governance
- **Toxicity**: E[1-p | accepted], expected harm from accepted interactions
- **Welfare**: cumulative payoff across agents per epoch
- **Quality gap**: E[p|accepted] - E[p|rejected]

## 3. Results

### 3.1 Cross-Scenario Summary
| Scenario | Acceptance | Toxicity | Welfare/Epoch | Collapse? |
|----------|-----------|----------|---------------|-----------|
<auto-populated from SQLite data>

### 3.2 Detailed Analysis
[TODO: Narrative analysis of patterns]

<figure references if --figures>

## 4. Discussion
[TODO: Interpretation, regime classification, threshold findings]

## 5. Conclusion
[TODO: 1-paragraph summary of key findings, implications, and future work]

## 6. Limitations
[TODO: Known limitations of this analysis]

## 7. References
[TODO]