Hypothesis Management

Manage research hypotheses for AgentSociety experiments. Each hypothesis defines experiment groups (control/treatment) and specifies required agent classes and environment modules.

When to Use

• User says "hypothesis", "research question", "experiment groups", or "control vs treatment"
• Literature search is done and user wants to formulate testable claims
• User needs to define what to compare in a simulation experiment

Do NOT use when:

• No literature search has been done yet (use literature-search first)
• User wants to run an existing experiment (use experiment-config)

Quick Reference

Use the Python interpreter from .env. See CLAUDE.md for setup. Run commands from the workspace root through .agentsociety/bin/ags.py.

Workflow

digraph hypothesis_flow {
    rankdir=LR;
    node [shape=box, style=filled, fillcolor="#E8F4FD"];
    topic [label="read TOPIC.md\nand literature index"];
    clarify [label="clarify question\nand comparison goal"];
    names [label="agent/env names known?"];
    scan [label="scan-modules\noptional helper"];
    groups [label="define control\nand treatment groups"];
    write [label="write HYPOTHESIS.md\nand SIM_SETTINGS.json"];
    sync [label="sync TOPIC.md"];

    topic -> clarify -> names;
    names -> groups [label="yes"];
    names -> scan [label="no"];
    scan -> groups;
    groups -> write -> sync;
}

Module Selection

Every hypothesis must specify at least one agent class and one environment module. If the exact names are uncertain, use scan-modules to discover or validate them before writing SIM_SETTINGS.json.

Group JSON Format:

{
  "name": "treatment",
  "group_type": "treatment",
  "description": "Agents with high social capital scores",
  "agent_selection_criteria": "agents whose social_connections > median"
}

Common Module Combinations:

Output Structure

hypothesis_{id}/
  HYPOTHESIS.md         # Hypothesis description and groups
  SIM_SETTINGS.json     # Agent and environment module configuration
  experiment_1/
    EXPERIMENT.md
  experiment_2/
    EXPERIMENT.md

After adding/modifying/deleting a hypothesis, update TOPIC.md with the hypothesis overview and link.

Common Mistakes

Pipeline Position

Predecessors: literature-search Optional helpers: scan-modules (when module names are unknown or need validation) Successors: experiment-config

Progress Tracking

After adding a hypothesis successfully:

$PYTHON .agentsociety/bin/ags.py research-pipeline update-stage hypothesis completed --metadata '{"hypotheses_count": N}'