fix(did): harden /did-event-study from Card-Krueger validation (real bug found by running it)

Validated against Pedro's DiD_book Card-Krueger to his 1e-6 standard:
- PRINCIPLE PASSES: DRDID reproduces his canonical 2x2 DiD (2.913982357…) to ~1e-14.
- REAL BUG: the skill prescribed DRDID(panel=TRUE, idname=id), which ERRORS on Card-Krueger — an unbalanced panel (409 stores, 389 in both waves) with 2 duplicate (id,wave) rows.

Fixes:
- Phase 3: pre-flight idname-unique-by-period + balance check; full-sample 2x2 via panel=FALSE + row-unique id (matches feols ~1e-10); balancing → panel=TRUE flagged as a DIFFERENT estimand (2.914 full-sample vs 2.972 balanced — recorded as a named alternative, the EXPLAINED pattern).
- did-conventions: idname-unique-by-period + check-balance-before-panel-mode now HARD.
- quality_reports/did_validation_card_krueger.md: the verification record.

Not yet validated: staggered att_gt path + HonestDiD/didFF sensitivity (packages not installed).

Author: pedrohcgs

.claude/rules/did-conventions.md

@@ -20,7 +20,7 @@ The opinionated defaults here reflect **Pedro Sant'Anna's sign-off** (2026-06-09
 ## Data & coding — HARD
 - Data MUST be **LONG**: one row per unit-period.
 - `gname` (group) = the **first period a unit is treated**; **never-treated coded EXACTLY `0`**.
-- `idname` must be **time-invariant and numeric**.
+- `idname` must be **time-invariant and numeric**, and **unique within each period**. **Check panel balance before any `panel = TRUE` estimation** — unbalanced or duplicate-`(id,period)` data errors in `DRDID`/`did` or silently changes the estimand (balancing drops attriters → a different target). For the full-sample textbook 2×2, use `panel = FALSE` with a row-unique id.
 - These estimators are **staggered-adoption / absorbing only** — once treated, always treated. No reversal.
 - `ATT(g,t)` is identified only for `t ≥ g`; `t < g` estimates are **pseudo-ATTs for pre-testing only** (valid only under no-anticipation).
 

.claude/skills/did-event-study/SKILL.md

@@ -44,8 +44,17 @@ Follow the decision logic in §Estimator selection. Output: which estimator, `es
 
 ### Phase 3 — Estimation (drive the package; do not reimplement)
 - **2×2 (one pre / one post):**
-  `DRDID::drdid(yname, tname, idname, dname, xformla = ~covs, data, panel = TRUE, estMethod = "imp")` → `summary()`.
+  ```r
+  DRDID::drdid(yname, tname, idname, dname, xformla = ~covs, data, panel = TRUE, estMethod = "imp")
+  ```
   IPW-only: `DRDID::ipwdid(..., normalized = TRUE)`; OR-only: `DRDID::ordid(...)`.
+  - **Pre-flight (learned from validating Card–Krueger):** `panel = TRUE` requires `idname` **unique within each period** AND a **balanced** panel. Real datasets often aren't — check first:
+    ```r
+    stopifnot(nrow(dplyr::count(data, .data[[idname]], .data[[tname]]) |> dplyr::filter(n > 1)) == 0)  # idname unique by period
+    balanced <- all(table(data[[idname]]) == length(unique(data[[tname]])))
+    ```
+  - **If unbalanced** (the common case): either (a) reproduce the **full-sample textbook 2×2** with `panel = FALSE` and a **row-unique id** (`data$rowid <- seq_len(nrow(data))`; this equals `feols(y ~ d*post)` to ~1e-10 — but RC SEs treat the waves as independent, so for a true panel report the clustered/panel SE separately); or (b) **balance** the panel (`keep ids present in all periods`) and use `panel = TRUE` — but this is a **different estimand** (the balanced subpopulation), so record it as a named alternative (`EXPLAINED`), e.g. "full-sample 2×2 = 2.914; balanced-panel DR = 2.972 (19 attriting stores dropped)."
+  - DR with **no covariates reduces to the simple 2×2** — DRDID earns its keep once `xformla` adds covariates.
 - **Staggered / multi-period (G×T or 2×T):**
   ```r
   out <- did::att_gt(

quality_reports/did_validation_card_krueger.md

@@ -0,0 +1,31 @@
+# `/did-event-study` validation — Card & Krueger (1994)
+
+**Date:** 2026-06-09 · **Model:** Opus 4.8 · **Standard:** `DiD_book` 1e-6 tolerance
+**Source of truth:** Pedro Sant'Anna's `DiD_book/Card_Krueger_American_Economic_Review_1994` (his code + recorded outputs).
+
+## Result: PASS (principle) + 1 real bug found & fixed (prescription)
+
+| Check | Value | vs target | Status |
+|---|---|---|---|
+| Reproduce his canonical 2×2 DiD (`feols(fte ~ treated*post)`) | `2.913982357430426` | his `…376` | **1e-14** ✅ |
+| Skill's estimator `DRDID::drdid` reproduces it (fixed: RC + row-id) | `2.913982357430…` | his 2×2 | **2.7e-14** ✅ |
+| Skill's *original* prescription `DRDID(panel=TRUE, idname=id)` | **ERROR** | — | ✗ bug |
+
+## The bug (why this validation mattered)
+Card–Krueger is an **unbalanced** panel (409 stores; only 389 in both waves) with **2 duplicate `(id,wave)` rows**. The skill prescribed `DRDID::drdid(panel = TRUE)` with the panel id, which **errors** ("idname must be unique by tname") on exactly this common real-world shape.
+
+**Fixes applied:**
+- Skill Phase 3: a pre-flight balance/uniqueness check; full-sample 2×2 via `panel = FALSE` + a **row-unique id** (matches `feols` to ~1e-10); balancing → `panel = TRUE` is flagged as a **different estimand**.
+- `did-conventions` rule: idname-unique-by-period + check-balance-before-panel-mode is now HARD.
+
+## Estimand note (the `EXPLAINED` pattern, live)
+- Full-sample textbook 2×2 (his target): **ATT = 2.914**
+- Balanced-panel DR (389 stores, 19 attriters dropped): **ATT = 2.972**
+
+Both are defensible — they answer different questions. The skill now records this as a named alternative rather than presenting one number as "the" answer.
+
+## Caveat
+SE comparison is not 1e-6: `DRDID` RC SE (1.73) treats waves as independent; `feols` clustered SE (1.29) uses the panel. For a true panel, report the clustered/panel SE. Point-estimate equivalence is the validation test.
+
+## Not yet validated
+`HonestDiD`/`didFF`/`contdid` are not installed → the staggered `att_gt` path + sensitivity suite (HonestDiD breakdown, `didFF`) and continuous-treatment path remain to be validated on a genuinely staggered `DiD_book` application.