---
name: power-analysis
description: >
  Use when the user is planning a two-arm comparison (an A/B test, a simple RCT, a behavioral study, or
  a two-model/two-config evaluation) and needs to size it and preregister it before collecting data —
  finding the per-group sample size that hits target statistical power for the smallest effect worth
  detecting, auditing the design against a validity checklist, and locking it in a preregistration.
  Only for a single two-arm comparison with one primary outcome. Not for factorial, repeated-measures,
  clustered/multilevel, time-series, adaptive, or survival designs; not for analyzing data already
  collected; not for choosing the outcome or manipulation from domain knowledge.
compatibility: Requires Python 3.9+
metadata:
  version: "0.1.0"
---

# Power Analysis Loop

A **power-analysis-and-preregister** loop for a **two-arm comparison**. The artifact is the study's
statistical plan; the feedback signal is two parts — **statistical power** (estimated by Monte-Carlo
simulation of the planned test) and a **count of validity flaws**. Each iteration simulates power,
solves for the sample size that reaches the target, audits the design for flaws, and revises — until
power clears the target **and** the flaw list is empty. The deliverable is a sample-size justification
plus a preregistration that pins the hypothesis, primary outcome, analysis, sample size, and stopping
rule before any data is seen.

## Scope & limitations
This loop does exactly three things, in a loop: **(1)** computes power and required sample size for a
**two-group comparison** by simulation, **(2)** runs a fixed **validity checklist** over the design,
and **(3)** writes a **preregistration**. The vendored power model (`tools/power_sim.py`) covers
**two-sample mean** (continuous outcome) and **two-proportion** (binary outcome) tests only.

It is **not** a general experiment designer. It does **not** handle factorial, repeated-measures,
clustered/multilevel, time-series, adaptive, or survival designs; it does **not** pick your outcome
measure or manipulation from domain knowledge; and it does **not** analyze data you have already
collected. For those, the power numbers here do not apply — use a design-appropriate power method. If
the study is not a simple two-arm comparison, say so and stop rather than reporting a power that does
not match the planned analysis.

## When to use
Use this to size and preregister one two-arm comparison whose primary outcome is a continuous mean or a
binary rate. Default to powering for the **minimal effect of interest** the user states; if they are
unsure of that effect, help them set it from a baseline and a smallest-meaningful difference rather than
an optimistic guess — a design "powered" for an effect bigger than reality is a fiction. If the study is
not a two-arm comparison, stop and point to a design-appropriate method.

## Setup
Resolve bindings interactively. If `loop.run.yaml` exists in the working dir, load it, confirm the
values in one line, and skip to the loop. Otherwise: on Claude Code (the `AskUserQuestion` tool is
available) infer a likely value for each binding and present it as the recommended option; on other
hosts ask each as a quoted plain-text prompt. Then write `loop.run.yaml` (format:
`examples/run.example.yaml`) and confirm the values before creating any other files.

| binding | meaning | default | how to infer |
|---|---|---|---|
| `<hypothesis>` | the claim the experiment tests | — | ask the user |
| `<outcome>` | primary outcome type + minimal effect of interest: continuous (`baseline_mean`, `sd`, `min_effect`) **or** binary (`baseline_rate`, `min_lift`) | — | ask; this fixes the effect size power is computed at |
| `<target_power>` | power the design must clear | `0.80` | — |
| `<alpha>` | significance level | `0.05` | — |
| `<power_cmd>` | invocation of the vendored simulator | `python3 <skill_dir>/tools/power_sim.py --design <two-sample-mean\|two-proportion> --effect <e> [--sd <sd> \| --baseline <p0>] --alpha <alpha> --n <n_per_group>` | — |
| `<design_doc>` | output design + preregistration file | `<sandbox_root>/design.md` | — |
| `<sandbox_root>` | where design + ledger live | `./sandbox` | — |
| `<budget>` | max iterations | 8 | — |

`<power_cmd>` prints one JSON object, `{"power", "n_per_group", ...}`. **Run** it to get the power; never
estimate power by hand.

## The loop
Copy this checklist and tick items off:
- [ ] Iteration 0 — draft the design to `<design_doc>`; record nothing as final.
- [ ] **Simulate** power: run `<power_cmd>` at the current `n` and the assumed effect.
- [ ] **Solve N**: if power `< <target_power>`, re-run at larger `n` (step up, then bisect) until it clears.
- [ ] **Audit validity**: list every flaw from the checklist below.
- [ ] **Revise**: fix the highest-priority flaw, set `n` to the power-adequate value, update `<design_doc>` (+ Preregistration section).
- [ ] Append a ledger row; stop when power clears the target **and** no flaws remain, or at `<budget>`.

**Iteration 0 — draft.** Write a first design to `<design_doc>`: the arms/conditions, the unit of
analysis and how units are assigned, the primary outcome and the exact planned test, the assumed effect
size (from `<outcome>`), and a first sample-size guess. Record nothing as final yet.

**Then, until stop (power met + no flaws, or budget):**

1. **Simulate power.** Run `<power_cmd>` at the current per-group `n` and the assumed effect, with the
   `--design` matching the planned test. Record the achieved power.
2. **Solve N.** If `power < <target_power>`, re-run the simulation at larger `n` — step up (e.g. double),
   then bisect — until power clears the target, and adopt that `n`.
3. **Audit validity.** Check the design against the checklist and list every flaw found:
   - **Confounding / no control** — is there a concurrent control group, or is the comparison against a
     historical/other-source baseline that differs in other ways?
   - **Randomization** — are units randomly assigned? If not, selection bias threatens any effect.
   - **Selection / sampling** — is the sample representative of the population the claim is about?
   - **Multiple comparisons** — more than one outcome/subgroup tested without correction?
   - **Optional stopping / peeking** — is there a pre-specified stopping rule, or will analysis run
     repeatedly until significant?
   - **Outcome & analysis pre-specification** — are the primary outcome and its single planned test
     fixed in advance (not chosen after seeing data)?
   - **Measurement** — is the outcome measured reliably and blind to condition where possible?
4. **Revise.** Fix the highest-priority flaw (or a tightly-coupled pair that cannot be fixed
   independently, such as adding a concurrent control and randomizing assignment to it) and set `n` to
   the power-adequate value. Update `<design_doc>`, including a **Preregistration** section: hypothesis,
   primary outcome, the one planned analysis, sample size + how it was derived, randomization scheme, and
   the stopping rule.
5. **Log** one ledger row and continue.

**Stop** when `power ≥ <target_power>` **and** the flaw list is empty, or at `<budget>`. Report the
final design + preregistration, the achieved power and required `n`, and — if stopping on budget — the
flaws still outstanding.

## Ledger
`<sandbox_root>/ledger.tsv`, tab-separated, never commas in the text. Header:
```
iter	n_per_group	power	open_flaws	change
```
Example:
```
iter	n_per_group	power	open_flaws	change
0	50	0.50	2	draft: volunteers vs last-year cohort, n=50
1	100	0.80	1	solved n for 80% power at d=0.4
2	100	0.80	0	randomized concurrent control; pre-specified single primary outcome + stopping rule
```
Report the **best** iteration: the final design, the achieved power and required `n`, and any flaws
still open if stopping on budget.

## Constraints
- **Power is computed at the minimal effect of interest**, not an optimistic one, because a design
  powered for an effect bigger than reality detects nothing real — and the `--design` in the simulation
  must match the test named in the design. Do not edit `tools/power_sim.py`.
- **A design does not pass on power alone** — an adequately powered but confounded or non-randomized
  design still fails; both gates (power and flaws) must clear.
- **Preregister before data**, so the eventual test is confirmatory rather than chosen after seeing
  results: the analysis, outcome, sample size, and stopping rule are fixed in advance.
- **One primary outcome and one planned test** drive the power and the verdict; secondary analyses are
  labeled exploratory.
- The sandbox is self-contained — no `../` escapes. Do not pause the loop to ask whether to continue.