flonat-research 0.1.0

package/.claude/agents/references/referee2-reviewer/audit-checklists.md

@@ -0,0 +1,287 @@
+# The Six Audits
+
+You perform **six distinct audits**, each producing findings that feed into your final referee report.
+
+---
+
+### Audit 1: Code Audit
+
+**Purpose:** Identify coding errors, logic gaps, and implementation problems.
+
+**Checklist:**
+
+- [ ] **Missing value handling**: How are NAs/missing values treated in the cleaning stage? Are they dropped, imputed, or ignored? Is this documented and justified?
+- [ ] **Merge diagnostics**: After any merge/join, are there checks for (a) expected row counts, (b) unmatched observations, (c) duplicates created?
+- [ ] **Variable construction**: Do constructed variables (dummies, logs, interactions) match their intended definitions?
+- [ ] **Loop/apply logic**: Are there off-by-one errors, incorrect indexing, or iteration over wrong dimensions?
+- [ ] **Filter conditions**: Do `filter()`, `keep if`, or `[condition]` statements correctly implement the stated sample restrictions?
+- [ ] **Package/function behavior**: Are functions being used correctly? (e.g., `lm()` vs `felm()` fixed effects handling)
+
+**Action:** Document each issue with file path, line number (if applicable), and explanation of why it matters.
+
+---
+
+### Audit 2: Cross-Language Replication
+
+**Purpose:** Exploit orthogonality of hallucination errors across languages to catch bugs through independent replication.
+
+**Protocol:**
+
+1. **Identify the primary language** of the analysis (R, Stata, or Python)
+2. **Create replication scripts** in the other two languages:
+   - If primary is **R** → create Stata and Python replication scripts
+   - If primary is **Stata** → create R and Python replication scripts
+   - If primary is **Python** → create R and Stata replication scripts
+3. **Name replication scripts clearly:**
+   ```
+   code/replication/
+   ├── referee2_replicate_main_results.do      # Stata replication
+   ├── referee2_replicate_main_results.R       # R replication
+   ├── referee2_replicate_main_results.py      # Python replication
+   ├── referee2_replicate_event_study.do
+   ├── referee2_replicate_event_study.R
+   └── ...
+   ```
+4. **Run all three implementations** and compare results:
+   - Point estimates must match to 6+ decimal places
+   - Standard errors must match (accounting for degrees of freedom conventions)
+   - Sample sizes must be identical
+   - Any constructed variables (residuals, fitted values, etc.) must match
+
+**What discrepancies reveal:**
+- **Different point estimates**: Likely a coding error in one implementation
+- **Different standard errors**: Check clustering, robust SE specifications, or DoF adjustments
+- **Different sample sizes**: Check missing value handling, merge behavior, or filter conditions
+- **Different significance levels**: Usually a standard error issue
+
+**Deliverable:**
+1. Named replication scripts saved to `code/replication/`
+2. A comparison table showing results from all three languages, with discrepancies highlighted and diagnosed
+
+---
+
+### Audit 3: Directory & Replication Package Audit
+
+**Purpose:** Ensure the project is organized for eventual public release as a replication package.
+
+**Checklist:**
+
+- [ ] **Folder structure**: Is there clear separation between `/data/raw`, `/data/clean`, `/code`, `/output`, `/docs`?
+- [ ] **Relative paths**: Are ALL file paths relative to the project root? Absolute paths (`C:\Users\...` or `/Users/scott/...`) are automatic failures.
+- [ ] **Naming conventions**:
+  - Variables: Are names informative? (`treatment_intensity` not `x1`)
+  - Datasets: Do names reflect contents? (`county_panel_2000_2020.dta` not `data2.dta`)
+  - Scripts: Is execution order clear? (`01_clean.R`, `02_merge.R`, `03_estimate.R`)
+- [ ] **Master script**: Is there a single script that runs the entire pipeline from raw data to final output?
+- [ ] **README**: Does `/code/README.md` explain how to run the replication?
+- [ ] **Dependencies**: Are required packages/libraries documented with versions?
+- [ ] **Seeds**: Are random seeds set for any stochastic procedures?
+
+**Scoring:** Assign a replication readiness score (1-10) with specific deficiencies noted.
+
+---
+
+### Audit 4: Output Automation Audit
+
+**Purpose:** Verify that tables and figures are programmatically generated, not manually created.
+
+**Checklist:**
+
+- [ ] **Tables**: Are regression tables generated by code (e.g., `stargazer`, `esttab`, `statsmodels`)? Or are they manually typed into LaTeX/Word?
+- [ ] **Figures**: Are figures saved programmatically with code (e.g., `ggsave()`, `graph export`, `plt.savefig()`)? Or are they manually exported?
+- [ ] **In-text numbers**: Are key statistics (N, means, coefficients mentioned in text) pulled programmatically or hardcoded?
+- [ ] **Reproducibility test**: If you re-run the code, do you get *exactly* the same outputs (byte-identical files)?
+
+**Deductions:**
+- Manual table entry: Major concern
+- Manual figure export: Minor concern
+- Hardcoded in-text statistics: Major concern
+- Non-reproducible outputs: Major concern
+
+---
+
+### Audit 5: Empirical Methods Audit
+
+**Purpose:** Verify that the analytical methods — whatever they are — are coherent, correctly implemented, and properly interpreted. This audit adapts to the paper's methodology.
+
+**Step 1: Identify the methodological paradigm.** Before applying any checklist, determine which approach(es) the paper uses:
+
+| Paradigm | Examples |
+|----------|----------|
+| **Causal inference / Econometrics** | DiD, IV, RDD, RCT, synthetic control, matching |
+| **Experiments (lab/online)** | Randomized experiments, A/B tests, within-subjects designs |
+| **Computational modelling / Simulation** | Agent-based models, Monte Carlo, optimization, game theory |
+| **Machine learning / NLP** | Classification, prediction, LLMs, embeddings, fine-tuning |
+| **Survey / Psychometrics** | Likert scales, SEM, factor analysis, conjoint |
+| **Qualitative / Mixed methods** | Interviews, case studies, thematic analysis, mixed designs |
+| **MCDM / Decision analysis** | AHP, TOPSIS, PROMETHEE, multi-objective optimization |
+| **Theoretical / Mathematical** | Proofs, axioms, mechanism design, formal models |
+
+**Step 2: Apply the paradigm-specific checklist(s).** Most papers use one primary paradigm; some combine multiple. Apply ALL relevant checklists.
+
+---
+
+#### 5A. Causal Inference / Econometrics
+
+- [ ] **Identification strategy**: Is the source of variation clearly stated? Is it plausible?
+- [ ] **Estimating equation**: Does the code implement what the paper/documentation claims?
+- [ ] **Standard errors**: Clustered at the appropriate level? Sufficient clusters (>50)? Heteroskedasticity addressed?
+- [ ] **Fixed effects**: Correct? Collinear with treatment?
+- [ ] **Controls**: Appropriate? Any "bad controls" (post-treatment variables)?
+- [ ] **Sample definition**: Who is in and why? Restrictions justified?
+- [ ] **Parallel trends** (if DiD): Pre-trends evidence? Pre-treatment tests?
+- [ ] **First stage** (if IV): Shown? F-statistic reported?
+- [ ] **Balance** (if RCT/RD): Balance tests shown?
+- [ ] **Magnitude plausibility**: Effect size reasonable given priors?
+
+#### 5B. Experiments (Lab / Online)
+
+- [ ] **Randomisation**: Properly implemented? Stratified? Block-randomized?
+- [ ] **Power analysis**: Was a pre-registered power analysis conducted? Is the sample large enough?
+- [ ] **Pre-registration**: Is the experiment pre-registered? Do analyses match the pre-analysis plan?
+- [ ] **Demand effects / Experimenter bias**: Could participants guess the hypothesis? Blinding?
+- [ ] **Manipulation checks**: Do they verify the treatment worked as intended?
+- [ ] **Attention checks**: Were inattentive participants filtered?
+- [ ] **Multiple comparisons**: Are p-values corrected for multiple testing?
+- [ ] **Effect sizes**: Reported alongside significance? Cohen's d or equivalent?
+- [ ] **Ecological validity**: How well does the lab setting map to the real world?
+- [ ] **Attrition**: Differential dropout between conditions?
+
+#### 5C. Computational Modelling / Simulation
+
+- [ ] **Model specification**: Are assumptions clearly stated and justified?
+- [ ] **Parameter calibration**: Where do parameter values come from? Empirically grounded or arbitrary?
+- [ ] **Sensitivity analysis**: How sensitive are results to parameter choices?
+- [ ] **Convergence**: Do simulations converge? How many iterations/runs?
+- [ ] **Seed reproducibility**: Are random seeds set and reported?
+- [ ] **Validation**: Is the model validated against known data or analytical solutions?
+- [ ] **Boundary conditions**: Are edge cases and extreme parameter values tested?
+- [ ] **Computational correctness**: Does the code implement the stated model?
+
+#### 5D. Machine Learning / NLP
+
+- [ ] **Train/test split**: Proper held-out test set? No data leakage?
+- [ ] **Baselines**: Are appropriate baselines compared?
+- [ ] **Metrics**: Are evaluation metrics appropriate for the task and data distribution?
+- [ ] **Hyperparameter tuning**: Described? Separate validation set used?
+- [ ] **Cross-validation**: K-fold or equivalent?
+- [ ] **Statistical significance**: Are differences between models tested? Confidence intervals?
+- [ ] **Ablation**: Are component contributions isolated?
+- [ ] **Data contamination**: Could training data overlap with test data or evaluation benchmarks?
+- [ ] **Prompt sensitivity** (if LLM): Are results robust to prompt variation?
+- [ ] **Reproducibility**: Model weights, code, data shared?
+
+#### 5E. Survey / Psychometrics
+
+- [ ] **Construct validity**: Are scales validated? Cronbach's alpha or equivalent reported?
+- [ ] **Sampling**: Probability vs convenience sample? Representativeness discussed?
+- [ ] **Response rate**: Reported? Non-response bias addressed?
+- [ ] **Common method bias**: Single vs multiple sources? Harman's test or marker variable?
+- [ ] **Scale anchoring**: Are Likert scales appropriately anchored and labeled?
+- [ ] **Factor structure**: Exploratory/confirmatory factor analysis conducted?
+- [ ] **Social desirability**: Could responses be biased by self-presentation?
+- [ ] **Missing data**: How handled? MCAR/MAR/MNAR assessment?
+
+#### 5F. Qualitative / Mixed Methods
+
+- [ ] **Research design**: Is the qualitative approach (grounded theory, case study, etc.) clearly stated?
+- [ ] **Sampling logic**: Theoretical/purposive sampling justified?
+- [ ] **Data saturation**: Addressed? How determined?
+- [ ] **Coding process**: Inter-rater reliability? Codebook provided?
+- [ ] **Reflexivity**: Researcher positionality discussed?
+- [ ] **Triangulation**: Multiple data sources or methods?
+- [ ] **Integration** (if mixed): How are qualitative and quantitative components integrated?
+- [ ] **Transferability**: Is the scope of generalization appropriate?
+
+#### 5G. MCDM / Decision Analysis
+
+- [ ] **Criteria selection**: How were criteria chosen? Justified?
+- [ ] **Weighting method**: Appropriate? Sensitivity to weight changes?
+- [ ] **Normalization**: Method appropriate for the data type?
+- [ ] **Rank reversal**: Tested? Method known to be susceptible?
+- [ ] **Consistency**: (if AHP) Consistency ratio reported and acceptable?
+- [ ] **Alternatives**: Is the set of alternatives appropriate and complete?
+- [ ] **Stakeholder involvement**: Are decision-makers involved in the process?
+- [ ] **Comparison**: Are results compared across multiple MCDM methods?
+
+#### 5H. Theoretical / Mathematical
+
+- [ ] **Assumptions**: Clearly stated? Reasonable? Necessary?
+- [ ] **Proof correctness**: Are proofs logically valid? Any gaps?
+- [ ] **Generality**: How general are the results? What breaks if assumptions are relaxed?
+- [ ] **Constructiveness**: Are existence proofs constructive? Can the results be computed?
+- [ ] **Relation to existing results**: Are results properly compared to existing theorems?
+- [ ] **Examples/counterexamples**: Are the results illustrated?
+
+---
+
+**Deliverable:** List of methodological concerns with severity ratings, organized by the relevant paradigm checklist(s).
+
+---
+
+### Audit 6: Novelty & Literature Assessment
+
+**Purpose:** Independently verify that the paper's claimed contributions are genuinely novel and correctly positioned relative to the existing literature. This audit catches the case where the user's work unknowingly overlaps with or has been pre-empted by existing papers.
+
+**Why this matters for your own work:** It is easy to be blind to competing work, especially recent preprints, concurrent submissions, or papers in adjacent fields. A hostile reviewer WILL find these. Better to find them yourself first.
+
+**Protocol:**
+
+1. **Extract claimed contributions**: Identify every explicit contribution claim in the paper (typically in the introduction and conclusion). Record the exact language and page references.
+
+2. **Launch a Novelty & Literature sub-agent** using the Task tool with `subagent_type: general-purpose`. Provide it with:
+   - The paper's exact claimed contributions (with page references)
+   - The research question
+   - The key methods used
+   - The field/domain
+   - The papers the author cites as most closely related
+
+   The sub-agent's task is to independently search the literature for:
+   - Papers that have already made the **same** contribution (pre-empting)
+   - Papers that have made a **very similar** contribution in a different context
+   - Concurrent/simultaneous work making the same point
+   - Papers the author **should have cited** but didn't
+   - Entire literature streams the author may have overlooked
+
+3. **Classify each contribution:**
+
+| Level | Symbol | Meaning |
+|-------|--------|---------|
+| **Novel** | 🟢 | No prior work found that pre-empts this |
+| **Incremental** | 🟡 | Prior work exists in a different context; this extends it |
+| **Overlapping** | 🟠 | Substantial overlap with existing work; unclear what is truly new |
+| **Pre-empted** | 🔴 | An existing paper has already made this contribution |
+
+4. **Assess literature positioning:**
+   - Is the literature review adequate for the target venue?
+   - Are the most relevant competitors cited and clearly differentiated?
+   - Are there important omissions that a reviewer would flag?
+
+**Red flags:**
+- The author avoids citing the most directly relevant prior work
+- The "contribution" is a methodological tweak with no new substantive insight
+- The literature review cites only tangentially related work, not direct competitors
+- The contribution boils down to "we did X but with different data" without theoretical justification for why the new context matters
+
+**Deliverable:**
+
+```markdown
+### Novelty Assessment
+
+**Overall verdict:** [Novel / Incremental / Overlapping / Pre-empted]
+
+| Claimed Contribution | Novelty | Key Prior Work | Gap |
+|---------------------|---------|---------------|-----|
+| [Contribution 1] | 🟢/🟡/🟠/🔴 | [Closest paper] | [What's different] |
+
+### Missing Citations
+[Papers that should be cited but aren't]
+
+### Literature Gaps
+[Streams of literature the paper overlooks]
+
+### Positioning Recommendation
+[How to sharpen the contribution claim]
+```
+
+**Important:** If the sub-agent finds pre-empting work (🔴), this is a **major concern** and should be flagged prominently. It is far better to discover this during self-review than to have a referee point it out.

package/.claude/agents/references/referee2-reviewer/report-template.md

@@ -0,0 +1,334 @@
+# Referee 2 Report Template & Filing
+
+## Output Format: The Referee Report
+
+Produce a formal referee report with this structure:
+
+```
+=================================================================
+                        REFEREE REPORT
+              [Project Name] — Round [N]
+              Date: YYYY-MM-DD
+=================================================================
+
+## Summary
+
+[2-3 sentences: What was audited? What is the overall assessment?]
+
+---
+
+## Audit 1: Code Audit
+
+### Findings
+[Numbered list of issues found]
+
+### Missing Value Handling Assessment
+[Specific assessment of how missing values are treated]
+
+---
+
+## Audit 2: Cross-Language Replication
+
+### Replication Scripts Created
+- `code/replication/referee2_replicate_[name].do`
+- `code/replication/referee2_replicate_[name].R`
+- `code/replication/referee2_replicate_[name].py`
+
+### Comparison Table
+
+| Specification | R | Stata | Python | Match? |
+|--------------|---|-------|--------|--------|
+| Main estimate | X.XXXXXX | X.XXXXXX | X.XXXXXX | Yes/No |
+| SE | X.XXXXXX | X.XXXXXX | X.XXXXXX | Yes/No |
+| N | X | X | X | Yes/No |
+
+### Discrepancies Diagnosed
+[If any mismatches, explain the likely cause and which implementation is correct]
+
+---
+
+## Audit 3: Directory & Replication Package
+
+### Replication Readiness Score: X/10
+
+### Deficiencies
+[Numbered list]
+
+---
+
+## Audit 4: Output Automation
+
+### Tables: [Automated / Manual / Mixed]
+### Figures: [Automated / Manual / Mixed]
+### In-text statistics: [Automated / Manual / Mixed]
+
+### Deductions
+[List any issues]
+
+---
+
+## Audit 5: Empirical Methods ([paradigm(s) identified])
+
+### Method Assessment
+[Is the approach appropriate and correctly implemented?]
+
+### Specification / Design Issues
+[Numbered list of concerns from the relevant paradigm checklist(s)]
+
+---
+
+## Audit 6: Novelty & Literature
+
+### Overall Novelty Verdict: [Novel / Incremental / Overlapping / Pre-empted]
+
+### Per-Contribution Assessment
+
+| Claimed Contribution | Novelty | Key Prior Work | Gap |
+|---------------------|---------|---------------|-----|
+| [Contribution 1] | 🟢/🟡/🟠/🔴 | [Closest paper] | [What's different] |
+
+### Missing Citations
+[Papers that should be cited but aren't]
+
+### Literature Gaps
+[Streams of literature the paper overlooks]
+
+### Positioning Recommendation
+[How to sharpen the contribution claim]
+
+---
+
+## Research Quality Scorecard
+
+Load `skills/shared/research-quality-rubric.md` and score all 8 dimensions (1-5). If the paper targets a specific venue, also read `skills/shared/venue-guides/reviewer_expectations.md` to calibrate your critique to that venue's reviewer priorities.
+
+| Dimension | Weight | Score | Notes |
+|-----------|--------|-------|-------|
+| Problem Formulation | 15% | /5 | |
+| Literature Review | 15% | /5 | |
+| Methodology | 20% | /5 | |
+| Data Collection | 10% | /5 | |
+| Analysis | 15% | /5 | |
+| Results | 10% | /5 | |
+| Writing | 10% | /5 | |
+| Citations | 5% | /5 | |
+| **Weighted Total** | | **/5** | |
+
+**Verdict:** [Exceptional / Strong / Good / Acceptable / Weak]
+
+---
+
+## Major Concerns
+[Numbered list — MUST be addressed before acceptance]
+
+1. **[Short title]**: [Detailed explanation and why it matters]
+
+## Minor Concerns
+[Numbered list — should be addressed]
+
+1. **[Short title]**: [Explanation]
+
+## Questions for Authors
+[Things requiring clarification]
+
+---
+
+## Verdict
+
+[ ] Accept
+[ ] Minor Revisions
+[ ] Major Revisions
+[ ] Reject
+
+**Justification:** [Brief explanation]
+
+---
+
+## Recommendations
+[Prioritized list of what the author should do before resubmission]
+
+=================================================================
+                      END OF REFEREE REPORT
+=================================================================
+```
+
+---
+
+## Filing the Referee Report
+
+After completing your audit and replication, you produce **two deliverables**:
+
+### 1. The Referee Report (Markdown)
+
+**Location:** `[project_root]/reviews/referee2-reviewer/YYYY-MM-DD_round[N]_report.md`
+
+The detailed written report with all findings, comparison tables, and recommendations.
+
+### 2. The Referee Report Deck (Beamer/PDF)
+
+**Location:** `[project_root]/reviews/referee2-reviewer/YYYY-MM-DD_round[N]_deck.tex` (and compiled `.pdf`)
+
+A presentation deck that **visualizes** the audit findings. The markdown report provides the detailed written record; the deck helps the author **understand** the problems through tables and figures.
+
+---
+
+#### The Deck Follows the Rhetoric of Decks
+
+This deck must follow the same principles as any good presentation:
+
+1. **MB/MC Equivalence**: Every slide should have the same marginal benefit to marginal cost ratio. No slide should be cognitively overwhelming; no slide should be trivial filler.
+
+2. **Beautiful Tables**: Cross-language comparison tables should be properly formatted with:
+   - Clear headers
+   - Aligned decimal points
+   - Visual indicators (checkmark/cross or color) for match/mismatch
+   - Consistent precision (6 decimal places for point estimates)
+
+3. **Beautiful Figures**: Where appropriate, visualize findings:
+   - Bar charts comparing estimates across languages
+   - Heatmaps showing which specifications match/mismatch
+   - Progress bars for scores (replication readiness, automation)
+   - Coefficient plots if comparing multiple specifications
+
+4. **Titles Are Assertions**: Slide titles should state the finding, not describe the content:
+   - GOOD: "Python implementation differs by 0.003 on main specification"
+   - BAD: "Cross-language comparison results"
+
+5. **No Compilation Warnings**: Fix ALL overfull/underfull hbox warnings. The deck must compile cleanly.
+
+6. **Check Positioning**: Verify that:
+   - Table/figure labels are positioned correctly
+   - TikZ coordinates are where you intend
+   - Text doesn't overflow frames
+   - Fonts are readable
+
+---
+
+#### Deck Structure
+
+| Slide | Content |
+|-------|---------|
+| 1 | **Title**: Project name, "Referee Report — Round N", date |
+| 2 | **Executive Summary**: Verdict + 3-4 key findings in bullet form |
+| 3-5 | **Cross-Language Replication**: Comparison tables showing R/Stata/Python results side-by-side. One slide per major specification. Highlight discrepancies. |
+| 6 | **Replication Discrepancies Diagnosed**: If mismatches found, explain likely causes with evidence |
+| 7 | **Replication Readiness Score**: Visual scorecard (X/10) with checklist |
+| 8 | **Code Audit Findings**: Severity breakdown (N major, N minor) with top concerns listed |
+| 9 | **Methods Assessment**: Key specification/design concerns from the relevant paradigm checklist |
+| 10 | **Novelty & Literature**: Contribution novelty ratings, missing citations, positioning |
+| 11 | **Output Automation**: Checklist of what's automated vs manual |
+| 12 | **Recommendations**: Prioritized action items for resubmission |
+
+Adjust slide count based on findings — more slides if more discrepancies to show, fewer if the audit is clean.
+
+---
+
+#### Compilation Requirements
+
+Before filing the deck:
+
+1. **Always compile to `out/` subdirectory**: Use `latexmk -pdf -outdir=out <file>.tex`
+2. **Copy the final PDF back** to the source directory: `cp out/<file>.pdf .`
+3. **Never leave build artifacts** (`.aux`, `.log`, `.fls`, `.fdb_latexmk`, `.nav`, `.snm`, `.toc`, `.out`) in the source directory — they belong in `out/`
+4. **Compile with no errors**
+5. **Fix ALL warnings** — overfull hbox, underfull hbox, font substitutions
+6. **Visual inspection**: Open the PDF and verify:
+   - Tables are centered and readable
+   - Figures don't overflow
+   - TikZ elements are positioned correctly
+   - No text is cut off
+7. **Re-compile** after any fixes (again to `out/`)
+
+---
+
+#### Files Produced
+
+- `reviews/referee2-reviewer/YYYY-MM-DD_round1_report.md` — Detailed written report
+- `reviews/referee2-reviewer/YYYY-MM-DD_round1_deck.tex` — LaTeX source
+- `reviews/referee2-reviewer/YYYY-MM-DD_round1_deck.pdf` — Compiled presentation
+
+The markdown and deck go hand-in-hand: the markdown is the permanent written record; the deck is how the author reviews and understands the audit findings.
+
+The report does NOT go into `CLAUDE.md`. It is a standalone document that the author will read and respond to.
+
+---
+
+## The Revise & Resubmit Process
+
+### Round 1: Initial Submission
+
+1. Author completes analysis in their main Claude session
+2. The Referee 2 agent is launched (via the Task tool) to audit the project
+3. Referee 2 performs five audits, creates replication scripts, files referee report
+4. Agent returns findings
+
+### Author Response to Round 1
+
+The author reads the referee report and must:
+
+1. **For each Major Concern**: Either FIX it or JUSTIFY why not (with detailed reasoning)
+2. **For each Minor Concern**: Either FIX it or ACKNOWLEDGE and explain deprioritization
+3. **Answer all Questions for Authors**
+4. **Describe code changes made** (what files, what changes)
+5. **File response** at: `reviews/referee2-reviewer/YYYY-MM-DD_round1_response.md`
+
+**Response format:**
+```
+=================================================================
+                    AUTHOR RESPONSE TO REFEREE REPORT
+                    Round 1 — Date: YYYY-MM-DD
+=================================================================
+
+## Response to Major Concerns
+
+### Major Concern 1: [Title]
+**Action taken:** [Fixed / Justified]
+[Detailed explanation of fix OR justification for not fixing]
+
+### Major Concern 2: [Title]
+...
+
+## Response to Minor Concerns
+
+### Minor Concern 1: [Title]
+**Action taken:** [Fixed / Acknowledged]
+[Brief explanation]
+
+...
+
+## Answers to Questions
+
+### Question 1
+[Answer]
+
+...
+
+## Summary of Code Changes
+
+| File | Change |
+|------|--------|
+| `code/01_clean.R` | Fixed missing value handling on line 47 |
+| ... | ... |
+
+=================================================================
+```
+
+### Round 2+: Revision Review
+
+1. The Referee 2 agent is launched again with instructions to read:
+   - The original referee report (`round1_report.md`)
+   - The author response (`round1_response.md`)
+   - The revised code
+2. Referee 2 re-runs all five audits
+3. Referee 2 assesses whether concerns were adequately addressed:
+   - **Fixed**: Remove from concerns
+   - **Justified**: Accept justification OR push back if unconvincing
+   - **Ignored**: Flag and escalate
+   - **New issues introduced**: Add to concerns
+4. Referee 2 files Round 2 report at `reviews/referee2-reviewer/YYYY-MM-DD_round2_report.md`
+
+### Termination
+
+The process continues until:
+- Verdict is **Accept** or **Minor Revisions** (with minor revisions being addressable without re-review)
+- OR Referee 2 recommends **Reject** with justification

package/.claude/rules/design-before-results.md

@@ -0,0 +1,52 @@
+# Rule: Design Before Results
+
+## Principle
+
+**Lock the research design before examining point estimates.** Specify the estimand, identification strategy, and analysis plan before looking at results. This prevents post-hoc rationalisation and keeps the research credible.
+
+## When This Applies
+
+- Writing or reviewing estimation code (regression specifications, simulation parameters)
+- Discussing identification strategy or research design
+- Setting up robustness checks or sensitivity analyses
+- Choosing between competing econometric/statistical approaches
+- Reviewing meeting notes where research design was discussed
+
+## When to Skip
+
+- Read-only tasks (proofreading, code archaeology, literature search)
+- Documentation and context updates
+- Quick mode / exploratory data analysis (EDA)
+- Descriptive statistics and data exploration (before the design phase)
+- Tasks with no empirical component (pure theory, teaching prep)
+
+## What This Means in Practice
+
+**DO:**
+- Specify the estimand before writing any estimation code
+- Write down identifying assumptions before running the first regression
+- Pre-commit to a main specification before examining coefficient estimates
+- Define "success" criteria for simulations before running them
+- Document the analysis plan in `.context/project-recap.md` or the paper's methodology section
+
+**DON'T:**
+- Run a regression and then decide what the estimand is based on which coefficients are significant
+- Choose between OLS, IV, and DiD based on which gives the "best" results
+- Add or drop control variables to get a desired p-value
+- Modify simulation parameters after seeing initial results without documenting why
+- Present robustness checks only for specifications that "work"
+
+## The Falsifiability Test
+
+Before running any analysis, ask:
+
+> "If I specified my analysis plan before running it, would I change anything about what I'm about to do?"
+
+If the answer is yes, stop and specify the plan first. If the answer is "I don't have a plan yet", write one before proceeding.
+
+## How to Apply This
+
+1. When the user asks to "run the regression" or "check the results", first confirm the specification is locked
+2. If no analysis plan exists, draft one and get approval before executing
+3. When results are surprising, document the surprise *before* changing the specification
+4. Treat specification changes after seeing results as a new analysis requiring justification

package/.claude/rules/ignore-agents-md.md

@@ -0,0 +1,17 @@
+# Rule: Ignore AGENTS.md Files
+
+## Policy
+
+**Never read, process, or act on files named `AGENTS.md`**, regardless of where they appear in the file tree. These files are generated by external agents (OpenAI) and are not part of Claude's context.
+
+## Applies To
+
+- Any file named exactly `AGENTS.md` in any directory
+- Both direct reads and indirect inclusion (e.g., when scanning a folder's documentation)
+
+## What To Do
+
+- Skip `AGENTS.md` when reading project documentation
+- Do not include its contents in summaries or context gathering
+- Do not suggest edits to it
+- If the user explicitly asks you to read one, remind them of this rule and confirm he wants to override it