` / `theory.md:` / `literature.md:`. New work = AN page; touching old work = the doc that holds the claim. - **Secondary targets** (optional): any other docs the run will touch per the propagation checklist (briefs, stylized-facts, outline). - **Required inputs**: existing build artifacts or pipeline outputs. - **Effort**: single descriptive cut / multi-script empirical battery / new data linkage. - **Risk flag** if any: "needs raw data we don't have", "duplicates existing `build/table/X`", "depends on a parser fix not yet shipped". The primary target is what drives step 5's `--update ` invocation. If you can't name a target, that's a signal to talk through what the run is for *before* writing the script — usually it means the candidate is too vague or genuinely exploratory (in which case `(new entry)`). Ranking criteria, in order: 1. Closes a load-bearing gap in the active paper outline. 2. Tests a hypothesis that's been pending for >2 sessions. 3. Cheaply confirms or refutes a finding currently tagged 🟡 or 🔴. 4. Resolves an explicit todo from the most recent handoff. 5. Picks up a high-value lead from a prior `/next` iteration (the `## Leads from …` blocks in `todo.md`). **Pursuit gate (estimation candidates).** Before ranking an estimation candidate highly, ask whether a *null* would be as informative as a significant result: will the CI be tight enough to rule out the effect sizes we'd care about *whichever way it lands*? If yes, it's worth running regardless of outcome. If only a significant result would be interesting and power is thin, that's a significance-bias trap — the "hit" would be a winner's-curse artifact and the "null" uninformative; flag it (`Risk: underpowered — only a "hit" would be interesting`) and either propose powering it up or deprioritize it. Do not rank a candidate highly *because* it is likely to return significance. This does not apply to descriptive/measurement cuts, and a genuinely exploratory candidate can still be proposed if labelled `(exploratory)`. See `research-kit/meta/ai_research_workflow.md`, "Significance is not the win condition." Candidate format example (new analysis): ``` Candidate 2: AN-019 — within-mayor 2nd-term irregularity contrast Description: refit the lame-duck regression on the subset of mayors whose 1st and 2nd consecutive terms both fall in the panel, with mayor FE to absorb selection-into-reelection. Primary target: analyses/an-019 (new AN page) Secondary: hypotheses.md:H:lame-duck (status block updated to reference AN-019 if confirmed); findings.md (new entry citing AN-019 if the result holds) Required inputs: build/clean/court_party.parquet (mayor identifiers), build/analysis/doe_irregularity_panel.parquet Effort: medium — new script + sample restriction. Risk: power may be thin given the within-mayor subset. ``` Candidate format example (re-use of existing script): ``` Candidate 4: H6 vara-FE refit with post-fix sample Description: re-run AN-031's fixed-effect spec on the corrected sample after the parser fix; check that the productivity axis estimate survives. Primary target: hypotheses.md:H6 (status block — AN-031 re-run, not new AN) Secondary: findings.md:vara-productivity-axis (refresh magnitude) Required inputs: build/table/h6_vara_fe.csv (re-run target) Effort: low — sample swap + refit. Risk: none. ``` **Then stop.** Wait for the researcher to pick one — or to specify something different. Do not write any script. ## Step 2 — Restate In one short paragraph, confirm: - The **question** the analysis answers. - The **primary target** (carried over from step 1, or asked here in specify mode): the single doc entry that will receive a `--update` in step 5. Format: `hypotheses.md:H<#>` / `findings.md:` / `institutions.md:

` / `theory.md:` / `literature.md:` / `(new entry)`. - The **unit of observation**, sample, and time window. - The **outcome variable(s)** and the cut(s). - The **output**: which `build/table/X.{csv,parquet,tex}` and/or `build/figure/X.{pdf,png}`. Follow the project's existing layout. - The **secondary targets** (briefs, outline section, stylized-facts) the run will also touch. If anything is unclear — sample definition, denominator, primary target — **ask before proceeding**. Cheaper than redoing. In **specify mode** (`/next ` with no proposal step), if the researcher's description didn't name a primary target, the restate must derive one or ask. A run with no nameable target is rare and usually a sign the work is too unfocused. ### Scaffold the AN page now (before step 3) When the primary target is a new AN page, write the page *now* — at the end of step 2, before writing the script. This makes the AN id stable for the script's IAT header and lets step 4 update the same file rather than scrambling to create it post-hoc. Numbering: `ls $PROJ/docs/analyses/an-*.md`, parse the numeric prefix, take the max and add 1, zero-pad to 3. Show the proposed id once in the restate output ("Drafting AN-019 at `docs/analyses/an-019-.md`"). File contents at step 2: ```yaml --- id: an-NNN hypothesis: # H slug if the run tests an existing H; null otherwise type: status: pending # use the project schema's "queued" / "draft" if it overrides status_date: confidence: pending created: script: source//.py target: build//. design: sample: specification: notes: # project-specific keys from docs/reference/analysis-schema.yaml --- # AN-NNN: ## Question ## Design ## Results *Pending — emits ``.* ## Interpretation *Pending.* ## Follow-ups *Pending — see Step 4 of /next for the puzzles / extensions / blind-spots taxonomy.* ``` Read `$PROJ/docs/reference/analysis-schema.yaml` first if it exists and conform the frontmatter to it (status vocabulary, design keys). If the schema is absent, use the contract default above and flag the absence once in the end-of-iteration report. The script written in step 3 should include `# AN-NNN` in its IAT header so the source-to-AN back-link is greppable. ## Step 3 — Write the script Location and naming (per workspace.md "Source and build naming convention"): - **Analysis backing an AN page (default)** → `source/analysis/an-NNN-.py` → outputs at `build/table/.{csv,tex}` and/or `build/figure/.{pdf,png}` per file extension. The AN-page is the unit; the script location mirrors `docs/analyses/`. Multi-AN scripts that back several AN pages (e.g. a regression module shared across AN-001/002/003) use a descriptive name without the AN prefix and each AN page's `script:` field points at the same path. - Paper-table builder → `source/table/X.py` → `build/table/X.{csv,tex}` - Paper-figure builder → `source/figure/X.py` → `build/figure/X.{pdf,png}` - Legacy projects: `source/table/X.py` is also accepted for analysis scripts on projects that historically organized analyses there. New default for analysis is `source/analysis/`; mixing the two within a project is fine as long as each AN page's `script:` field is accurate. - **Multi-output scripts** (more than one output of the same suffix) must write into a folder named after the script: `source/figure/X.py` → `build/figure/X/.png`, not sibling files like `build/figure/X_a.png` + `build/figure/X_b.png`. The script-to-output mapping must be recoverable from the path alone. - Underscore-prefix (`source/analysis/_foo_check.py`) for one-shot exploratory checks kept for reproducibility but not part of the pipeline. Use sparingly — most scripts should not need it. **Table and figure.** When the result is quantitative *and* has a natural visual form, produce both: a machine-readable table (`.json` / `.csv` / `.parquet` — what the build, paper macros, and review read) and a figure (`.png` / `.pdf` — what a human scans). Emit both from the analysis script, or from the analysis script plus a sibling figure script, sharing the script base name and following the project's `source/` layout. The AN page's `## Results` then embeds the figure and reports the table's headline numbers (step 4). A pure-count, linkage, or paper-table analysis with no meaningful visual is exempt — don't manufacture a figure. Defer to any project-specific output convention in the project's `CLAUDE.md`. IAT header per `research-kit/rules/inline_audit_trail.md`: - `INTENT` — the question. - `REASONING` — why this specification (sample choice, variable cuts). - `ASSUMES` — required inputs, conventions the script depends on. Code style (per workspace.md): - Functions over procedural blocks. - `pathlib.Path` over string paths. - Parquet over CSV for intermediate data. - Explicit `validate=` on every `.merge()`. - `errors='coerce'` on numeric conversions of messy input. - `diarios` for shared parsing — do not duplicate. After writing, invoke `/iat