writing-reports

name	writing-reports
description	Invoke this skill when writing oci-report.md from an executed OCI analysis. Keywords: - oci-report.md, actor-critic report - results.json, analysis spec, analysis plan - diagnostics: covariate balance, overlap, placebo outcome - SMD, P1 confounders, propensity scores - ATE, ATT, ATO estimands - decision-grade results, diagnostic table

• Review only the analysis plan, spec, and results.json. Do not use ground truth when reviewing evals.
• Keep reports short.

Interpreting the plan

• Plan rules scoped to a specific iteration (e.g. "for the first iteration", "for iter_01") bind only that iteration. They are starting conditions for the actor-critic loop, not invariants.
• When reviewing iter_NN with NN > 1, do not flag deviations from first-iteration defaults as compliance issues. Subsequent iterations are graded against (a) results-vs-spec consistency, (b) the diagnostic rules below, and (c) iteration-agnostic plan rules only.
• Iteration-agnostic plan rules (no iteration-scoping phrase) bind every iteration.
• Plan instructions about how to revise on later iterations (e.g. "if diagnostics fail for the ATO, rerun with a higher ATO_THRESHOLD") describe legitimate revisions — do not flag them as deviations.

Fail conditions

• The parameterization in results.json does not match the spec.
• results.json includes no estimands.
• An estimand is missing its estimate, standard error, or 95% confidence interval.

Diagnostics

• Covariate balance: max standardized mean difference (SMD) of P1 confounders must be < 0.2. Otherwise fail.
• Overlap: warn if more than 10% of observations have propensity scores outside (0.1, 0.9).
• Placebo outcome: warn if the treatment effect on the placebo is significant (p < 0.05).

Report structure

• Executive summary: treatment, outcome, dataset, P1 confounders, estimand(s), estimate(s), confidence interval(s).
• Diagnostic table and whether the results are satisfactory.
• Next steps: remedies for failed diagnostics and warnings, unobserved confounders, confirmatory experiments.

Diagnostic table columns

• Estimand: ATE, ATT, or ATO (diagnostics are per-estimand — one row per estimand × diagnostic).
• Diagnostic: Covariate Balance, Overlap, Placebo Outcome.
• Target Result: Max P1 SMD < 0.2, < 10% extreme propensities, no significant effect.
• Actual Result.
• Grade: ✅ Pass, ⛔ Fail, ⚠️ Warning. ⛔ is reserved exclusively for Max P1 SMD > 0.2 (covariate balance) — it is the only blocking failure. Overlap and placebo can only be ✅ or ⚠️ — never ⛔.

Satisfaction (three tiers)

• Decide one of three labels for the overall analysis and report it in the executive summary:

  • fully_satisfactory — every diagnostic is ✅. Results are decision-grade as-is.
  • satisfactory_with_caveats — no ⛔, but at least one ⚠️ (overlap and/or placebo). Results are usable but the caveats must be called out, and remedies should still be suggested.
  • not_satisfactory — at least one ⛔ (covariate balance failure). Results are blocked from decision use until the balance failure is remedied.

• The covariate-balance check is the only blocking failure. Overlap and placebo warnings degrade results to "with caveats" but never block.

• If any diagnostic fails or warns, invoke the suggesting-remedies skill.