flonat-research 0.1.0

package/skills/shared/concept-validation-gate.md

@@ -0,0 +1,161 @@
+# Concept Validation Gate
+
+> Shared reference for writing and literature skills. Validates that a research concept is sufficiently developed before investing time in synthesis, drafting, or review. Adapted from CommScribe (Xu 2026).
+
+## Principle
+
+**A weak concept produces a weak paper.** Validate the concept before proceeding to literature synthesis or drafting. This prevents wasted effort on poorly defined research questions, missing theoretical framing, or generic AI-sounding proposals.
+
+---
+
+## Validation Requirements
+
+| Requirement | Minimum | Why It Matters |
+|-------------|---------|----------------|
+| **Word count** | 300 words | Demonstrates sufficient engagement with the idea |
+| **Citations** | 3 references | Shows grounded knowledge, not speculation |
+| **Research question** | Explicit, specific | Defines scope and testable contribution |
+| **Theoretical framing** | Named framework or lens | Provides analytical structure |
+| **Original voice** | Detected (not generic AI) | Ensures authentic intellectual engagement |
+
+---
+
+## What a Concept Plan Must Address
+
+### 1. Research Question
+
+Specific, answerable, and falsifiable.
+
+| Quality | Example |
+|---------|---------|
+| ❌ Too vague | "How does AI affect organisations?" |
+| ❌ Too broad | "What is the impact of technology on decision-making?" |
+| ✅ Specific | "How does the introduction of AI decision support change the weighting behaviour of expert panels in multi-criteria evaluation?" |
+
+### 2. Theoretical Framing
+
+Name the theory, cite the source, explain how it applies.
+
+| Quality | Example |
+|---------|---------|
+| ❌ Missing | "I'll look at decision-making." |
+| ❌ Name-dropped | "This uses prospect theory." |
+| ✅ Engaged | "Drawing on Kahneman and Tversky's (1979) prospect theory, I examine whether AI recommendations shift reference points in expert judgement, potentially amplifying loss aversion in high-stakes MCDM contexts." |
+
+### 3. Literature Context
+
+What existing work does this build on or challenge?
+
+| Quality | Example |
+|---------|---------|
+| ❌ Generic | "Many scholars have studied this." |
+| ✅ Specific | "While Bansal et al. (2021) examined AI advice-taking in individual decisions, and Sunstein (2019) analysed group polarisation, neither addresses how AI interacts with structured multi-criteria processes where criteria weights are elicited." |
+
+### 4. Contribution Claim
+
+What is genuinely new?
+
+| Quality | Example |
+|---------|---------|
+| ❌ Vague | "This fills a gap in the literature." |
+| ✅ Specific | "By embedding AI recommendations within a live AHP process, I isolate the mechanism through which AI shifts weight allocations — something prior work has theorised but not tested experimentally." |
+
+### 5. Scope Boundaries
+
+What are you explicitly NOT covering?
+
+**Example:** "Focus: expert panels in public sector procurement. Excluded: consumer-facing AI recommendations, autonomous systems without human oversight, non-MCDM decision frameworks."
+
+---
+
+## Depth Score
+
+Beyond the checklist, assess intellectual depth (0.0–1.0):
+
+### Depth Indicators (presence increases score)
+
+| Category | Markers |
+|----------|---------|
+| **Nuance** | "however", "although", "yet", "while", "despite", "conversely" |
+| **Critical thinking** | "gap", "limitation", "critique", "overlooked", "underexplored", "tension" |
+| **Engagement** | "argues", "suggests", "contends", "demonstrates", "challenges", "extends" |
+| **Theory** | "framework", "lens", "perspective", "mechanism", "construct", "typology" |
+| **Methodology** | "method", "approach", "design", "identification", "estimation", "measure" |
+
+### Scoring
+
+- Count markers per category
+- Normalise by word count (per 100 words)
+- Weight: Nuance (0.25), Critical thinking (0.25), Engagement (0.20), Theory (0.15), Methodology (0.15)
+- **Target:** depth_score ≥ 0.4
+
+### Interpretation
+
+| Score | Assessment |
+|-------|-----------|
+| < 0.2 | Generic — likely AI-generated or insufficiently developed |
+| 0.2–0.4 | Surface-level — needs more critical engagement |
+| 0.4–0.6 | Adequate — meets minimum for proceeding |
+| 0.6–0.8 | Strong — shows genuine intellectual engagement |
+| > 0.8 | Excellent — deep, nuanced, ready for synthesis |
+
+---
+
+## Red Flags
+
+Flag these phrases — they signal generic or AI-generated concepts:
+
+| Red Flag | Problem |
+|----------|---------|
+| "This paper will explore..." | Generic opener |
+| "In recent years..." | Filler, not specific |
+| "With the rise of..." | Cliché |
+| "The purpose of this research is to..." | Formulaic |
+| "fills a gap in the literature" | Overused claim without specificity |
+| "This is an important topic because..." | Assertion without evidence |
+| "Much has been written about..." | Vague attribution |
+
+**Response when detected:** "Your concept sounds generic. Use specific details from your reading to establish your voice and demonstrate genuine engagement with the literature."
+
+---
+
+## Validation Outcomes
+
+### ✅ PASS
+
+All requirements met, depth_score ≥ 0.4, no red flags (or red flags are minor).
+
+→ Proceed to literature synthesis or drafting.
+
+### ⚠️ REVISE
+
+1-2 requirements unmet or depth_score 0.2–0.4.
+
+→ Provide specific feedback on what to strengthen. Ask for revision before proceeding.
+
+### ❌ FAIL
+
+3+ requirements unmet or depth_score < 0.2.
+
+→ Concept is not ready. Suggest the user read more in the area, narrow the question, or identify a theoretical framework before returning.
+
+---
+
+## How Skills Use This
+
+### In `/literature` (before synthesis)
+
+1. Request concept plan from user
+2. Run validation checks
+3. If PASS → proceed to search and synthesis
+4. If REVISE/FAIL → return feedback, wait for revision
+
+
+1. Check if a validated concept exists (in project's `.planning/` or `CONCEPT.md`)
+2. If not → run validation gate before drafting
+3. If yes → use the concept to guide section structure
+
+### In review agents
+
+1. Check whether the paper's introduction meets concept validation standards
+2. A paper that would FAIL the concept gate has fundamental framing issues → flag as Critical

package/skills/shared/council-protocol.md

@@ -0,0 +1,265 @@
+# Council Protocol
+
+> Shared protocol for multi-model council mode. Any review agent or skill can opt into this by providing domain-specific system prompts and output formatting. This file defines the generic orchestration flow.
+>
+> **Included backend:** `cli-council` (local CLI tools, free with existing subscriptions). An optional API backend (`llm-council` via OpenRouter) is available separately — see below.
+
+## Core Concept: Cross-Model Agentic Invocation
+
+Claude Code can invoke other LLM providers' CLI tools as subprocess reviewers — a different model reviews work that Claude produced, providing genuine architectural diversity. The system is **extensible**: any CLI tool that accepts a prompt and returns text can be wrapped as a backend (~20 lines of Python following the `BackendSpec` pattern in `packages/cli-council/`). Available backends change as subscriptions change; the architecture does not.
+
+## What Council Mode Is
+
+Council mode coordinates this cross-model capability into a structured 3-stage deliberation:
+
+1. **Stage 1: Independent Assessments** — N models (typically 3, each from a different provider) independently evaluate the same artifact using the same instructions
+2. **Stage 2: Anonymised Peer Review** — each model evaluates the others' assessments without knowing which model produced which
+3. **Stage 3: Chairman Synthesis** — a chairman model reads everything and produces the final report
+
+The key insight: genuine model diversity (different architectures, training data, biases) surfaces issues that any single model — or even multiple instances of the same model — would miss.
+
+## Infrastructure
+
+### CLI Backend: `cli-council` (Included)
+
+Package: `packages/cli-council/`
+
+- `CouncilRunner` — orchestrator that invokes CLI backends via subprocess
+- Pluggable backends: `GeminiBackend`, `ClaudeBackend`, and a dormant `CodexBackend` (OpenAI subscription cancelled Mar 2026; resubscribing would restore it). New backends follow the same `BackendSpec` pattern.
+- `CouncilResult` — Pydantic models for text-based results
+- CLI — `python -m cli_council` for standalone use
+- Uses existing subscriptions — no per-token API costs
+- **Currently active backends:** Gemini (`gemini -p`), Claude (`claude -p`)
+- **Best for:** Ad-hoc reviews, research tasks, quick multi-perspective opinions
+
+### API Backend: `llm-council` (Optional, Separate Install)
+
+> Not included in this repo. Install separately: `pip install llm-council` or clone from GitHub.
+
+- `LLMClient` — generic async OpenRouter client with JSON/text chat and retry logic
+- `CouncilService` — 3-stage orchestration engine with customisable Stage 2/3 prompts
+- `CouncilResult` — Pydantic models for structured JSON results
+- CLI — `python -m llm_council` for standalone use
+- Requires `OPENROUTER_API_KEY` in the environment
+- **Best for:** Automated pipelines, structured JSON output, programmatic integration
+
+### Choosing a Backend
+
+| Factor | `cli-council` (included) | `llm-council` (separate) |
+|--------|--------------------------|--------------------------|
+| Cost | Subscription-included | Per-token (OpenRouter) |
+| Output format | Free-form text | Structured JSON |
+| Reliability | Variable (CLI output parsing) | High (API contracts) |
+| Speed | Slower (subprocess overhead) | Fast (parallel async HTTP) |
+| Model control | Whatever CLIs support | Full OpenRouter catalogue |
+| Offline | Partially (Claude -p works offline) | No |
+
+**Default:** Use `cli-council` (included and free). Use `llm-council` only if you need structured JSON output or are running in an automated pipeline.
+
+## When to Use
+
+- Pre-submission quality checks (high stakes)
+- When thoroughness matters more than speed
+- When the user explicitly requests "council mode", "council review", or "thorough review"
+- Never the default — standard single-reviewer mode remains the default for all consumers
+
+## Parallel Independent Review
+
+Beyond multi-model council mode, review agents can also be launched **in parallel** within a single Claude Code session for maximum coverage from different perspectives:
+
+1. **Pre-flight:** Launch `fatal-error-check` first (haiku model, ~15-30 seconds). If it returns FAIL, fix the fatal errors before proceeding.
+2. **Parallel launch:** If the pre-flight passes, launch all three review agents simultaneously in a **single message** with three Agent tool calls:
+   - `paper-critic` — adversarial LaTeX audit (grammar, notation, citation, tone, LaTeX, TikZ)
+   - `domain-reviewer` — substantive correctness (assumptions, derivations, citations, code-theory, backward logic)
+   - `referee2-reviewer` — full Reviewer 2 audit (identification, methods, robustness, presentation, scholarly rigour)
+3. **Synthesise:** Once all three agents return, run `/synthesise-reviews` to cross-reference issues, apply consensus escalation, and produce a unified `REVISION-PLAN.md`.
+
+This pattern maximises coverage by combining complementary review perspectives. Each agent has different check dimensions and catches different classes of issues. Parallel launch saves time compared to sequential runs.
+
+**When to use parallel review vs council mode:**
+
+| Scenario | Use |
+|----------|-----|
+| Maximum coverage from different review perspectives | Parallel independent review |
+| Model diversity (different LLM architectures finding different issues) | Council mode |
+| Both perspectives AND model diversity | Parallel review first, then council mode on the most Critical workstream |
+| Quick pre-submission check | Fatal-error-check only |
+
+## Prerequisites for a Consumer
+
+An agent or skill that supports council mode must provide:
+
+| What | Where | Purpose |
+|------|-------|---------|
+| **System prompt builder** | Consumer's `references/council-personas.md` | How to construct the system prompt sent to all models |
+| **Output formatter** | Consumer's `references/council-prompts.md` | Stage 3 chairman prompt template + output format |
+| **Council mode section** | Consumer's agent/skill body | Short section noting support + pointer to reference files |
+| **Trigger phrases** | Consumer's frontmatter description/examples | How the user activates council mode |
+
+## Orchestration Protocol
+
+The **main session** orchestrates council mode. Review agents cannot orchestrate themselves (they lack Bash). When council mode is triggered:
+
+### Pre-flight
+
+1. Run the consumer's standard pre-checks and hard gates
+2. If any gate fails, report immediately — do not invoke the council (save cost)
+3. Collect all source material (file contents, logs, rubrics) into a system prompt and user message
+4. Read the consumer's reference files for prompt construction guidance
+
+### Stage 1: Independent Assessments
+
+The main session invokes the `llm-council` package (via CLI or Python script). The library:
+
+1. Sends the system prompt + user message to N different LLM models via OpenRouter
+2. Each model independently produces a JSON assessment
+3. All calls are parallel (async)
+4. Failed models are logged and skipped — the council proceeds with available responses
+
+**Default models:** `anthropic/claude-sonnet-4.5`, `openai/gpt-5`, `google/gemini-2.5-pro`
+
+### Stage 2: Anonymised Peer Review
+
+The library automatically:
+
+1. Labels Stage 1 assessments as "Assessment A", "Assessment B", etc. (anonymised)
+2. Sends all assessments to each model for cross-evaluation
+3. Each model evaluates the others' work, identifies agreements/disagreements, and provides a ranking
+4. Rankings are parsed and aggregated
+
+**Model:** Same models as Stage 1 (each reviews the others' work).
+
+### Stage 3: Chairman Synthesis
+
+The library:
+
+1. Sends all assessments and peer reviews to the chairman model
+2. The chairman considers all inputs and produces a single synthesised response
+3. The response follows the consumer's required output schema
+
+**Default chairman:** `anthropic/claude-sonnet-4.5`
+
+### Write Output
+
+The main session receives the `CouncilResult` JSON and formats it into the consumer's standard output (e.g., `CRITIC-REPORT.md` for paper-critic). The report uses the consumer's standard format with two sections appended:
+
+```markdown
+## Council Notes
+
+### Agreement Summary
+- [N] issues confirmed by all reviewers
+- [N] issues confirmed by majority
+- [N] issues from single reviewer (validated in cross-review)
+- [N] disputed issues (marked [DISPUTED])
+
+### Aggregate Rankings
+| Assessment | Model | Avg Rank | Rankings Count |
+|------------|-------|----------|----------------|
+| Assessment A | [model name] | X.X | N |
+| Assessment B | [model name] | X.X | N |
+| Assessment C | [model name] | X.X | N |
+
+## Council Metadata
+- **Mode:** Council ([N] models + peer review + chairman)
+- **Models:** [list of model IDs used]
+- **Chairman:** [chairman model ID]
+- **Timing:** Stage 1: Xms, Stage 2: Xms, Stage 3: Xms, Total: Xms
+- **Date:** YYYY-MM-DD
+```
+
+These sections are appended **after** the consumer's standard report content. Downstream consumers (e.g., fixer agent) that parse only the standard sections are unaffected.
+
+## CLI Invocation
+
+### Option A: CLI Backend (`cli-council` — Included)
+
+For ad-hoc reviews using existing subscriptions (no API cost):
+
+```bash
+cd "packages/cli-council"
+uv run python -m cli_council \
+    --prompt-file /tmp/council-prompt.txt \
+    --context-file /tmp/council-context.txt \
+    --output /tmp/council-result.json \
+    --output-md /tmp/council-report.md \
+    --chairman claude \
+    --timeout 180
+```
+
+- Write the paper content / review instructions to `--context-file`, and the specific question to `--prompt-file`
+- Output is free-form text — the markdown report (`--output-md`) is usually more useful than JSON
+- The chairman backend defaults to `claude` (since we're already in Claude Code)
+
+### Option B: API Backend (`llm-council` — Separate Install)
+
+> Requires separate installation: `pip install llm-council` and an `OPENROUTER_API_KEY`.
+
+For structured JSON output and automated pipelines:
+
+```bash
+uv run python -m llm_council \
+    --system-prompt-file /tmp/council-system.txt \
+    --user-message-file /tmp/council-user.txt \
+    --models "anthropic/claude-sonnet-4.5,openai/gpt-5,google/gemini-2.5-pro" \
+    --chairman "anthropic/claude-sonnet-4.5" \
+    --output /tmp/council-result.json
+```
+
+For advanced cases (custom Stage 2/3 prompts), write a small Python script that imports `llm_council` and calls `CouncilService.run_council()` with `stage2_system` and `stage3_prompt_builder` parameters.
+
+## Issue Resolution Rules (Chairman)
+
+The consumer's chairman prompt should instruct the chairman to apply these rules:
+
+| Situation | Action |
+|-----------|--------|
+| Issue confirmed by 2+ models | Retain at the **highest** agreed severity |
+| Issue from 1 model, validated in peer review | Retain at the original severity |
+| Issue from 1 model, disputed in peer review | Retain with `[DISPUTED]` tag; chairman makes final severity call |
+| Issue found only in peer review (missed initially) | Add as a new finding |
+| Conflicting severity assessments | Chairman decides; notes the range in the issue description |
+
+**Scoring:** The chairman produces an independent score informed by all inputs — not a mechanical average.
+
+## Model Configuration
+
+| Parameter | Built-in Default | Override |
+|-----------|-----------------|---------|
+| Stage 1 models | `anthropic/claude-sonnet-4.5`, `openai/gpt-5`, `google/gemini-2.5-pro` | `--models` CLI flag or user config |
+| Chairman model | `anthropic/claude-sonnet-4.5` | `--chairman` CLI flag or user config |
+| Max tokens | 4096 | `--max-tokens` CLI flag |
+
+**User defaults** persist to `~/.config/llm-council/config.json` and override built-in defaults. Manage via `llm-council models --set-defaults` / `--set-chairman` / `--reset`, or interactively with `llm-council models --pricing` to review options first.
+
+The library's `config.py` contains the full model registry (17 models across Anthropic, OpenAI, Google) with tiers and live pricing.
+
+## Cost Considerations
+
+Council mode costs significantly more than standard mode because it calls N models for Stage 1, N models for Stage 2, and 1 model for Stage 3 (total: 2N+1 API calls). With 3 models:
+
+- **Standard mode:** 1 agent call (free — uses Claude Code context)
+- **Council mode:** 7 OpenRouter API calls (3 + 3 + 1)
+
+Pricing depends on the models chosen. Check OpenRouter for current rates. Use council mode when thoroughness justifies the cost — typically pre-submission or high-stakes reviews.
+
+## Persona Support (Optional)
+
+Each consumer can define **personas** in `references/council-personas.md` — distinct reviewer emphases that are prepended to the system prompt. Since council mode already uses different LLM providers (which bring natural perspective diversity), personas are optional but can add further differentiation.
+
+Current approach: the same system prompt goes to all models. Personas are documented as reference material describing what each model *tends to focus on* based on its architecture. Future extension: per-model system prompt variants via the library's API.
+
+## Consumers
+
+| Consumer | CLI (`cli-council`) | API (`llm-council`) | Notes |
+|----------|---------------------|---------------------|-------|
+| `paper-critic` | Supported | Implemented | First consumer — Technical Rigour, Presentation, Scholarly Standards personas |
+| `referee2-reviewer` | Supported | Supported | 5-audit protocol + council cross-review — highest-value consumer |
+| `domain-reviewer` | Supported | — | Math/assumption checking — different models catch different derivation gaps |
+| `proposal-reviewer` | Supported | — | Feasibility and novelty — different models have different domain knowledge |
+| `peer-reviewer` | Supported | — | Full paper review — the canonical use case for multi-model deliberation |
+| `multi-perspective` | Supported | — | Replaces Claude-only sub-agents with genuine model diversity |
+| `literature` | Implemented | — | Phase 2b (search) and Phase 7 (synthesis) — see skill definition |
+| `devils-advocate` | Supported | — | Round 1/2/3 played by different models for genuine adversarial tension |
+| `proofread` | Supported | — | Lower value — most useful for notation consistency and citation voice balance |
+| `code-review` | Supported | — | Most valuable for domain correctness and cross-language verification |
+| `bib-validate` | Supported | — | Different models have different bibliographic knowledge — catches metadata mismatches |

package/skills/shared/distribution-diagnostics.md

@@ -0,0 +1,164 @@
+# Distribution Diagnostics Before Model Selection
+
+> Shared reference for `/data-analysis` and review agents. Mandatory checks on dependent variables before selecting a statistical model. Prevents misspecification. Adapted from CommDAAF AgentAcademy protocol (Xu 2026).
+
+## Principle
+
+**Never run a regression without inspecting the DV distribution first.** OLS on count data, Poisson on overdispersed data, and linear models on zero-inflated outcomes all produce misleading results. Five minutes of diagnostics prevents weeks of wasted analysis.
+
+---
+
+## Mandatory Checks
+
+Run these on every dependent variable before model selection:
+
+| Diagnostic | What to compute | Why it matters |
+|-----------|----------------|----------------|
+| **Basic stats** | N, mean, median, SD, range | Understand the variable |
+| **Skewness** | `scipy.stats.skew(y)` or `moments::skewness(y)` | \|skew\| > 1 → OLS assumptions likely violated |
+| **Zero proportion** | `sum(y == 0) / N` | > 15% zeros → consider zero-inflated or hurdle models |
+| **Overdispersion** | `var(y) / mean(y)` | > 1.5 → Poisson is wrong, use Negative Binomial |
+| **Normality** | QQ-plot + Shapiro-Wilk (if N < 5000) | Formal test, but visual inspection matters more |
+| **Outliers** | IQR method or robust Mahalanobis distance | Extreme values can dominate OLS estimates |
+
+---
+
+## Model Selection Decision Tree
+
+```
+Is the DV a count (0, 1, 2, ...)?
+├── Yes → Check overdispersion (var/mean > 1.5?)
+│   ├── Yes → Check zero proportion (> 30%?)
+│   │   ├── Yes → Zero-inflated NB or Hurdle model
+│   │   └── No  → Negative Binomial
+│   └── No → Check zero proportion (> 30%?)
+│       ├── Yes → Zero-inflated Poisson
+│       └── No  → Poisson
+├── Is the DV a proportion or bounded [0, 1]?
+│   └── Yes → Beta regression (or fractional logit)
+├── Is the DV binary (0/1)?
+│   └── Yes → Logistic regression
+├── Is the DV ordinal (ordered categories)?
+│   └── Yes → Ordered logistic/probit
+└── Is the DV continuous?
+    └── Check skewness and normality of residuals
+        ├── Residuals ~normal → OLS
+        ├── Highly skewed DV → Log-transform, then OLS (report both)
+        └── Heavy tails → Robust regression or quantile regression
+```
+
+**Key rule:** Never use OLS on raw counts without explicit justification. Social media engagement, citation counts, survey response counts — these are almost never normally distributed.
+
+---
+
+## Effect Size Reporting
+
+### For count models (NB, Poisson): report Incidence Rate Ratios (IRR)
+
+| IRR | Interpretation |
+|-----|---------------|
+| 1.0 | No effect |
+| 1.2 | 20% increase |
+| 1.5 | 50% increase |
+| 2.0 | Double |
+| 0.5 | Half |
+
+**Always translate to practical meaning:** "Posts with frame X received 50% more engagement (IRR = 1.50, 95% CI [1.22, 1.84])" — not just "β = 0.41, p < 0.01".
+
+### For OLS: report standardised coefficients alongside raw
+
+Help readers judge magnitude, not just significance.
+
+### For logistic: report odds ratios AND predicted probabilities
+
+Odds ratios are hard to interpret. Show predicted probability at meaningful values of the IV.
+
+---
+
+## Multiple Testing
+
+When testing multiple predictors or outcomes:
+
+| Method | When to use |
+|--------|------------|
+| **Bonferroni** | Conservative; few tests (< 10) |
+| **Holm** | Less conservative; sequential rejection |
+| **FDR (Benjamini-Hochberg)** | Many tests (> 10); controls false discovery rate |
+
+**Always report both raw and adjusted p-values.** Let readers assess.
+
+---
+
+## Implementation
+
+### Python
+
+```python
+import numpy as np
+from scipy import stats
+
+def distribution_diagnostics(y, name="DV"):
+    """Run mandatory diagnostics before model selection."""
+    n = len(y)
+    skewness = stats.skew(y)
+    pct_zeros = np.sum(y == 0) / n * 100
+    var_mean = np.var(y) / np.mean(y) if np.mean(y) > 0 else float('inf')
+
+    diagnostics = {
+        'n': n, 'mean': np.mean(y), 'median': np.median(y),
+        'sd': np.std(y), 'skewness': skewness,
+        'pct_zeros': pct_zeros, 'var_mean_ratio': var_mean,
+    }
+
+    # Model recommendation
+    if pct_zeros > 30:
+        diagnostics['recommendation'] = 'Zero-inflated model or Hurdle'
+    elif var_mean > 1.5:
+        diagnostics['recommendation'] = 'Negative Binomial'
+    elif abs(skewness) > 1:
+        diagnostics['recommendation'] = 'Log-transform or GLM'
+    else:
+        diagnostics['recommendation'] = 'OLS (verify residuals)'
+
+    return diagnostics
+```
+
+### R
+
+```r
+distribution_diagnostics <- function(y, name = "DV") {
+  n <- length(y)
+  skew <- moments::skewness(y)
+  pct_zeros <- sum(y == 0) / n * 100
+  var_mean <- var(y) / mean(y)
+
+  cat(sprintf("=== %s (N=%d) ===\n", name, n))
+  cat(sprintf("Mean: %.3f | Median: %.3f | SD: %.3f\n", mean(y), median(y), sd(y)))
+  cat(sprintf("Skewness: %.3f | Zeros: %.1f%% | Var/Mean: %.3f\n", skew, pct_zeros, var_mean))
+
+  if (pct_zeros > 30) cat("→ Zero-inflated or Hurdle model\n")
+  else if (var_mean > 1.5) cat("→ Negative Binomial\n")
+  else if (abs(skew) > 1) cat("→ Log-transform or GLM\n")
+  else cat("→ OLS (verify residuals)\n")
+}
+```
+
+---
+
+## Integration
+
+### In `/data-analysis` Phase 1 (EDA)
+
+Run `distribution_diagnostics()` on every DV and key IVs before proceeding to estimation. If the diagnostics suggest a non-OLS model, flag this before the user locks their specification.
+
+### In review agents
+
+Check whether the paper reports distribution diagnostics or justifies model choice. A paper using OLS on count data without justification → flag as Major issue.
+
+### Validation tier interaction
+
+| Tier | Requirement |
+|------|------------|
+| 🟢 Exploratory | Run diagnostics, note recommendation |
+| 🟡 Pilot | Run diagnostics, justify model choice in notes |
+| 🔴 Publication | Run diagnostics, report in paper, compare 2+ model families |