/v1.0.0

name: agentsociety-analysis
version: 1.0.0
description: Use when an experiment run has completed and the user wants rigorous interpretation, claim-driven charts, bilingual reports, or cross-hypothesis synthesis from simulation data. Also use when multiple charts or PNG/JPG assets must be assembled into one labeled composite figure. Requires high-quality narrative and evidence traceability, not only harness gate PASS.

Analysis

Use this skill for interactive experiment analysis. **You (Claude Code) own orchestration, scientific judgment, and user dialogue.** The harness CLI enforces **structural** reproducibility and **phase gates**; it does not replace your reasoning.

**Quality before gates:** Read `references/analysis-quality.md` at the start of each phase. A `validate-*` PASS with weak science is a failure — improve claims, evidence, and prose first, then attest.

Harness vs LLM (read first)

| Layer | Who | What | | --------------- | ---------------------------- | ------------------------------------------------------------------------------------ | | **Structural** | Python `validate-*` | Files exist, JSON schemas valid, DB/tables/artifacts consistent | | **Attestation** | You via `record-attestation` | Phase-complete judgment: findings, limitations, user alignment (schema-checked only) | | **Narrative** | You | Reports, synthesis, claim wording, chart design, caveats | | **Memory** | You + user confirmation | Reviewable lessons, reusable recipes, and confirmed preferences |

After each phase: (1) do the analytical work with the user, (2) run `validate-<phase>`, (3) run `record-attestation` with rubric from `references/phase-attestation.md`, (4) `gate-status` or `advance`.

After release or synthesis, run the experience loop from `references/experience-memory.md` when the user wants learning: `draft-reflection` → ask user feedback / `record-feedback` → `review-reflection` → `promote-reflection`. Promoted memory is active by default in `intake`, `status`, and `run-loop`; inspect it with `memory-context`. Do not promote user preferences unless the user explicitly confirms them.

References: `references/harness-contract.md`, `references/phase-attestation.md`, `references/analysis-quality.md`, `references/experience-memory.md`, `references/json-payloads.md`.

**JSON payloads:** `--payload` accepts a JSON object or a `.json` file path. The CLI repairs minor syntax issues via `json-repair` before Pydantic validation — still fix wrong fields, not escaping.

Overview

Analyze experiment results from AgentSociety simulations. Explore data interactively, produce targeted visualizations or composite figures, and write bilingual reports with optional cross-experiment synthesis.

The plotting and figure-assembly parts of this skill follow a contract-first structure adapted to the `agentsociety2` analysis stack: fixed Python backend, replay-backed evidence tracking, `ags.py analysis` tool surface, and report asset management under `presentation/` and `synthesis/`.

When to Use

• An experiment run has completed and either `run/replay/_schema.json` or legacy `run/sqlite.db` exists in the run directory.
• The user asks to analyze results, explore data, visualize data, combine multiple assets into one figure, create charts, or write analysis reports.
• The user references a hypothesis or experiment ID and wants to understand outcomes.

**Do NOT use when:**

• The experiment run has not completed (no `run/replay/_schema.json`).
• The user only wants to configure or launch experiments (use run-experiment instead).

Quick Reference

| Command | Purpose | | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis load-context --workspace . --hypothesis-id ID --experiment-id ID` | Load experiment context | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis list-tables --data-path PATH` | List replay-backed tables/datasets | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis data-summary --data-path PATH` | Full data summary | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis query-data --data-path PATH --sql "SELECT ..."` | Read-only SQL query | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis run-eda --data-path PATH --output-dir DIR --type TYPE [--workspace . --hypothesis-id ID]` | Generate EDA; auto-registers explore artifacts when hypothesis id is set | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis compose-figure --workspace . --hypothesis-id ID --spec FILE` | Combine claim-scoped raster charts/images into one labeled figure | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis collect-assets --workspace . --hypothesis-id ID --experiment-id ID --output-dir DIR` | Collect assets; DIR may be the report root or its `assets/` child | | `$PYTHON_PATH .agentsociety/bin/ags.py analysis sync-report-assets --workspace . --hypothesis-id ID --experiment-id ID`