exekiel179/psyclaw/analysis-plan

Analysis Plan

Use this skill only in analysis mode. Do not start academic/ARS writing from here.

Stages

1. Clarify + light EDA — Inspect data/clean once; write a compact profile. Ask only high-value clarifying questions.
2. From hypotheses to models (required table) — Before the cards, fill in the table under "Hypotheses to models" in analysis/plans/plan.md (the workspace template already has its header; keep the columns), one row per hypothesis and one per exploratory variable:

• Scope as worded: whole sample, restricted to <group> (wording such as "among X" or "no specific prediction for Y"), moderation, or exploratory, no direction.
• Implied tests follow the standing method rules in the plan template. Detail for change scores, interactions, mediation, multilevel models, SEM, and reporting is injected from the matching method skill. Do not treat this process skill as that reference.
• Status: confirmatory or exploratory; every implied test enters the multiplicity plan.

Re-read the table before writing the report and state, for each implied test, the result or why it was not run. These tests are the first candidates for the "concrete new method" option on the cards below, and the table goes into the plan you submit for approval. 2b. Decision points and verdict rules (required, before any outcome model) — Fill in the two tables under "Decision points" and "Verdict rules" in analysis/plans/plan.md.

• One row per analytic fork: sample and exclusion rules, coding and scoring keys, unit of analysis, groups analysed separately or pooled, model family and estimator, random effects and covariates, missing data, alpha, multiplicity family and method, criteria for support.
• Settled by: brief, data, convention (almost any competent analyst would choose it), or intent (the brief and data leave it open and reasonable analysts differ). A standing method rule or an injected method skill is a default, not a settlement: when the brief does not settle a fork that such a rule covers, the row is intent.
• Intent rows go on the choice cards below. With no one to ask (unattended), make the option closest to the brief's wording primary, run the main alternative as a labelled sensitivity analysis, and report both when their conclusions differ.
• Verdict rules (alpha, multiplicity family and method, what counts as support) are locked before the first outcome model. A later change is a deviation: record it with its reason in the decision log.

1. Per-analysis choices (required) — Do not dump one mega-plan and stop. For each analysis you propose, present a short decision card:

• Question (what this analysis answers)
• Options: first option must be a concrete new method; you may add alternatives; put「已经足够，先执行已选」last, never as the default recommendation
• Your recommendation with rationale
• Wait for the user to pick (or say「可以」to accept the recommendation) before adding the next analysis
• Soft「可以 / 确认」only settles the current card — it does not authorize scripts

1. Overall ritual approval (required unless `/plan auto`) — After every listed choice is decided, ask the user to type exactly:

我已审阅并批准本方案

Record that sentence as the approval ritual. Do not treat short tokens (可以 / ok / 继续) as execute authorization.

When the approver can only pick from options (no free text), a two-option approve/revise card leaves you guessing what to change. Submit the plan, including the hypotheses-to-models table, as:

• approve — approve the plan as written
• revise_<element> — one option per element a reviewer might change (for example revise_outcome, revise_covariates, revise_h2a_scope), each stating the concrete alternative you would adopt

If a revise option is chosen, apply that alternative and resubmit the same card once. Do not ask open follow-up questions about what to change.

1. Auto mode — If the user said /plan auto, proceed without ritual, but every report/script summary must state 「未经人审批」.
2. Crosscheck / verify (human-gated) — Do not start /crosscheck or /verify automatically. After scripts (or before a costly pass), ask whether to open that block; only run it after an explicit yes. Skipping must mark 「未经核对」.
3. Execute — Local reproducible scripts under analysis/scripts/ by default; MCP only for special backends or explicit request.
4. Handoff — Update analysis/HANDOFF.md before academic mode. Final Panel「核实」remains required for completion.

Volume rule

Never tell the user “分析方法已经足够了” as a closing statement. If the plan is getting long, still offer another concrete method as option 1, and only then offer「已经足够」as an explicit selectable option.

Persistence

Keep state in analysis/plans/ (/plan new|status|auto|human|run|defer|handoff). Soft「可以」acknowledges a node; the typed ritual authorizes run when approvalMode=human.

Boundaries

• Never overwrite data/raw.
• No novel stats algorithms in PsyClaw core.
• Do not merge with ARS planning.
• Model proposes crosschecks after asking; humans mark items — do not expect users to invent /verify ids themselves.