From ai4ss-skills
Executes the first analysis loop from a design brief and analysis-ready data, producing tables, figures, model outputs, logs, and a run manifest.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai4ss-skills:research-analysis-runnerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Execute the first analysis loop from a design brief and analysis-ready materials. The skill produces outputs that can be reviewed, not final claims.
agents/openai.yamlexamples/invalid_analysis_readiness_missing_variable.csvexamples/ready_panel.csvexamples/valid_analysis_readiness_check.csvexamples/valid_analysis_run_manifest.csvreferences/analysis-workflow.mdreferences/manifest-schema.mdreferences/prompt-pack.mdreferences/readiness-schema.mdreferences/worked-example.mdscripts/check_runtime_contract.pyscripts/validate_analysis_manifest.pyscripts/validate_analysis_readiness.pyExecute the first analysis loop from a design brief and analysis-ready materials. The skill produces outputs that can be reviewed, not final claims.
This skill answers: "设计和数据已经有了,第一批可检查结果怎么跑出来?" Its value is not deciding what results mean; it is making scripts, outputs, logs, and interpretation boundaries visible.
Run the analysis plan, preserve logs, and stop before interpretation outruns evidence. Tables and figures are outputs; claims require downstream review and author judgment.
scripts/check_runtime_contract.py to verify the analysis data path, required packages, required columns, and output directories in the same R/Python environment that will run the script.Rscript --vanilla or a fresh Python process) after edits so hidden workspace objects cannot satisfy missing variables.Do not choose a final specification, select favorable results, write result prose, certify robustness, or declare causal validity. If the requested analysis changes the design, route back to study-design-builder or methods-reviewer.
This skill executes the Answer strategy part of the MIDA spine against a declared design source and analysis-ready data source.
It must record script path, output path, sample note, diagnostic or uncertainty output when available, and interpretation_boundary. It cannot revise the inquiry, pick preferred results after seeing outputs, or convert outputs into final claims.
When a .aiss model is present, every analysis output that bears on a declared concept, causal implication, or empirical bridge must carry the relevant model identifiers in the manifest.
Before execution, the skill must pass the analysis_readiness_check.csv gate. This gate validates the clean data or extracted evidence object against the declared analysis plan, required variables, sample flow, variable provenance, and .aiss bridge alignment. This is the local regression-ready seam from ai4ss-skills, generalized to all first-pass analysis objects.
study_design_brief.md, study_design_declaration.csv, research_model.aiss, analysis_plan_scaffold.md, analysis_readiness_check.csv, analysis-ready data, variable dictionary, scripts, or source extraction outputs.analysis_readiness_check.csv when missing, scripts or notebooks, tables, figures, logs, and docs/analysis_run_manifest.csv.route_id, design_source, target_inquiry, analysis_plan_path, data_source, unit_of_analysis, required_variables, available_variables, missing_variables, sample_flow_path, merge_audit_path, variable_provenance_path, readiness_status, script_path, output_path, output_type, model_or_operation, sample_note, interpretation_boundary, validation_command, ai4ss_model_path, model_id, concept_id, causal_id, bridge_id, ai4ss_check_status, next_skill_route.methods-reviewer, academic-writing-scaffold, research-slides-builder, study-design-builder, research-data-builder, or ask_author.Use this skill only when a design source and analysis-ready material exist. Hand data construction or merge repair to research-data-builder. Hand design ambiguity to study-design-builder. Hand result-claim, inference, robustness, or identification audit to methods-reviewer. Hand writing support to academic-writing-scaffold only after methods review or author approval.
Step -1: Check readiness
-> Read AGENTS.md, design brief, analysis plan, data dictionary, and available data/scripts.
-> Confirm unit, required variables, output paths, and no-write zones.
-> Run `scripts/check_runtime_contract.py --cwd <project> --path <input-or-quoted-glob> --data <analysis-data> --required-columns <cols> --key-columns <keys> --python-import <module> --r-package <pkg> --expect-output <path> --fresh-after <run-start-iso>` with the checks that match the run.
-> If `research_model.aiss` is referenced, confirm it passes `scripts/validate_ai4ss_model.py` or record why not.
-> Create or validate `analysis_readiness_check.csv` with `scripts/validate_analysis_readiness.py`.
-> If readiness is `blocked`, stop and route back to design, data, methods, or author decision.
-> If design_source, data_source, or analysis readiness evidence is missing, stop and route back.
Step 0: Plan one analysis loop
-> Choose the smallest requested operation: descriptive table, balance table, baseline model, figure shell, coding summary, or robustness candidate list.
-> State expected outputs, script paths, log paths, and validation checks.
Step 1: Execute reproducibly
-> Write or update minimal scripts under scripts/ when needed.
-> Save outputs under output/ or docs/ according to project conventions.
-> Preserve command, timestamp, package versions when practical, sample notes, and warnings.
-> If an execution fails, fix and rerun before creating presentation-ready tables or figures.
Step 2: Build manifest
-> Record every table, figure, model object, coding output, and log in `analysis_run_manifest.csv`.
-> State interpretation boundaries for each output.
-> Link each relevant output to `model_id`, `concept_id`, `causal_id`, or `bridge_id` from the `.aiss` model.
Step 3: Stop for review
-> Do not narrate final findings.
-> Route outputs to `methods-reviewer` for validity and claim review, or to `research-slides-builder` only for verified teaching/demo artifacts.
docs/analysis_run_manifest.csv.docs/analysis_readiness_check.csv before execution when one does not already exist.scripts/.output/tables/, output/figures/, or project-defined paths.output/logs/.scripts/check_runtime_contract.py --cwd <project> ... before or after execution to check files/globs, Python imports, R packages, data schema, duplicate CSV keys, expected outputs, and output freshness. Quote shell globs.scripts/validate_analysis_manifest.py <path> to check the analysis run manifest.scripts/validate_analysis_readiness.py <path> to check whether clean data can enter analysis execution.scripts/validate_ai4ss_model.py <path-to-research_model.aiss> before treating model-linked outputs as reviewable.analysis_readiness_check.csv to be ready or explicitly warn before execution.| File | Content | Read when |
|---|---|---|
| analysis-workflow.md | Readiness checks, execution loop, logging, and stop rules | Running analysis from a design brief |
| manifest-schema.md | CSV schema for analysis outputs and interpretation boundaries | Creating or validating analysis manifests |
| readiness-schema.md | CSV schema for the regression-ready / analysis-ready gate | Checking cleaned data against a declared analysis plan |
| prompt-pack.md | Copy-ready prompts for readiness checks, first analysis loops, and review handoffs | Turning design/data into execution |
| worked-example.md | Digital-government feasibility table and baseline runner example | Teaching or demonstrating the skill |
npx claudepluginhub siyaozheng/ai4ss-skills --plugin ai4ss-skillsGenerates an executable empirical analysis plan from study_spec.md, audit report, and cleaned data structure. Outputs analysis_plan.md for human approval before analysis execution.
Executes pre-registered analysis plans with review checkpoints, validating each step and reporting results. Useful for reproducible data analysis without subagents.
Builds auditable social-science data pipelines: raw files to analysis samples with merge audits, missingness checks, and reproducible scripts.